AndydeCleyre/zpy — 98 Stars

Topics

#completion #pip-tools #python #uv #venv #zsh #zsh-plugin

Language breakdown

Shell 100.0%

▸ Files click to expand

README

=== 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/helpall/
__ 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

🔗 More in this category