Packaging & PyPI
From "Works on my machine" to "pip install my-tool". The professional distribution workflow.
1. The Big Idea (ELI5)
👶 Explain Like I'm 10: Shipping Container Logistics
Imagine you bake amazing Cookies (Code).
- Local Script: You hand a cookie to your friend. It breaks in their pocket. They ask "Does this contain nuts?" (Dependencies). You forgot to tell them.
- Packaging: You put the cookies in a Standardized Box (Package). You label it with Ingredients (Requirements), Expiration Date (Version), and Instructions (Docs). Now you can ship this box ANYWHERE in the world (PyPI), and the person receiving it knows exactly what they are getting.
2. The Standard: `pyproject.toml`
For 20 years, we used `setup.py`. That is DEAD. The modern standard (PEP 621) is a static configuration file called `pyproject.toml`.
TOML
[project]
name = "super_math_tool"
version = "1.0.0"
description = "A tool to calculate huge numbers"
authors = [
{name = "Rohit User", email = "rohit@example.com"}
]
dependencies = [
"numpy>=1.20",
"requests<3.0"
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"3. The Tooling Wars: Pip vs Poetry vs Hatch
`pip` installs packages. It does NOT manage your project's build process. Use a modern Package Manager:
| Tool | Role | Verdict |
|---|---|---|
| Pip | Installer | Good for simple scripts. Bad for libraries. |
| Poetry | Manager | The industry favorite. Handles locking & publishing. |
| UV | Installer | Built in Rust. 100x faster than pip. The future. |
4. Semantic Versioning (SemVer)
Your version number `1.2.3` isn't random. It follows rules:
- MAJOR (1): Breaking changes. Old code might stop working.
- MINOR (2): New features, but backwards compatible.
- PATCH (3): Bug fixes only. Safe to update.
5. Publishing to PyPI (The Repo)
Once your package is built (into a `.whl` file), you upload it.
BASH
# 1. Build the package
poetry build
# 2. Configure PyPI token
poetry config pypi-token.pypi pypi-AgEIpy...
# 3. Publish!
poetry publishPractice First: Always upload to TestPyPI first. It's a sandbox. You cannot delete files from real PyPI once uploaded (to prevent breaking the internet).