5.8 KiB
Configuring 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 [the standard][project metadata standard].
Name (required) ## {: #name }
The name of the project.
[project]
name = "your-app"
Version (required) ## {: #version }
=== ":octicons-file-code-16: pyproject.toml"
=== "Dynamic"
See the dedicated [versioning](../version.md) section.
```toml
[project]
...
dynamic = ["version"]
[tool.hatch.version]
path = "..."
```
=== "Static"
```toml
[project]
...
version = "0.0.1"
```
Description
A brief summary of the project.
[project]
...
description = '...'
Readme
The full description of the project.
=== ":octicons-file-code-16: pyproject.toml"
=== "Simple"
The file extension must be `.md`, `.rst`, or `.txt`.
```toml
[project]
...
readme = "README.md"
```
=== "Complex"
The `content-type` field must be set to `text/markdown`, `text/x-rst`, or `text/plain`.
=== "File"
A `charset` field may also be set to instruct which encoding to
use for reading the file, defaulting to `utf-8`.
```toml
[project]
...
readme = {"file" = "README.md", "content-type" = "text/markdown"}
```
=== "Text"
The `content-type` field must be set to `text/markdown` or `text/x-rst`.
```toml
[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][].
=== ":octicons-file-code-16: pyproject.toml"
=== "SPDX expression"
```toml
[project]
...
license = "Apache-2.0 OR MIT"
```
=== "Files"
```toml
[project]
...
license-files = ["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
See the dependency specification page 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"
Dynamic
If any metadata fields are set dynamically, like the version may be, then they must be listed here.
[project]
...
dynamic = [
"...",
]
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
Allowing ambiguous features
By default, names of optional dependencies are normalized to prevent ambiguity. To disable this normalization, set allow-ambiguous-features to true:
[tool.hatch.metadata]
allow-ambiguous-features = true
!!! danger "Deprecated" This option temporarily exists to provide better interoperability with tools that do not yet support PEP 685 and will be removed in the first minor release after Jan 1, 2024.