Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/AndydeCleyre/zpy

Manage Python environments in Zsh, with uv or pip-tools
https://github.com/AndydeCleyre/zpy

completion pip-tools python uv venv zsh zsh-plugin

Last synced: 5 months ago
JSON representation

Manage Python environments in Zsh, with uv or pip-tools

Awesome Lists containing this project

README 

          
===

zpy

===

-------------------------------------------------------

Manage Python environments in Zsh, with uv or pip-tools

-------------------------------------------------------



|ghpages| |reqs-ci| |container-ci|



|container-alpine| |container-fedora| |container-ubuntu|



|repo| |docsite| |contact|



|logo|



``zpy`` is a set of Zsh functions

wrapping

or uv__, or

pip-tools__

and Python's venv module,

for the *simple* and *interactive* management of

Python **virtual environments**,

**dependency specifications**,

and **isolated Python app installations**.



None of them should get in your way.

All have **thorough tab completion**.



__ https://github.com/astral-sh/uv



__ https://github.com/jazzband/pip-tools



They can generally replace pipenv, poetry, pipx, pipsi, virtualenvwrapper, etc.



.. contents::



|zpy-completions|



Getting It

----------



The short version of installation:



- Install Python, Zsh, fzf__

- Source this repo's ``zpy.plugin.zsh`` in your ``.zshrc``, or use a Zsh plugin manager to add ``andydecleyre/zpy``



__ https://github.com/junegunn/fzf



Check out `the docs`__ for installation, explanation, and usage docs!



__ https://andydecleyre.github.io/zpy/



Examples

--------



- Install tools from PyPI or git, each with its own isolated venv:



  .. code:: console



    % pipz install uv tldr jello rich-cli yt-dlp 'visidata @ git+https://github.com/saulpw/visidata@develop'



- Create a venv for the current folder (if necessary), activate it, and **sync** installed pkgs to match *all* ``requirements.txt`` lockfiles:



  .. code:: console



    % envin



  . . . or sync packages to *particular* lockfiles:



  .. code:: console



    % envin dev-requirements.txt



- **Add** a pkg to ``requirements.in``, **compile** a locked dep tree as ``requirements.txt``, and **sync** installed packages:



  .. code:: console



    % pipacs beautifulsoup4



- **Compile** all ``(*-)requirements.in`` files, upgrading versions where possible, then **sync** to match:



  .. code:: console



    % pipcs -U



- Inject "loose" requirements (as written in ``requirements.in``) into ``pyproject.toml``:



  .. code:: console



    % pypc



There are about 25 user-facing functions in total.

For details,

see the reference__ and the short guide__.



__ https://andydecleyre.github.io/zpy/help_all/



__ https://andydecleyre.github.io/zpy/start/



They are also available as subcommands to the "supercommand" ``zpy``;

``envin`` is equivalent to ``zpy envin``, etc.



Basic usage of ``envin`` and ``pipacs``:



|envin-pipacs-gif|



Basic usage of ``pipz``:



|pipz-gif|



Try it in a Container

---------------------



Try it in isolation with docker or podman with one of these commands:



.. code:: console



  $ docker run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master

  $ podman run --net=host -it --rm -e TERM=$TERM quay.io/andykluger/zpy-ubuntu:master



Replace "ubuntu" with "alpine" or "fedora" if you prefer.



Guiding Ideas

-------------



.. image:: https://github.com/AndydeCleyre/zpy/raw/master/doc/src/img/flow.svg

   :alt: Information flow diagram

   :width: 100%



- You should not have to manually specify the dependencies anywhere other than

  ``*requirements.in`` files

- Folks who want to use your code shouldn't have to install any new-fangled

  less-standard tools (pipenv, poetry, pip-tools, zpy, etc.);

  ``pip install -r *requirements.txt`` ought to be sufficient

- It's nice to keep the venv folder *outside* of the project itself

- Not every manageable project *needs* a ``pyproject.toml`` or to be packaged

- Lockfiles are good

- Tab completion is wonderful



- These functions **don't**:



  - need to be used exclusively

  - need to be used by everyone on the same project

  - do what mise__/pyenv__/asdf-vm__ or flit__ do best (but do work with them if you choose)

  - *conflict* with anything else your team cares to do with your code;

    If they can be a friendlier neighbor to your workflows, file an issue__



__ https://github.com/jdx/mise



__ https://github.com/pyenv/pyenv



__ https://asdf-vm.com



__ https://flit.readthedocs.io/en/latest/



__ https://github.com/AndydeCleyre/zpy/issues



Known Issues

------------



Functions ``pipacs``, ``pipac``, ``pipcs``, and ``pipc`` allow forwarding arguments directly

to ``pip-compile``, or ``uv pip compile`` when ``uv`` is installed.



There are currently two problems with this when ``uv`` is used:



- Tab completion of those arguments, even when ``uv`` tab completions are installed, will fail.

  If it bothers you, please add a 👍 on

  `their existing issue`__.

- When the options passed are intended to override ones already passed internally,

  the command will fail.

  If this bothers you, please add a 👍 on

  `their existing issue`__.



__ https://github.com/astral-sh/uv/issues/3249



__ https://github.com/astral-sh/uv/issues/3248



.. |repo| image:: https://img.shields.io/github/size/andydecleyre/zpy/zpy.plugin.zsh?logo=github&label=Code&color=blueviolet

   :alt: Plugin file size in bytes

   :target: https://github.com/andydecleyre/zpy



.. |container-alpine| image:: https://img.shields.io/badge/Container-Quay.io-green?logo=alpine-linux

   :alt: Demo container - Alpine Linux

   :target: https://quay.io/repository/andykluger/zpy-alpine



.. |container-fedora| image:: https://img.shields.io/badge/Container-Quay.io-green?logo=red-hat

   :alt: Demo container - Fedora

   :target: https://quay.io/repository/andykluger/zpy-fedora



.. |container-ubuntu| image:: https://img.shields.io/badge/Container-Quay.io-green?logo=ubuntu

   :alt: Demo container - Ubuntu

   :target: https://quay.io/repository/andykluger/zpy-ubuntu



.. |container-ci| image:: https://github.com/AndydeCleyre/zpy/actions/workflows/ctnrs.yml/badge.svg?branch=develop

   :alt: Demo containers - GitHub Actions

   :target: https://github.com/AndydeCleyre/zpy/actions/workflows/ctnrs.yml



.. |reqs-ci| image:: https://github.com/AndydeCleyre/zpy/actions/workflows/reqs.yml/badge.svg

   :alt: Bump PyPI requirements - GitHub Actions

   :target: https://github.com/AndydeCleyre/zpy/actions/workflows/reqs.yml



.. |contact| image:: https://img.shields.io/badge/Contact-Telegram-blue?logo=telegram

   :alt: Contact developer on Telegram

   :target: https://t.me/andykluger



.. |docsite| image:: https://readthedocs.org/projects/zpy/badge/

   :alt: Documentation Status

   :target: https://zpy.readthedocs.io/en/latest/



.. |ghpages| image:: https://github.com/AndydeCleyre/zpy/actions/workflows/gh-pages.yml/badge.svg?branch=master

   :alt: Build GitHub Pages

   :target: https://andydecleyre.github.io/zpy/



.. |logo| image:: https://github.com/AndydeCleyre/zpy/blob/assets/zpy-logo.png?raw=true

   :alt: zpy logo

   :width: 160px



.. |zpy-completions| image:: https://user-images.githubusercontent.com/1787385/172661113-7a2c6670-e716-491e-8db4-c005fef8455b.png

   :alt: zpy supercommand completions

   :width: 800px



.. |envin-pipacs-gif| image:: https://github.com/AndydeCleyre/zpy/blob/assets/envin_pipacs.gif?raw=true

   :alt: Animated envin and pipacs demo

   :width: 800px



.. |pipz-gif| image:: https://github.com/AndydeCleyre/zpy/blob/assets/pipz.gif?raw=true

   :alt: Animated pipz demo

   :width: 800px