Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 38 ยท pyproject and Metadata

Project Metadata Fields

Fill in the [project] table correctly: names, versions, authors, license expressions, classifiers, URLs, optional dependencies and how they become core metadata.

The [project] table is what people see on PyPI and what installers read to resolve dependencies. Each field maps to a line in a standard text format called core metadata, written into every wheel as METADATA. In this lesson you will go through the fields one at a time and then convert a [project] table into real core metadata, the same thing a build backend does.

A complete example

TOML
[project]
name = "weather-cli"
version = "0.3.0"
description = "Print the forecast in your terminal"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"
license-files = ["LICENSE"]
authors = [{ name = "Ana Reyes", email = "[email protected]" }]
maintainers = [{ name = "Weather Team" }]
keywords = ["weather", "cli", "forecast"]
classifiers = [
  "Development Status :: 4 - Beta",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.12",
  "Environment :: Console",
]
dependencies = ["requests>=2.30", "rich>=13"]

[project.optional-dependencies]
yaml = ["pyyaml>=6"]
docs = ["mkdocs>=1.6"]

[project.urls]
Homepage = "https://example.com/weather-cli"
Source = "https://github.com/example/weather-cli"
Issues = "https://github.com/example/weather-cli/issues"

[project.scripts]
weather = "weather_cli.main:run"

Field by field

name (required). Letters, digits, -, _, .. Names are compared after normalization, so Weather_CLI equals weather-cli. Check that the name is free on PyPI before you invest in it.

version (required, or dynamic). Must follow PEP 440, covered in the next lesson.

description. A single line shown in search results. Keep it under about 100 characters.

readme. A path to a Markdown, reStructuredText or text file that becomes the long description on PyPI. The content type is inferred from the extension.

requires-python. The Python versions you support, as a specifier such as ">=3.10". Installers use it to skip releases that do not match the interpreter. Set a lower bound you actually test; leave off upper bounds like <4 unless you know of a break.

license and license-files. Modern projects write an SPDX license expression such as "MIT", "Apache-2.0" or "MIT OR Apache-2.0" (PEP 639), and list files that carry the text. Older tutorials show license = { text = "MIT" } or license = { file = "LICENSE" }, plus a License :: classifier. Prefer the expression form with a recent backend.

authors, maintainers. Lists of tables with name and/or email.

keywords, classifiers. Keywords are free text for search. Classifiers come from a fixed list of "trove classifiers" (pip index and trove-classifiers package): development status, supported Python versions, topic, environment, operating system. They help filtering on PyPI. Mistyped classifiers make uploads fail.

dependencies. The runtime requirements, as PEP 508 strings.

optional-dependencies. Named groups called extras. Users opt in with pip install "weather-cli[yaml]". Use them for optional features, not for development tools (those belong in dependency groups, see Dependency Management).

urls. Any labels you like; PyPI shows them in the sidebar. Common labels: Homepage, Documentation, Source, Issues, Changelog.

scripts, gui-scripts, entry-points. Console commands and plugin hooks; see Entry Points and Command-Line Tools.

dynamic. Names of fields whose values the backend computes instead of you writing them, most often version (read from a file, a Git tag or a module attribute).

From [project] to core metadata

A wheel's METADATA file is plain RFC 822 style text, the same layout as an email header, followed by a blank line and the long description. Field names differ slightly from the TOML keys (Requires-Dist, Provides-Extra, Project-URL). Writing the translation by hand shows how little magic there is.

Python Turning [project] into core metadata

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.

Notice how an optional dependency becomes a normal Requires-Dist line with an extra == "yaml" marker. When someone installs weather-cli[yaml], the installer evaluates that marker as true and includes pyyaml.

Reading metadata back

importlib.metadata parses the same format and gives it a friendly interface. get_all returns every repeated field.

Python Parsing a METADATA file

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.

Extras in practice

Extras are a good way to keep a base install light:

Terminal
pip install "weather-cli"            # requests + rich
pip install "weather-cli[yaml]"      # + pyyaml
pip install "weather-cli[yaml,docs]" # several at once

A frequent idiom is an all extra that combines the others (all = ["weather-cli[yaml,docs]"]). Mention extras in your README, and guard imports so the base install fails with a helpful message if the extra is missing:

Python
try:
    import yaml
except ImportError as exc:
    raise SystemExit("Install the extra: pip install 'weather-cli[yaml]'") from exc

Do not put a mutable URL in dependencies for a published package. PyPI rejects direct references (pkg @ git+https://...) in uploaded metadata. Use them only in application requirements.

Common mistakes

  • A description with line breaks or Markdown (it is one plain line).
  • A missing readme, leaving PyPI's project page empty.
  • requires-python omitted, so an install on an old Python succeeds and then fails at runtime.
  • A made-up classifier, which PyPI rejects at upload time.
  • Development tools in dependencies or extras, forcing them on every user.
  • Setting both version = "..." and dynamic = ["version"].

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does pip install the optional group yaml defined under [project.optional-dependencies]?

    Extras are requested in square brackets after the distribution name.
  2. 2. Where does the long description shown on PyPI come from?

    description is a one-line summary; readme provides the long description.
  3. 3. What does requires-python = ">=3.10" do?

    It is metadata that installers check. Python itself does not enforce it.
  4. 4. Which license form is preferred by recent packaging standards (PEP 639)?

    An SPDX license expression plus license-files is the modern way.

Summary

  • [project] holds standard metadata that every backend maps to core metadata (METADATA).
  • Required: name, and version unless dynamic. Strongly recommended: description, readme, requires-python, license, classifiers, urls.
  • dependencies are runtime needs; optional-dependencies are extras with extra == "name" markers.
  • Classifiers must come from the official list; license should be an SPDX expression.
  • dynamic lets a backend compute fields such as the version.
  • importlib.metadata and the email parser read the same format back.

Next: Version Specifiers and Environment Markers