Skip to content
Tutorials Center
My learning

Topics

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

TEXT
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

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

Python Read pyproject.toml with tomllib

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.

Python Build a tiny package in memory and import 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.

Everyday commands (read-only)

Terminal
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 under src/. 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:function is called with no arguments, so read sys.argv or use argparse.
  • python -m package runs package/__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__.py may re-export your public API (from .core import shout) and define __all__, so users write textkit.shout.
  • Avoid circular imports by moving shared code into a lower-level module, or importing inside a function.
  • Old style. setup.py and setup.cfg still work but new projects should use pyproject.toml; do not run python setup.py install.
  • Always use a virtual environment so project dependencies do not mix with the system Python.