pyproject.toml and Build Backends

## Why a declarative table exists at all For most of Python's history a project described itself by *running code*: `setup.py` called `setup(...)` with keyword arguments, so the only way to learn a project's name, version or dependencies was to execute an arbitrary script from a stranger. That is a chicken-and-egg problem (the script may import the very library it needs to describe itself) and a security problem. `pyproject.toml` replaced it with data. TOML was chosen because it has one obvious parse, and since Python 3.11 the standard library can read it with `tomllib` — no third-party parser required. A `pyproject.toml` has three families of tables: * `[build-system]` — the build-time contract: which tools build this project. * `[project]` — PEP 621 core metadata: what this distribution *is*. * `[tool.<name>]` — a namespace each tool owns for its own settings. Installers ignore these completely; a formatter or a type checker reads its own subtable and nothing else. ## The fields, and what they mean `name` is the **distribution** name — the string you type after `pip install` and the name PyPI reserves. It is normalised (lowercased, and runs of `-`, `_` and `.` folded to a single `-`), so `Sensor_Collector` and `sensor-collector` are the same project. Crucially it is *not* required to match the importable package name; a distribution named `python-dateutil` installs a package you import as `dateutil`, and that gap is a routine source of confusion when reading a lock file. `version` is a PEP 440 version string (`1.4.0`, `2.0.0rc1`, `0.3.0.post1`). `requires-python` is a specifier such as `>=3.11` that installers consult *before* downloading, so an old interpreter gets a clear resolution error rather than a broken install. `dependencies` is a list of PEP 508 requirement strings — `"packaging>=24"`, `"tomli; python_version < '3.11'"` — and each may carry an environment marker so a requirement applies only on some platforms or interpreter versions. `description` is the one-line summary shown in search results; `readme` points at the long description file; `license` and `license-files` describe licensing (modern backends accept an SPDX expression string plus a glob of license files); `authors`, `maintainers`, `keywords`, `classifiers` and `urls` are catalogue metadata. A `dynamic` list names fields the backend computes at build time instead of you writing them literally; a field may be static or dynamic, never both. ## What the table turns into The backend translates `[project]` into **core metadata**: the `METADATA` file inside a wheel, `PKG-INFO` inside a source distribution, and the `<name>-<version>.dist-info/METADATA` file in the installed environment. The mapping is mechanical: `name` becomes `Name`, `dependencies` entries become repeated `Requires-Dist` lines, `requires-python` becomes `Requires-Python`. At runtime `importlib.metadata` reads exactly that file, which is why `importlib.metadata.version("somedist")` asks for the *distribution* name rather than the module you imported. ## The two dependency lists people confuse `[project] dependencies` are **runtime** requirements: installed alongside your package into the user's environment. `[build-system] requires` are **build-time** requirements: installed into a temporary environment that exists only while the artifact is produced, and never shipped to the user. A build plugin belongs in the second list; putting it in the first makes every user install a tool they will never run. The reverse mistake — a runtime dependency listed only in `requires` — produces a package that builds fine and fails on first import. ## Reading it back ```python import tomllib with open("pyproject.toml", "rb") as fh: cfg = tomllib.load(fh) project = cfg["project"] print(project["name"], project["version"]) print(project.get("requires-python")) ``` Note `tomllib.load` wants a **binary** file object; handing it a text handle raises `TypeError`. That is the standard-library reader added in Python 3.11. ## What an interviewer is checking Three things, usually. First, that you know the metadata is *static data*, not executed code, and why that matters to resolvers, mirrors and auditing tools. Second, that you can separate `[project]` from `[build-system]` without hesitating — a surprising number of candidates believe `pyproject.toml` is a setuptools file, when it is a standard every backend implements. Third, that you know the distribution name and the import name are different namespaces. If you can also say where the table ends up after installation — `dist-info/METADATA`, readable via `importlib.metadata` — you have covered the whole life cycle of the field in about ninety seconds.