pep621.md•6.56 kB
# PEP 621 Metadata
The project metadata are stored in the `pyproject.toml`. The specifications are defined by [PEP 621], [PEP 631] and [PEP 639]. Read the detailed specifications in the PEPs.
[PEP 621]: https://www.python.org/dev/peps/pep-0621/
[PEP 631]: https://www.python.org/dev/peps/pep-0631/
[PEP 639]: https://www.python.org/dev/peps/pep-0639/
_In the following part of this document, metadata should be written under `[project]` table if not given explicitly._
## Multiline description
You can split a long description onto multiple lines, thanks to TOML support for multiline strings.
Just remember to escape new lines, so the final description appears [on one line only in your package metadata](https://packaging.python.org/specifications/core-metadata/#summary).
Indentation will be removed as well when escaping new lines:
```toml
description = """\
Lorem ipsum dolor sit amet, consectetur adipiscing elit, \
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \
Ut enim ad minim veniam, quis nostrud exercitation ullamco \
laboris nisi ut aliquip ex ea commodo consequat.\
"""
```
See [TOML's specification on strings](https://toml.io/en/v1.0.0#string).
## Package version
=== "Static"
```toml
[project]
version = "1.0.0"
```
=== "Dynamic"
```toml
[project]
...
dynamic = ["version"]
[tool.pdm]
version = { source = "file", path = "mypackage/__version__.py" }
```
The version will be read from the `mypackage/__version__.py` file searching for the pattern: `__version__ = "{version}"`.
Read more information about other configurations in [dynamic project version](https://backend.pdm-project.org/metadata/#dynamic-project-version) from the `pdm-backend` documentation.
## Python version
The required version of Python is specified as the string `requires-python`:
```toml
requires-python = ">=3.9"
classifiers = [
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
...
]
```
Note: As per [PEP 621](https://peps.python.org/pep-0621/#allow-tools-to-add-extend-data),
PDM is not permitted to dynamically update the `classifiers` section like some other non-compliant tools.
Thus, you should also include the appropriate [trove classifiers](https://pypi.org/classifiers/) as shown above if you plan on publishing your package on [PyPI](https://pypi.org/).
## License
<!-- TODO: update following paragraphs if PEP 639 is accepted,
see https://peps.python.org/pep-0639/#deprecate-license-classifiers -->
The license is specified as the string `license`:
```toml
license = {text = "BSD-2-Clause"}
classifiers = [
"License :: OSI Approved :: BSD License",
...
]
```
Note: As per [PEP 621](https://peps.python.org/pep-0621/#allow-tools-to-add-extend-data),
PDM is not permitted to dynamically update the `classifiers` section like some other non-compliant tools.
Thus, you should also include the appropriate [trove classifiers](https://pypi.org/classifiers/) as shown above if you plan on publishing your package on [PyPI](https://pypi.org/).
## Dependency specification
The `project.dependencies` is an array of dependency specification strings following the [PEP 440](https://www.python.org/dev/peps/pep-0440/) and [PEP 508](https://www.python.org/dev/peps/pep-0508/).
Examples:
```toml
[project]
...
dependencies = [
# Named requirement
"requests",
# Named requirement with version specifier
"flask >= 1.1.0",
# Requirement with environment marker
"pywin32; sys_platform == 'win32'",
# URL requirement
"pip @ git+https://github.com/pypa/pip.git@20.3.1"
]
```
## Optional dependencies
You can have some requirements optional, which is similar to `setuptools`' `extras_require` parameter.
```toml
[project.optional-dependencies]
socks = [ 'PySocks >= 1.5.6, != 1.5.7, < 2' ]
tests = [
'ddt >= 1.2.2, < 2',
'pytest < 6',
'mock >= 1.0.1, < 4; python_version < "3.4"',
]
```
To install a group of optional dependencies:
```bash
pdm install -G socks
```
`-G` option can be given multiple times to include more than one group.
## Context variables expansion
Depending on which build backend you are using, PDM will expand some variables in the dependency strings.
### Environment variables
=== "pdm-backend"
```toml
[project]
dependencies = ["flask @ https://${USERNAME}:${PASSWORD}/artifacts.io/Flask-1.1.2.tar.gz"]
```
=== "hatchling"
```toml
[project]
dependencies = ["flask @ https://{env:USERNAME}:{env:PASSWORD}/artifacts.io/Flask-1.1.2.tar.gz"]
```
Find more usages [here](https://hatch.pypa.io/dev/config/context/#environment-variables)
Don't worry about credential leakage, the environment variables will be expanded when needed and kept untouched in the lock file.
### Relative paths
When you add a package from a relative path, PDM will automatically save it as a relative path for `pdm-backend` and `hatchling`.
For example, if you run `pdm add ./my-package`, it will result in the following line in `pyproject.toml`.
=== "pdm-backend"
```toml
[project]
dependencies = ["my-package @ file:///${PROJECT_ROOT}/my-package"]
```
=== "hatchling"
```toml
[project]
dependencies = ["my-package @ {root:uri}/my-package"]
```
By default, hatchling doesn't support [direct references](https://hatch.pypa.io/dev/config/dependency/#direct-references)
in the dependency string, you need to turn it on in `pyproject.toml`:
```toml
[tool.hatch.metadata]
allow-direct-references = true
```
The relative path will be expanded based on the project root when installing or locking.
## Console scripts
The following content:
```toml
[project.scripts]
mycli = "mycli.__main__:main"
```
will be translated to `setuptools` style:
```python
entry_points = {
'console_scripts': [
'mycli=mycli.__main__:main'
]
}
```
Also, `[project.gui-scripts]` will be translated to `gui_scripts` entry points group in `setuptools` style.
## Entry points
Other types of entry points are given by `[project.entry-points.<type>]` section, with the same format of `[project.scripts]`:
```toml
[project.entry-points.pytest11]
myplugin = "mypackage.plugin:pytest_plugin"
```
If the entry point name contains dots or other special characters, wrap it in quotes:
```toml
[project.entry-points."flake8.extension"]
myplugin = "mypackage.plugin:flake8_plugin"
```