2023-05-26 19:13:23 -05:00
# viv
2022-12-20 14:29:21 -06:00
< div align = "center" >
< a href = "https://github.com/daylinmorgan/viv" >
2023-05-26 19:13:23 -05:00
< img src = "https://raw.githubusercontent.com/daylinmorgan/viv/main/assets/logo.svg" alt = "Logo" width = 500 >
2022-12-20 14:29:21 -06:00
< / a >
< p align = "center" >
viv isn't venv
< / p >
< / div >
2023-05-28 18:45:47 -05:00
2023-05-29 14:02:50 -05:00
Try before you buy!
```sh
2023-05-31 10:54:53 -05:00
python3 < (curl -fsSL viv.dayl.in/viv.py) run pycowsay -- "viv isn't venv\!"
2023-05-29 14:02:50 -05:00
```
2023-03-09 14:58:01 -06:00
---
`Viv` is a standalone dependency-free `venv` creator.
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).
2023-05-26 19:13:23 -05:00
**Importantly**, `viv` will also remove your user site directory.
(view with: `python -m 'import site;print(site.USER_SITE)'` ).
2023-03-09 14:58:01 -06:00
2023-05-28 18:36:41 -05:00
`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.
2022-12-19 23:17:43 -06:00
## Setup
2022-12-20 10:21:42 -06:00
2023-05-26 19:13:23 -05:00
Run the below command to install `viv` .
2022-12-20 10:21:42 -06:00
```sh
2023-05-31 10:54:53 -05:00
python3 < (curl -fsSL viv.dayl.in/viv.py) manage install
2022-12-20 10:21:42 -06:00
```
2023-05-26 19:13:23 -05:00
To access `viv` from within scripts you should add it's location to your `PYTHONPATH` .
By default `viv` will be installed to `$XDG_DATA_HOME/viv` or `~/.local/share/viv` you can customize this with `--src` .
2022-12-19 23:17:43 -06:00
```sh
2023-05-26 19:13:23 -05:00
export PYTHONPATH="$PYTHONPATH:$HOME/.local/share/viv"
2022-12-19 23:17:43 -06:00
```
2023-03-09 14:58:01 -06:00
Advanced users may recognize that principally,
the module just needs to be recognized at run time
2023-05-28 17:39:33 -05:00
and the single script [`viv.py` ](https://github.com/daylinmorgan/viv/blob/main/src/viv/viv.py ) can be invoked directly for the CLI.
2023-03-09 14:58:01 -06:00
How you accomplish these options is ultimately up to you but the above instructions can get you started.
2023-03-08 03:43:07 -06:00
### Pypi (Not Recommended)
2022-12-19 23:17:43 -06:00
2023-03-08 03:43:07 -06:00
```sh
pip install viv
2022-12-19 23:17:43 -06:00
```
2023-03-09 14:58:01 -06:00
Why is this *not recommended* ? Mainly, because `viv` is all about hacking your `sys.path` .
Placing it in it's own virtual environment or installing in a user site directory may complicate this endeavor.
2022-12-19 23:17:43 -06:00
## Usage
2023-03-09 14:58:01 -06:00
In any python script with external dependencies you can add this line,
to automate `vivenv` creation and installation of dependencies.
2023-03-08 03:43:07 -06:00
```python
2023-03-15 13:16:09 -05:00
__import__("viv").use("click")
2023-03-08 03:43:07 -06:00
```
2023-05-26 19:13:23 -05:00
To remove all `vivenvs` you can use the below command:
2023-03-09 14:58:01 -06:00
2022-12-19 23:17:43 -06:00
```sh
viv remove $(viv list -q)
```
2023-05-28 18:36:41 -05:00
To remove `viv` all together you can use the included `purge` command:
2023-03-08 03:43:07 -06:00
2023-05-28 18:36:41 -05:00
```sh
2023-05-31 10:54:53 -05:00
python3 < (curl -fsSL viv.dayl.in/viv.py) manage purge
2023-03-08 03:43:07 -06:00
```
2023-05-28 18:45:47 -05:00
## 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
2023-05-31 10:54:53 -05:00
python3 < (curl -fsSL viv.dayl.in/viv.py) shim black -o ./black --standalone --freeze
2023-05-28 18:45:47 -05:00
```
2022-12-19 23:17:43 -06:00
## Alternatives
2023-03-08 03:43:07 -06:00
### [pip-run](https://github.com/jaraco/pip-run)
```sh
pip-run (10.0.5)
├── autocommand (2.2.2)
├── jaraco-context (4.3.0)
├── jaraco-functools (3.6.0)
│ └── more-itertools (9.1.0)
├── jaraco-text (3.11.1)
│ ├── autocommand (2.2.2)
│ ├── inflect (6.0.2)
│ │ └── pydantic>=1.9.1 (1.10.5)
│ │ └── typing-extensions>=4.2.0 (4.5.0)
│ ├── jaraco-context>=4.1 (4.3.0)
│ ├── jaraco-functools (3.6.0)
│ │ └── more-itertools (9.1.0)
│ └── more-itertools (9.1.0)
├── more-itertools>=8.3 (9.1.0)
├── packaging (23.0)
├── path>=15.1 (16.6.0)
├── pip>=19.3 (23.0.1)
└── platformdirs (3.1.0)
```
### [pipx](https://github.com/pypa/pipx/)
```sh
pipx (1.1.0)
├── argcomplete>=1.9.4 (2.1.1)
├── packaging>=20.0 (23.0)
└── userpath>=1.6.0 (1.8.0)
└── click (8.1.3)
```