viv/README.md

144 lines
4.9 KiB
Markdown
Raw Normal View History

2023-08-21 15:16:18 -05:00
<!-- badges -->
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![PYPI][pypi-shield]][pypi-url]
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com)
2023-08-29 10:50:48 -05:00
[![Conda][conda-shield]][conda-url]
2023-08-21 15:16:18 -05:00
2022-12-20 14:29:21 -06:00
<div align="center">
<a href="https://github.com/daylinmorgan/viv">
<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">
2023-06-02 14:08:54 -05:00
<h1> viv isn't venv </h1>
2022-12-20 14:29:21 -06:00
</p>
2023-06-02 14:08:54 -05:00
<div align="center">
<img
2023-08-21 10:01:09 -05:00
src="https://raw.githubusercontent.com/daylinmorgan/viv/main/assets/viv-help.svg"
2023-06-02 14:08:54 -05:00
alt="cli screenshot"
width="500"
>
</div>
2023-06-01 00:04:02 -05:00
<p align="center">
<a href="https://viv.dayl.in">Documentation</a>
</p>
2022-12-20 14:29:21 -06:00
</div>
2023-05-28 18:45:47 -05:00
2023-05-29 14:02:50 -05:00
Try before you buy!
```sh
python3 <(curl -fsSL viv.dayl.in/viv.py) run pycowsay -- "viv isn't venv\!"
2023-05-29 14:02:50 -05:00
```
---
2023-08-03 18:16:40 -05:00
`Viv` is a standalone dependency-free `venv` creator [^1].
`Viv` helps you ignore silly things like managing temporary or rarely used virtual environments,
while still unleashing the full power of python scripting with it's entire ecosystem at your disposal.
`Viv`'s uncompromising insistence on portability means that it will always:
1. only use the standard library
2. never exceed a single script.
2023-05-28 18:36:41 -05:00
2023-08-03 18:16:40 -05:00
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
Run the below command to install `viv`.
2022-12-20 10:21:42 -06:00
```sh
python3 <(curl -fsSL viv.dayl.in/viv.py) manage install
2022-12-20 10:21:42 -06: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
export PYTHONPATH="$PYTHONPATH:$HOME/.local/share/viv"
2022-12-19 23:17:43 -06:00
```
### Pypi (Not Recommended)
2022-12-19 23:17:43 -06:00
```sh
pip install viv
2022-12-19 23:17:43 -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
In any python script with external dependencies you can add this line,
to automate `vivenv` creation and installation of dependencies.
```python
2023-03-15 13:16:09 -05:00
__import__("viv").use("click")
```
To remove all `vivenvs` you can use the below command:
2022-12-19 23:17:43 -06:00
```sh
viv cache remove $(viv list -q)
2022-12-19 23:17:43 -06:00
```
2023-05-28 18:36:41 -05:00
To remove `viv` all together you can use the included `purge` command:
2023-05-28 18:36:41 -05:00
```sh
python3 <(curl -fsSL viv.dayl.in/viv.py) manage purge
```
2023-08-15 14:52:19 -05:00
## Equivalent commands from alternatives
2023-08-15 14:52:19 -05:00
### [pip-run](https://github.com/jaraco/pip-run)
2023-05-28 18:45:47 -05:00
2023-08-15 14:52:19 -05:00
```sh
pip-run cowsay -- -m cowsay "moove over, pip-run"
python3 <(curl -fsSL viv.dayl.in/viv.py) run cowsay -- "moove over, pip-run"
```
2023-05-28 18:45:47 -05:00
```sh
2023-08-15 14:52:19 -05:00
python -m pip-run requests -- -c "import requests; print(requests.get('https://pypi.org/project/pip-run').status_code)"
python -m viv requests -b python -- -c "import requests; print(requests.get('https://pypi.org/project/viv').status_code)"
2023-05-28 18:45:47 -05:00
```
2023-08-15 14:52:19 -05:00
### [pipx](https://github.com/pypa/pipx/)
2022-12-19 23:17:43 -06:00
2023-08-15 14:52:19 -05:00
```sh
pipx install pycowsay
viv shim pycowsay
```
```sh
2023-08-15 14:52:19 -05:00
pipx run https://gist.githubusercontent.com/cs01/fa721a17a326e551ede048c5088f9e0f/raw/6bdfbb6e9c1132b1c38fdd2f195d4a24c540c324/pipx-demo.py
python3 <(curl -fsSL viv.dayl.in/viv.py) run \
-s https://gist.githubusercontent.com/cs01/fa721a17a326e551ede048c5088f9e0f/raw/6bdfbb6e9c1132b1c38fdd2f195d4a24c540c324/pipx-demo.py
```
2023-08-15 14:52:19 -05:00
## Bonus: use `viv` with just standalone snippet (37LOC)
`--standalone` will auto-generate a mini function version of `viv` to accomplish the same basic task as using a local copy of `viv`.
After generating this 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.
`viv freeze` also supports `--standalone`
```sh
2023-08-15 14:52:19 -05:00
python3 <(curl -fsSL viv.dayl.in/viv.py) shim black -o ./black --standalone --freeze
```
2023-08-03 18:16:40 -05:00
2023-08-15 14:52:19 -05:00
2023-08-03 18:16:40 -05:00
[^1]: You do need to have `pip` but surely you have `pip` already.
2023-08-21 15:16:18 -05:00
2023-08-29 10:50:48 -05:00
[conda-shield]: https://img.shields.io/conda/vn/conda-forge/viv
[conda-url]: https://anaconda.org/conda-forge/viv
2023-08-21 15:16:18 -05:00
[pypi-shield]: https://img.shields.io/pypi/v/viv
[pypi-url]: https://pypi.org/project/viv
[stars-shield]: https://img.shields.io/github/stars/daylinmorgan/viv.svg
[stars-url]: https://github.com/daylinmorgan/viv/stargazers
[issues-shield]: https://img.shields.io/github/issues/daylinmorgan/viv.svg
[issues-url]: https://github.com/daylinmorgan/viv/issues
[license-shield]: https://img.shields.io/github/license/daylinmorgan/viv.svg
[license-url]: https://github.com/daylinmorgan/viv/blob/main/LICENSE