pip-deepfreeze

A simple pip freeze workflow for Python application developers.

About

pip-deepfreeze aims at doing one thing and doing it well, namely installing and pinning dependencies of Python applications (not libraries) in a virtual environment.

• It is easy to use.
• It is fast.
• It relies on the documented pip command line interface and its ubiquitous requirements file format.
• It assumes your project is configured using a PEP 517 compliant build backend but otherwise makes no assumption on the specific backend used.
• It is written in Python 3.6+, yet works in any virtual environment that has pip installed, including python 2.
• It is small, simple, with good test coverage and hopefully easy to maintain.

While pip-deepfreeze is functional already (see roadmap below), this is to be considered as alpha software for a little while, until we have gathered some feedback on the CLI options.

Installation

Using pipx (recommended):

pipx install pip-deepfreeze

Using pip:

pip install --user pip-deepfreeze

It is not recommended to install pip-deepfreeze in the same environment as your application, so its dependencies do not interfere with your app. By default it works with the python found in your PATH (which does what you normally expect in an activated virtualenv), but you can ask it to work within another environment using the --python option.

Quick start

Make sure your application declares its dependencies using setuptools (via the install_requires key in setup.py or setup.cfg), or any other compliant PEP 517 build backend such as flit.

Create and activate a virtual environment.

Install your project in editable mode in the active virtual environment:

pip-df sync

or, if your project does not support editable installs:

pip-df sync --no-editable

If you don't have one yet, this will generate a file named requirements.txt, containing the exact version of all your application dependencies, as they were installed.

When you add or remove dependencies of your project (via setup.py or favorite build backend configuration), run pip-df sync again to update your environment and requirements.txt.

To update one or more dependencies to the latest allowed version, run:

pip-df sync --update DEPENDENCY1 --update DEPENDENCY2 ...

How to

(TODO)

• Initial install (create a venv, and run pip-df sync which will install and generate requirements.txt)
• Add pip options (--find-links, --extra-index-url, etc: in requirements.txt.in)
• Add a dependency that is published in an index or accessible via --find-links (add it in setup.py)
• Install dependencies from direct URLs such as git (add it in setup.py and add the git reference in requirements.txt.in)
• Remove a dependency (remove it from setup.py)
• Update a dependency to the most recent version (pip-df sync --update DEPENDENCY1 --update DEPENDENCY2)
• Update all dependencies to the latest version (pip-df sync --update-all or remove requirements.txt and run pip-df sync)
• Deploy my project (pip wheel --no-deps requirements.txt -e . --wheel-dir=release, ship the release directory then run pip install --no-index release/*.whl).

CLI reference

Global options:

Usage: pip-df [OPTIONS] COMMAND [ARGS]...

  A simple pip freeze workflow for Python application developers.

Options:
  --python PYTHON       [default: python]
  -v, --verbose         [default: False]
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or
                        customize the installation.

  --help                Show this message and exit.

Commands:
  sync

sync command options:

Usage: pip-df sync [OPTIONS]

Options:
  -u, --update DEPENDENCY     Make sure DEPENDENCY is upgraded (or downgraded)
                              to the latest allowed version. If DEPENDENCY is
                              not part of your application dependencies
                              anymore, this option has no effect. This option
                              can be repeated.

  --update-all                Upgrade (or downgrade) all dependencies of your
                              application to the latest allowed version.

  --editable / --no-editable  Install the project in editable mode.  [default:
                              True]

  --help                      Show this message and exit.

Roadmap

• Stabilize CLI options.
• Better UX if the project does not support editable installs (install in editable mode if possible, with automatic fallback to non-editable mode).
• Optionally uninstall unneeded dependencies.
• Support extras (e.g. for a test extra, we would have requirements-test.txt which includes requirements.txt and optionally requirements-test.txt.in).
• Support different target environements for the same project (e.g. different python versions, which may result in different packages being installed). Is this actually useful in practice ?

Development

To run tests, use tox. You will get a test coverage report in htmlcov/index.html. An easy way to install tox is pipx install tox.

This project uses pre-commit to enforce linting (among which black for code formating, isort for sorting imports, and mypy for type checking).

To make sure linters run locally on each of your commits, install pre-commit (pipx install pre-commit is recommended), and run pre-commit install in your local clone of the pip-deepfreeze repository.