diff --git a/README.md b/README.md index ab1c7a598..17f6f8b6a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,39 @@ # `puffin` -An experimental Python package manager. +An experimental Python packaging tool. + +## Motivation + +Puffin is an extremely fast (experimental) Python package resolver and installer, intended to +replace `pip` and `pip-tools` (`pip-compile` and `pip-sync`). + +Puffin itself is not a complete "package manager", but rather a tool for locking dependencies +(similar to `pip-compile`) and installing them (similar to `pip-sync`). Puffin can be used to +generate a set of locked dependencies from a `requirements.txt` file, and then install those +locked dependencies into a virtual environment. + +Puffin represents an intermediary goal in our pursuit of building a "Cargo for Python": a Python +package manager that is extremely fast, reliable, and easy to use -- capable of replacing not only +`pip`, but also `pipx`, `pip-tools`, `virtualenv`, `tox`, `setuptools`, and even `pyenv`, by way of +managing the Python installation itself. + +Puffin's limited scope allows us to solve many of the low-level problems that are required to +build such a package manager (like package installation) while shipping an immediately useful tool +with a minimal barrier to adoption. Try it today in lieu of `pip` and `pip-tools`. + +## Limitations + +Puffin does not yet support: + +- Source distributions +- VCS dependencies +- URL dependencies +- Uninstalling packages +- ... + +Like `pip-compile`, Puffin generates a platform-specific `requirements.txt` file (unlike, e.g., +`poetry`, which generates a platform-agnostic `poetry.lock` file). As such, Puffin's +`requirements.txt` files are not portable across platforms and Python versions. ## Usage @@ -16,6 +49,23 @@ To install from a resolved `requirements.txt` file: cargo run -p puffin-cli -- sync requirements.txt ``` +For more, see `cargo run -p puffin-cli -- --help`: + +```text +Usage: puffin-cli + +Commands: + compile Compile a `requirements.in` file to a `requirements.txt` file + sync Sync dependencies from a `requirements.txt` file + clean Clear the cache + freeze Enumerate the installed packages in the current environment + help Print this message or the help of the given subcommand(s) + +Options: + -h, --help Print help + -V, --version Print version +``` + ## Benchmarks ### Resolution