Packaging & Distribution

Writing a script is one thing; making it easy for someone else to install and run is another. In Python, Packaging is the process of bundling your code, metadata, and dependencies into a standard format (like a “Wheel”) that can be shared via PyPI (the Python Package Index).

1. Modern Project Structure

The community has settled on a standard structure for professional projects.

Directorymy_app/
- Directorysrc/
  - Directorymy_app/
    init .py
    core.py
- Directorytests/
  - test_core.py
- pyproject.toml
- README.md
- .gitignore

2. The Heart of the Package: `pyproject.toml`

The pyproject.toml file is the modern, unified way to configure your project. It replaces old files like setup.py and requirements.txt.

[project]
name = "cool-tool"
version = "0.1.0"
description = "A professional Python utility"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31.0",
    "rich>=13.0.0"
]

[project.scripts]
# This allows users to run 'my-cmd' in their terminal
my-cmd = "cool_tool.core:main"

3. Modern Tooling: `uv` (Recommended)

While pip and setuptools are the classics, the modern industry is moving toward uv. It is written in Rust and is 10x-100x faster than traditional tools.

Initializing a Project

uv init my-project

Managing Dependencies

uv automatically handles your virtual environment and pyproject.toml.

uv add requests

4. Under the Hood: The “Wheel” Format

When you “install” a library, you are usually downloading a Wheel (.whl) file.

Source Archive (.tar.gz): Raw source code. Needs to be “built” on the user’s machine.
Wheel (.whl): A pre-compiled, binary-ready ZIP file. It installs instantly because Python just has to unzip it into your site-packages folder.

5. Publishing to the World (PyPI)

Once your package is ready, you can share it with the world.

Build: Create the distribution files. uv build (or python -m build)
Upload: Send them to PyPI. uv publish (or twine upload dist/*)

6. Summary Table

Tool	Purpose	Status
`pyproject.toml`	Configuration manifest.	The Standard.
`setuptools`	Legacy build backend.	Still common.
`uv`	Package/Env management.	Industry Favorite.
`poetry`	Full-stack project management.	Very popular.