From 8bc81aaf70708c1481d5ba4f14192a5b94af5609 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Thu, 15 Feb 2024 09:54:29 -0500 Subject: [PATCH] Update README (#1307) --- README.md | 73 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 01b92f140..70721f52b 100644 --- a/README.md +++ b/README.md @@ -7,17 +7,19 @@ [![Actions status](https://github.com/astral-sh/puffin/workflows/CI/badge.svg)](https://github.com/astral-sh/puffin/actions) [![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/astral-sh) -An extremely fast Python package installer and resolver, written in Rust. Designed as a drop-in replacement for `pip` and `pip-compile`. +An extremely fast Python package installer and resolver, written in Rust. Designed as a drop-in +replacement for `pip` and `pip-compile`. Puffin is backed by [Astral](https://astral.sh), the creators of [Ruff](https://github.com/astral-sh/ruff). ## Highlights - ⚖️ Drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. -- ⚡️ 10-100x faster than `pip` and `pip-tools` (`pip-compile` and `pip-sync`). +- ⚡️ [10-100x faster](https://github.com/astral-sh/puffin/blob/main/BENCHMARKS.md) than `pip` + and `pip-tools` (`pip-compile` and `pip-sync`). - 💾 Disk-space efficient, with a global cache for dependency deduplication. -- 🐍 Installable via `pip`, `pipx`, `brew` etc. Puffin is a static binary that can be installed without Rust or - Python. +- 🐍 Installable via `curl`, `pip`, `pipx`, etc. Puffin is a static binary that can be installed + without Rust or Python. - 🧪 Tested at-scale against the top 10,000 PyPI packages. - 🖥️ Support for macOS, Linux, and Windows. - 🧰 Novel features such as [dependency version overrides](#dependency-overrides) and @@ -29,13 +31,23 @@ Puffin is backed by [Astral](https://astral.sh), the creators of [Ruff](https:// ## Getting Started -Puffin is available as [`puffin`](https://pypi.org/project/puffin/) on PyPI: +Install Puffin with our standalone installers, or from [PyPI](https://pypi.org/project/puffin/): ```shell +# On macOS and Linux. +curl -LsSf https://astral.sh/puffin/install.sh | sh + +# On Windows. +irm https://astral.sh/puffin/install.ps1 | iex + +# With pip. +pip install puffin + +# With pipx. pipx install puffin ``` -To create a virtual environment with Puffin: +To create a virtual environment: ```shell puffin venv # Create a virtual environment at .venv. @@ -56,7 +68,7 @@ puffin pip compile pyproject.toml -o requirements.txt # Read a pyproject.toml puffin pip compile requirements.in -o requirements.txt # Read a requirements.in file. ``` -To install a set of locked dependencies into the virtual environment: +To sync a set of locked dependencies with the virtual environment: ```shell puffin pip sync requirements.txt # Install from a requirements.txt file. @@ -66,28 +78,10 @@ Puffin's `pip-install` and `pip-compile` commands supports many of the same comm as existing tools, including `-r requirements.txt`, `-c constraints.txt`, `-e .` (for editable installs), `--index-url`, and more. -## Roadmap - -Puffin is an extremely fast Python package resolver and installer, designed as a drop-in -replacement for `pip` and `pip-tools` (`pip-compile` and `pip-sync`). - -Puffin is not a complete package manager. Instead, it represents an intermediary goal in our -pursuit of a "Cargo for Python": a Python package and project manager that is extremely fast, -reliable, and easy to use — a single tool capable of unifying not only `pip` and `pip-tools`, but -also `pipx`, `virtualenv`, `tox`, `setuptools`, `poetry`, `pyenv`, `rye`, and more. - -In the future, Puffin will be used as the foundation for such a tool: a single binary that -bootstraps your Python installation and gives you everything you need to be productive with Python. - -In the meantime, though, Puffin's narrower 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-compile`. - ## Limitations -Puffin does not support the entire `pip` feature set. Namely, Puffin does not plan to support the -following `pip` features: +Puffin does not support the entire `pip` feature set. Namely, Puffin does not (and does not plan to) +support the following `pip` features: - `.egg` dependencies - Editable installs for Git and direct URL dependencies (editable installs _are_ supported for local @@ -103,6 +97,24 @@ Like `pip-compile`, Puffin generates a platform-specific `requirements.txt` file `poetry` and `pdm`, which generate platform-agnostic `poetry.lock` and `pdm.lock` files). As such, Puffin's `requirements.txt` files may not be portable across platforms and Python versions. +## Roadmap + +Puffin is an extremely fast Python package resolver and installer, designed as a drop-in +replacement for `pip`, `pip-tools` (`pip-compile` and `pip-sync`), and `virtualenv`. + +Puffin represents an intermediary goal in our pursuit of a ["Cargo for Python"](https://blog.rust-lang.org/2016/05/05/cargo-pillars.html#pillars-of-cargo): +a comprehensive project and package manager that is extremely fast, reliable, and easy to use. + +Think: a single binary that bootstraps your Python installation and gives you everything you need to +be productive with Python, bundling not only `pip`, `pip-tools`, and `virtualenv`, but also `pipx`, +`tox`, `poetry`, `pyenv`, `ruff`, and more. + +Our goal is to evolve Puffin into such a tool. + +In the meantime, though, the narrower `pip-tools` scope allows us to solve the low-level problems +involved in building such a tool (like package installation) while shipping something immediately +useful with minimal barrier to adoption. + ## Advanced Usage ### Python discovery @@ -161,8 +173,9 @@ The specifics of Puffin's caching semantics vary based on the nature of the depe If you're running into caching issues, Puffin includes a few escape hatches: -- To force Puffin to ignore cached data for all dependencies, run `puffin pip install --reinstall ...`. -- To force Puffin to ignore cached data for a specific dependency, run, e.g., `puffin pip install --reinstall-package flask ...`. +- To force Puffin to revalidate cached data for all dependencies, run `puffin pip install --refresh ...`. +- To force Puffin to revalidate cached data for a specific dependency, run, e.g., `puffin pip install --refresh-package flask ...`. +- To force Puffin to ignore existing installed versions, run `puffin pip install --reinstall ...`. - To clear the global cache entirely, run `puffin clean`. ### Resolution strategy @@ -286,7 +299,7 @@ Puffin has Tier 1 support for the following platforms: Puffin is continuously built, tested, and developed against its Tier 1 platforms. Inspired by the Rust project, Tier 1 can be thought of as ["guaranteed to work"](https://doc.rust-lang.org/beta/rustc/platform-support.html). -Puffin has Tier 2 support ("guaranteed to build") for the following platforms: +Puffin has Tier 2 support (["guaranteed to build"](https://doc.rust-lang.org/beta/rustc/platform-support.html)) for the following platforms: - Linux (PPC64) - Linux (PPC64LE)