Packaging your code

import tomllib

PYPROJECT = '''
[project]
name = "trail-notes"
version = "1.2.0"
requires-python = ">=3.11"
dependencies = ["requests>=2.31,<3", "rich>=13"]

[project.scripts]
notes = "trail_notes.cli:main"
'''

config = tomllib.loads(PYPROJECT)
project = config["project"]
print(project["name"], project["version"])
print("needs:", project["dependencies"])
module, function = project["scripts"]["notes"].split(":")
print(f"the notes command runs {function}() from {module}")

TOML is a simple settings format: [section] headers, key = value lines, strings in quotes and lists in square brackets. tomllib.loads turns it into ordinary dictionaries. Tools such as black and mypy read their own [tool.black] and [tool.mypy] sections of this same file, which is why one pyproject.toml can configure a whole project.

import tomllib
data = tomllib.loads('[project]\nname = "kit"\nversion = "0.3.1"\n[project.scripts]\nkit = "kit.app:run"\n')
print(data["project"]["version"], list(data["project"]["scripts"]))

Versions that mean something

Most Python projects use semantic versioning: MAJOR.MINOR.PATCH, like 1.2.0.

• Bump PATCH (1.2.0 → 1.2.1) for bug fixes that change nothing else.
• Bump MINOR (1.2.1 → 1.3.0) when you add features in a backward-compatible way.
• Bump MAJOR (1.3.0 → 2.0.0) when you break something: remove a function, change what one returns.

Users then write version specifiers for their dependencies with confidence. requests>=2.31,<3 means "2.31 or newer, but not 3.0", which takes fixes and features but not breaking changes. ~=2.31 is shorthand for much the same. Pin exact versions (==2.32.3) in an application's lock file, so every deployment is identical, but keep a library's ranges loose, so it can share an environment with other libraries.

Before 1.0.0, all bets are off: many projects treat 0.x as "still settling", where any release may break things. Releasing a 1.0 is a promise about stability.

What a wheel really is

Running python -m build turns the project into two files in dist/: a source archive and a wheel, trail_notes-1.2.0-py3-none-any.whl. pip installs wheels. And a wheel is simply a zip file with a set layout:

• the package's own files, like trail_notes/__init__.py, exactly where they'll go in site-packages;
• a trail_notes-1.2.0.dist-info/ folder of metadata: METADATA (name, version, dependencies), WHEEL (which wheel format and which Pythons), entry_points.txt (the commands) and RECORD (every file with a hash of its contents, so pip can check nothing was damaged).

The file name says who can use it: py3-none-any means "any Python 3, no compiled code, any platform". Packages with C extensions, like NumPy, publish separate wheels for each operating system and Python version.

Installing a pure-Python wheel is mostly unzipping it into site-packages and creating the commands. That's literally how the academy installs Flask and black for your code: it unzips their wheels into the browser's Python. The exercise below builds and installs one by hand, so none of this stays magic.

import base64
import hashlib


def record_line(path, data):
    pass


print(record_line("trail_notes/__init__.py", b'__version__ = "1.2.0"\n'))

Publishing

The Python Package Index, PyPI, is where pip install looks by default. Publishing a release takes a few steps:

1. Choose a name nobody has taken, and bump the version (PyPI never lets you upload the same version twice).
2. Build: python -m build creates the wheel and the source archive in dist/.
3. Try it on TestPyPI first, a separate practice index, and install from there in a fresh virtual environment.
4. Upload with twine upload dist/* or uv publish. Better still, let CI publish when you push a version tag, using PyPI's trusted publishing, which needs no stored password at all.

Most code never needs to be public. Teams share private packages through a private index, or simply with pip install git+https://... straight from a repository. Either way, the same pyproject.toml and the same wheel format do the work. And remember the responsibilities that come with publishing: a clear license, a README that explains how to use it, and version numbers users can trust.

import importlib
import importlib.metadata
import io
import sys
import zipfile
from pathlib import Path

files = {
    "hello_kit/__init__.py": '__version__ = "0.1.0"\n\ndef main():\n    print("hello from hello-kit")\n    return 0\n',
    "hello_kit-0.1.0.dist-info/METADATA": "Metadata-Version: 2.1\nName: hello-kit\nVersion: 0.1.0\n",
    "hello_kit-0.1.0.dist-info/WHEEL": "Wheel-Version: 1.0\nGenerator: by hand\nRoot-Is-Purelib: true\nTag: py3-none-any\n",
    "hello_kit-0.1.0.dist-info/entry_points.txt": "[console_scripts]\nhello = hello_kit:main\n",
}
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w") as wheel:
    for name, text in files.items():
        wheel.writestr(name, text)
Path("hello_kit-0.1.0-py3-none-any.whl").write_bytes(buffer.getvalue())

target = Path("site_demo")
zipfile.ZipFile("hello_kit-0.1.0-py3-none-any.whl").extractall(target)
sys.path.insert(0, str(target.resolve()))
importlib.invalidate_caches()

print("installed version:", importlib.metadata.version("hello-kit"))
command = importlib.metadata.entry_points(group="console_scripts", name="hello")
for ep in command:
    print("the hello command runs", ep.value)
    ep.load()()