docs: update README/example

README.md

@@ -9,16 +9,9 @@
   </p>
 </div>
 <br />
-
 ---
 
-Python is a great choice to quickly prototype or accomplish small tasks in scripts.
-However, leveraging it's vast ecosystem can be tedious for one-off or rarely used scripts.
-This is were `viv` comes in handy.
-
 `Viv` is a standalone dependency-free `venv` creator.
-It is meant to be invoked in any script that has third-party dependencies,
-prior to loading of any of the external modules.
 
 These `venvs` can be identified by name or by their specification.
 In any case they will be re-used across scripts (and generated on-demand, if needed).
@@ -26,6 +19,10 @@ In any case they will be re-used across scripts (and generated on-demand, if nee
 **Importantly**, `viv` will also remove your user site directory.
 (view with: `python -m 'import site;print(site.USER_SITE)'`).
 
+`Viv`'s uncompromising insistence on portability means that it will always (1) only use the standard library (2) never exceed a single script.
+
+For that reason any usage of the `CLI` can be accomplished using a remote copy as seen in the below install command.
+
 ## Setup
 
 Run the below command to install `viv`.
@@ -46,6 +43,19 @@ the module just needs to be recognized at run time
 and the single script [`viv.py`](https://github.com/daylinmorgan/viv/blob/main/src/viv/viv.py) can be invoked directly for the CLI.
 How you accomplish these options is ultimately up to you but the above instructions can get you started.
 
+## Additional Features
+
+An experimental feature of `viv` is generating shim's that leverage the principles of `viv`.
+These shims would operate similar to `pipx` in which you can specify a command line app to "install".
+
+*Note* that `--standalone` will auto-generate a code-golfed minified version of `viv` to accomplish the same basic task as using a local copy of `viv`.
+After generating this a standalone `shim` you can freely use this script across unix machines which have `python>3.8`.
+See [examples/black](https://github.com/daylinmorgan/viv/blob/dev/examples/black) for output of below command.
+
+```sh
+python3 <(curl -fsSL gh.dayl.in/viv/viv.py) shim black -o ./black --standalone --freeze
+```
+
 ### Pypi (Not Recommended)
 
 ```sh
@@ -70,43 +80,10 @@ To remove all `vivenvs` you can use the below command:
 viv remove $(viv list -q)
 ```
 
-# Standalone Viv
+To remove `viv` all together you can use the included `purge` command:
 
-Supposing you want to increase the portability of your script while still employing the principles of `viv`.
+```sh
-
+python3 <(curl -fsSL gh.dayl.in/viv/viv.py) manage purge
-The below function can be freely pasted at the top of your scripts and requires
-no modification of your PYTHONPATH or import of additional modules (including downloading/installing `viv`).
-
-It can be auto-generated with for example: `viv freeze <spec> --standalone`.
-
-The only part necessary to modify if copied verbatim from below is the call to `_viv_use`.
-
-Output of `viv freeze rich --standalone`:
-
-```python
-# <<<<< auto-generated by daylinmorgan/viv (v22.12a3-35-g0d0c66d-dev)
-# fmt: off
-def _viv_use(*pkgs: str, track_exe: bool = False, name: str = "") -> None:                                    # noqa
-    i,s,m,e,spec=__import__,str,map,lambda x: True if x else False,[*pkgs]                                    # noqa
-    if not {*m(type,pkgs)}=={s}: raise ValueError(f"spec: {pkgs} is invalid")                                 # noqa
-    ge,sys,P,ew=i("os").getenv,i("sys"),i("pathlib").Path,i("sys").stderr.write                               # noqa
-    (cache:=(P(ge("XDG_CACHE_HOME",P.home()/".cache"))/"viv"/"venvs")).mkdir(parents=True,exist_ok=True)      # noqa
-    ((sha256:=i("hashlib").sha256()).update((s(spec)+                                                         # noqa
-     (((exe:=("N/A",s(P(i("sys").executable).resolve()))[e(track_exe)])))).encode()))                         # noqa
-    if (env:=cache/(name if name else (_id:=sha256.hexdigest()))) not in cache.glob("*/") or ge("VIV_FORCE"): # noqa
-        v=e(ge("VIV_VERBOSE"));ew(f"generating new vivenv -> {env.name}\n")                                   # noqa
-        i("venv").EnvBuilder(with_pip=True,clear=True).create(env)                                            # noqa
-        with (env/"pip.conf").open("w") as f:f.write("[global]\ndisable-pip-version-check=true")              # noqa
-        if (p:=i("subprocess").run([env/"bin"/"pip","install","--force-reinstall",*spec],text=True,           # noqa
-            stdout=(-1,None)[v],stderr=(-2,None)[v])).returncode!=0:                                          # noqa
-            if env.is_dir():i("shutil").rmtree(env)                                                           # noqa
-            ew(f"pip had non zero exit ({p.returncode})\n{p.stdout}\n");sys.exit(p.returncode)                # noqa
-        with (env/"viv-info.json").open("w") as f:                                                            # noqa
-            i("json").dump({"created":s(i("datetime").datetime.today()),"id":_id,"spec":spec,"exe":exe},f)    # noqa
-    sys.path = [p for p in (*sys.path,s(*(env/"lib").glob("py*/si*"))) if p!=i("site").USER_SITE]             # noqa
-_viv_use("markdown-it-py==2.2.0", "mdurl==0.1.2", "Pygments==2.14.0", "rich==13.3.2")                         # noqa
-# fmt: on
-# >>>>> code golfed with <3
 ```
 
 ## Alternatives

examples/black

@@ -1,20 +1,38 @@
 #!/usr/bin/env python3
-"""
-Proof of concept output for a 'shim generator'
-that would essentially emulate pipx
 
-A possible cli signature
 
-viv shim black -o ~/bin/black
+# <<<<< auto-generated by viv (v23.5a2-2-gebb657c-dev)
-"""
+# see `python3 <(curl -fsSL gh.dayl.in/viv/viv.py) --help`
+# fmt: off
+def _viv_use(*pkgs, track_exe=False, name=""):                                                      # noqa
+    T,F=True,False;i,s,m,e,spec=__import__,str,map,lambda x: T if x else F,[*pkgs]                  # noqa
+    if not {*m(type,pkgs)}=={s}: raise ValueError(f"spec: {pkgs} is invalid")                       # noqa
+    ge,sys,P,ew=i("os").getenv,i("sys"),i("pathlib").Path,i("sys").stderr.write                     # noqa
+    (cache:=(P(ge("XDG_CACHE_HOME",P.home()/".cache"))/"viv"/"venvs")).mkdir(parents=T,exist_ok=T)  # noqa
+    ((sha256:=i("hashlib").sha256()).update((s(spec)+                                               # noqa
+     (((exe:=("N/A",s(P(i("sys").executable).resolve()))[e(track_exe)])))).encode()))               # noqa
+    if ((env:=cache/(name if name else (_id:=sha256.hexdigest())))                                  # noqa
+        not in cache.glob("*/")) or ge("VIV_FORCE"):                                                # noqa
+        v=e(ge("VIV_VERBOSE"));ew(f"generating new vivenv -> {env.name}\n")                         # noqa
+        i("venv").EnvBuilder(with_pip=T,clear=T).create(env)                                        # noqa
+        with (env/"pip.conf").open("w") as f:f.write("[global]\ndisable-pip-version-check=true")    # noqa
+        if (p:=i("subprocess").run([env/"bin"/"pip","install","--force-reinstall",*spec],text=True, # noqa
+            stdout=(-1,None)[v],stderr=(-2,None)[v])).returncode!=0:                                # noqa
+            if env.is_dir():i("shutil").rmtree(env)                                                 # noqa
+            ew(f"pip had non zero exit ({p.returncode})\n{p.stdout}\n");sys.exit(p.returncode)      # noqa
+        with (env/"viv-info.json").open("w") as f:                                                  # noqa
+            i("json").dump({"created":s(i("datetime").datetime.today()),                            # noqa
+            "id":_id,"spec":spec,"exe":exe},f)                                                      # noqa
+    sys.path = [p for p in (*sys.path,s(*(env/"lib").glob("py*/si*"))) if p!=i("site").USER_SITE]   # noqa
+    return env                                                                                      # noqa
+# fmt: on
+# >>>>> code golfed with <3
 
 import subprocess
 import sys
 
-import viv
-
 if __name__ == "__main__":
-    vivenv = viv.use(
+    vivenv = _viv_use(
         "black==23.3.0",
         "click==8.1.3",
         "mypy-extensions==1.0.0",
@@ -22,11 +40,4 @@ if __name__ == "__main__":
         "pathspec==0.11.1",
         "platformdirs==3.5.1",
     )
-    sys.exit(
+    sys.exit(subprocess.run([vivenv / "bin" / "black", *sys.argv[1:]]).returncode)
-        subprocess.run(
-            [
-                vivenv.path / "bin" / "black",
-                *sys.argv[1:],
-            ]
-        ).returncode
-    )