docs: rewrite Package Management category intro

The intro predated the audit and never mentioned poetry-core, which the README now lists.

Co-Authored-By: Claude <noreply@anthropic.com>

website/data/category_intros/package-management.md

@@ -1,33 +1,34 @@
-Whatever you need from PyPI, uv installs and locks it, and uv-build packages pure Python. Conda is more than a Python package manager: it handles any language.
+uv manages your project with a lockfile, and doubles as a Python package manager. Its uv-build backend packages pure-Python code with reasonable defaults.
 
 How to choose:
 
-- A project's dependencies, lockfile, and Python versions: uv
-- Packaging a pure-Python project: uv-build
-- Non-Python dependencies, like C libraries or R: conda
-- Nothing beyond what ships with Python: pip
-- A project already on Poetry: Poetry
-- Tests across several Python versions: Hatch
-- Command-line apps, each in its own environment: pipx
+- A new project, from installing Python to locking dependencies: uv
+- Packaging pure-Python code in a uv project: uv-build
+- Installing packages with only what ships with Python: pip
+- A project already on Poetry, or one that relies on its plugins: Poetry
+- Tests across a matrix of Python versions: Hatch
+- Command-line apps, each in its own environment: pipx, or `uv tool` on uv
+- Scientific stacks with non-Python libraries: conda
 - C or C++ extension modules: setuptools
-- Build hooks or a flexible project layout: Hatchling
+- Build hooks, or a layout uv-build doesn't expect: Hatchling
+- Building a Poetry project without Poetry installed: poetry-core
 
-uv is one tool for [your project's dependencies, lockfile, and Python versions](https://docs.astral.sh/uv/), and it covers what you'd otherwise use pip, pipx, and Poetry for. Start with `uv init`, add dependencies with `uv add`, and run your code with `uv run`, which [syncs the environment with the lockfile](https://docs.astral.sh/uv/guides/projects/#running-commands) first. Its `uv pip` commands are meant [for projects not ready to move away from pip](https://docs.astral.sh/uv/pip/).
+uv is [a single tool](https://docs.astral.sh/uv/) for Python versions, virtual environments, dependencies, and command-line tools. Start a project with `uv init`, add packages with `uv add`, and run code with `uv run`, which [checks that the lockfile and environment are up to date](https://docs.astral.sh/uv/guides/projects/#running-commands) before every run. The `uv pip` commands are [for projects not ready to move away from pip](https://docs.astral.sh/uv/pip/), not the main interface.
 
-uv-build is uv's own build backend, which its docs call [a great choice for most Python projects](https://docs.astral.sh/uv/concepts/build-backend/#choosing-a-build-backend). It's for pure-Python code, aims to need no configuration, and by default expects your package in `src/<package_name>/`.
+uv-build is uv's own build backend, and `uv init` [sets it up](https://docs.astral.sh/uv/concepts/projects/init/) with your code in `src/<project_name>/`. When you need build scripts or a more flexible layout, uv's docs [suggest Hatchling instead](https://docs.astral.sh/uv/concepts/build-backend/#choosing-a-build-backend).
 
-conda manages [packages in any language](https://packaging.python.org/en/latest/key_projects/#conda), Python included, so it fits projects that need compiled non-Python libraries next to their Python ones. Install it with [Miniforge](https://docs.conda.io/projects/conda/en/stable/), which uses the free conda-forge channel. Miniconda and the Anaconda Distribution use Anaconda's repository instead, which [may require a commercial license](https://docs.conda.io/projects/conda/en/stable/user-guide/getting-started.html#before-you-start). In a conda environment, [install as much as you can with conda](https://docs.conda.io/projects/conda/en/stable/user-guide/tasks/manage-environments.html#using-pip-in-an-environment) before you use pip for the rest. To change the environment later, create a new one rather than running conda after pip.
+pip [installs packages](https://pip.pypa.io/en/stable/) from PyPI and other indexes. It comes with Python, but managing environments, the interpreter, and the project as a whole is [outside its scope](https://pip.pypa.io/en/stable/topics/workflow/). Run it as `python -m pip`, so you [know which Python](https://pip.pypa.io/en/stable/user_guide/#running-pip) gets the package.
 
-pip is the [standard tool to install packages from PyPI](https://packaging.python.org/en/latest/guides/tool-recommendations/#installing-packages), and it ships with most Python installations. Run it as `python -m pip`, so [it installs into the interpreter you name](https://pip.pypa.io/en/stable/user_guide/#running-pip), and use it inside a [virtual environment](https://pip.pypa.io/en/stable/getting-started/#next-steps). To repeat an install, [pin every version](https://pip.pypa.io/en/stable/topics/repeatable-installs/#pinning-the-package-versions) in a requirements file generated by `pip freeze`. By default, pip doesn't check downloads for tampering, so for deployments its docs [recommend hash-checking mode](https://pip.pypa.io/en/stable/topics/secure-installs/).
+Poetry [manages your dependencies and builds your package](https://python-poetry.org/docs/), with a lockfile for repeatable installs. For a project you won't publish, [turn off package mode](https://python-poetry.org/docs/basic-usage/#operating-modes) and use Poetry for dependencies only. Its build backend, poetry-core, lets pip [build and install your project](https://github.com/python-poetry/poetry-core) without Poetry.
 
-Poetry [manages dependencies and packaging](https://python-poetry.org/docs/), with a lockfile for repeatable installs. [Install it in its own virtual environment](https://python-poetry.org/docs/#installation), with pipx for example, and never in the project it manages.
+Hatch [manages environments, builds, and Python installs](https://hatch.pypa.io/latest/) for your project. `hatch run test:pytest` [runs pytest in a `test` environment](https://hatch.pypa.io/latest/tutorials/environment/basic-usage/) without activating it, and creates that environment on first use. A [matrix](https://hatch.pypa.io/latest/environment/#matrix) repeats an environment across Python versions.
 
-Hatch is a [Python project manager](https://hatch.pypa.io/latest/) for environments, builds, and publishing. You never create its environments by hand: the first command you run in one [creates it](https://hatch.pypa.io/latest/environment/). Define a [matrix](https://hatch.pypa.io/latest/config/environment/advanced/#matrix) to run the same tests across Python versions. For most projects, `hatch test` [runs pytest and coverage.py](https://hatch.pypa.io/latest/tutorials/testing/overview/) with no test environment of your own.
+Hatchling is Hatch's build backend, [developed with Hatch but separate from it](https://packaging.python.org/en/latest/guides/tool-recommendations/). It [takes the files to ship from your `.gitignore`](https://hatch.pypa.io/latest/why/#build-backend) and builds reproducible wheels and sdists by default.
 
-pipx installs command-line apps [each in its own virtual environment](https://pipx.pypa.io/stable/#pip-vs-pipx) and puts their commands on your PATH, and `pipx run` runs an app without installing it. If you already use uv, its tool command does the same job. pipx's docs suggest pipx [when you need its extras](https://pipx.pypa.io/stable/explanation/comparisons.html#picking-one), like installing an app system-wide.
+pipx installs command-line apps [each in its own virtual environment](https://pipx.pypa.io/latest/), so their dependencies never collide, and puts their commands on your PATH. To try an app once, [`pipx run`](https://pipx.pypa.io/latest/tutorial/getting-started.html) runs it in a temporary environment. `uv tool` does the same job on uv, and pipx's docs say [running both is fine](https://pipx.pypa.io/latest/explanation/comparisons.html#picking-one).
 
-setuptools [builds C and C++ extension modules](https://setuptools.pypa.io/en/latest/userguide/ext_modules.html), and Hatch's docs [recommend it](https://hatch.pypa.io/latest/why/#build-backend) when you need them. Keep your config in `pyproject.toml` and [only the dynamic parts](https://setuptools.pypa.io/en/latest/userguide/quickstart.html#setuppy-discouraged) in `setup.py`. Build with `python -m build` [instead of running `setup.py`](https://packaging.python.org/en/latest/discussions/setup-py-deprecated/).
+conda manages [packages and environments for any language](https://docs.conda.io/projects/conda/en/latest/), and [its packages](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/packages.html) can hold system libraries and programs, not only Python modules. Keep your requirements in a file, and [use pip only after conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#pip-in-env) has installed everything it can.
 
-Hatchling is the build backend the Python Packaging User Guide's [tutorial uses by default](https://packaging.python.org/en/latest/tutorials/packaging-projects/#choosing-a-build-backend). It supports plugins and [build hooks](https://hatch.pypa.io/latest/config/build/#build-hooks), and uv's docs point to it when you need build scripts or a more flexible project layout.
+setuptools [builds C and C++ extension modules](https://setuptools.pypa.io/en/latest/userguide/ext_modules.html), and Hatch's docs [recommend it](https://hatch.pypa.io/latest/why/#build-backend) for them. Keep its configuration in pyproject.toml and `setup.py` [minimal, if you need one at all](https://setuptools.pypa.io/en/latest/userguide/quickstart.html#setuppy-discouraged), and don't run `setup.py` as a script.
 
-Whichever tool builds your package, declare the backend in `pyproject.toml`'s `[build-system]` table and your metadata in [the standard `[project]` table](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/), which most build backends understand. For an app, commit [uv.lock](https://docs.astral.sh/uv/guides/projects/#uvlock) or [poetry.lock](https://python-poetry.org/docs/basic-usage/#as-an-application-developer), so every machine installs the same versions. A library's lockfile doesn't reach the apps that install it, since they [resolve its dependencies themselves](https://python-poetry.org/docs/basic-usage/#as-a-library-developer).
+Whichever tool writes your lockfile, commit it to version control, as [uv](https://docs.astral.sh/uv/guides/projects/#uvlock) and [Poetry](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control) both recommend, so every machine installs the same versions.