=== zpy

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

|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

Zpy

Install / Use

README