From 0e40aeb15d77dfc5c7a99d10edfa3222bf9f41eb Mon Sep 17 00:00:00 2001 From: Daylin Morgan Date: Sun, 28 May 2023 18:36:41 -0500 Subject: [PATCH] docs: update README/example --- README.md | 63 ++++++++++++++++---------------------------------- examples/black | 45 ++++++++++++++++++++++-------------- 2 files changed, 48 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 50f0329..3f94235 100644 --- a/README.md +++ b/README.md @@ -9,16 +9,9 @@


- --- -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`. - -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 --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 +```sh +python3 <(curl -fsSL gh.dayl.in/viv/viv.py) manage purge ``` ## Alternatives diff --git a/examples/black b/examples/black index 5687e8b..b4ceb9d 100755 --- a/examples/black +++ b/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( - subprocess.run( - [ - vivenv.path / "bin" / "black", - *sys.argv[1:], - ] - ).returncode - ) + sys.exit(subprocess.run([vivenv / "bin" / "black", *sys.argv[1:]]).returncode)