Python Reference ยท Practical Pages
Python packaging and project layout
Concept page on Python packaging: a standard project layout, pyproject.toml fields, dependencies, entry points, building wheels and the import system basics.
A Python package is a directory of modules that you can import; a distribution is the thing you build and install (a wheel or a source archive). Modern projects describe themselves in one file, pyproject.toml, and the same layout works for a small script collection, a library you publish, or an application you deploy.
Packaging commands (pip, python -m build, twine) need a real file system, a terminal and a network, so they cannot run in the browser. The code blocks that show them are read-only; the TryIts below demonstrate the pieces you can run: parsing pyproject.toml with tomllib, building a package in memory and looking at import behaviour.
A standard layout
my-project/
pyproject.toml
README.md
LICENSE
src/
textkit/
__init__.py
core.py
cli.py
tests/
test_core.py
The src/ layout keeps your tests from accidentally importing the uninstalled source tree, so you test the code the way users will install it. Every directory that should be importable as a package contains __init__.py (it can be empty; namespace packages without it exist but are rarely what you want).
A minimal pyproject.toml
[build-system] requires = ["setuptools>=77"] build-backend = "setuptools.build_meta" [project] name = "textkit" version = "0.1.0" description = "Small text helpers" readme = "README.md" requires-python = ">=3.10" license = "MIT" dependencies = ["rich>=13"] [project.optional-dependencies] dev = ["pytest"] [project.scripts] textkit = "textkit.cli:main"
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Everyday commands (read-only)
python -m venv .venv # isolated environment python -m pip install -e ".[dev]" # editable install with extras python -m pytest # run tests against the installed package python -m build # create dist/*.whl and dist/*.tar.gz python -m twine upload dist/* # publish to an index
Usage notes
- Name and version. The project name is what users
pip install; the import name is the folder undersrc/. They may differ, but keeping them the same avoids confusion. Versions follow PEP 440 (1.2.0,1.2.0rc1); semantic versioning is the common convention. - Dependencies use specifiers:
>=2.0,~=2.1(compatible release),==1.4.*. Libraries should allow ranges; applications may pin exact versions in a lock or requirements file. - Build backends are interchangeable: setuptools, hatchling, flit, pdm-backend, maturin (for Rust). The
[project]table is the same for all of them. - Entry points under
[project.scripts]create command-line programs.module:functionis called with no arguments, so readsys.argvor useargparse. python -m packagerunspackage/__main__.py, a good way to make a package executable without installing a script.- Editable installs (
pip install -e .) let you change source files without reinstalling. __init__.pymay re-export your public API (from .core import shout) and define__all__, so users writetextkit.shout.- Avoid circular imports by moving shared code into a lower-level module, or importing inside a function.
- Old style.
setup.pyandsetup.cfgstill work but new projects should usepyproject.toml; do not runpython setup.py install. - Always use a virtual environment so project dependencies do not mix with the system Python.
Related
- sys, configparser
- import, Deprecated and removed features
- Tutorial lessons: Modules, Packages and pip, Virtual environments