=== 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 pip-tools__ and Python's venv module (or uv__), 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/jazzband/pip-tools

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

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 zpy.rtfd.io__ for installation, explanation, and usage docs!

__ https://zpy.rtfd.io

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://zpy.readthedocs.io/en/latest/help_all/

__ https://zpy.readthedocs.io/en/latest/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

.. |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