Project metadata¶
Project metadata is stored in a pyproject.toml file located at the root of a project's tree and is based entirely on PEP 621.
Name (required)¶
The name of the project.
[project]
name = "your-app"
Version (required)¶
See the dedicated versioning section.
[project]
...
dynamic = ["version"]
[tool.hatch.version]
path = "..."
[project]
...
version = "0.0.1"
Description¶
A brief summary of the project.
[project]
...
description = '...'
Readme¶
The full description of the project.
The file extension must be .md, .rst, or .txt.
[project]
...
readme = "README.md"
The content-type field must be set to text/markdown, text/x-rst, or text/plain.
A charset field may also be set to instruct which encoding to use for reading the file, defaulting to utf-8.
[project]
...
readme = {"file" = "README.md", "content-type" = "text/markdown"}
The content-type field must be set to text/markdown or text/x-rst.
[project]
...
readme = {"text" = "...", "content-type" = "text/markdown"}
Note
If this is defined as a file, then it will always be included in source distributions for consistent builds.
Python support¶
The Python version requirements of the project.
[project]
...
requires-python = ">=3.8"
License¶
For more information, see PEP 639.
[project]
...
license = "Apache-2.0 OR MIT"
[project]
...
license-files = { paths = ["LICENSE.txt"] }
[project]
...
license-files = { globs = ["LICENSES/*"] }
Ownership¶
The people or organizations considered to be the authors or maintainers of the project. The exact meaning is open to interpretation; it may list the original or primary authors, current maintainers, or owners of the package. If the values are the same, prefer only the use of the authors field.
[project]
...
authors = [
{ name = "...", email = "..." },
]
maintainers = [
{ name = "...", email = "..." },
]
Keywords¶
The keywords used to assist in the discovery of the project.
[project]
...
keywords = [
"...",
]
Classifiers¶
The trove classifiers that apply to the project.
[project]
...
classifiers = [
"...",
]
URLs¶
A table of URLs where the key is the URL label and the value is the URL itself.
[project.urls]
Documentation = "..."
"Source code" = "..."
Dependencies¶
The format is based on PEP 631. See the dependency specification section for more information.
Entries support context formatting and disallow direct references by default.
Required¶
[project]
...
dependencies = [
"...",
]
Optional¶
[project.optional-dependencies]
option1 = [
"...",
]
option2 = [
"...",
]
Entry points¶
Entry points are a mechanism for the project to advertise components it provides to be discovered and used by other code.
CLI¶
After installing projects that define CLI scripts, each key will be available along your PATH as a command that will call its associated object.
[project.scripts]
cli-name = "pkg.subpkg:func"
Using the above example, running cli-name would essentially execute the following Python script:
import sys
from pkg.subpkg import func
sys.exit(func())
GUI¶
GUI scripts are exactly the same as CLI scripts except on Windows, where they are handled specially so that they can be started without a console.
[project.gui-scripts]
gui-name = "pkg.subpkg:func"
Plugins¶
[project.entry-points.plugin-namespace]
plugin-name1 = "pkg.subpkg1"
plugin-name2 = "pkg.subpkg2:func"
Metadata options¶
Allowing direct references¶
By default, dependencies are not allowed to define direct references. To disable this check, set allow-direct-references to true:
[tool.hatch.metadata]
allow-direct-references = true
[metadata]
allow-direct-references = true