| 1 |
# Python Project Metadata |
| 2 |
|
| 3 |
maturin supports [PEP 621](https://www.python.org/dev/peps/pep-0621/), |
| 4 |
you can specify python package metadata in `pyproject.toml`. |
| 5 |
maturin merges metadata from `Cargo.toml` and `pyproject.toml`, `pyproject.toml` takes precedence over `Cargo.toml`. |
| 6 |
|
| 7 |
Here is a `pyproject.toml` example from PEP 621 for reference purpose: |
| 8 |
|
| 9 |
```toml |
| 10 |
[project] |
| 11 |
name = "spam" |
| 12 |
version = "2020.0.0" |
| 13 |
description = "Lovely Spam! Wonderful Spam!" |
| 14 |
readme = "README.rst" |
| 15 |
requires-python = ">=3.8" |
| 16 |
license = {file = "LICENSE.txt"} |
| 17 |
keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"] |
| 18 |
authors = [ |
| 19 |
{email = "[email protected]"}, |
| 20 |
{name = "Tzu-Ping Chung"} |
| 21 |
] |
| 22 |
maintainers = [ |
| 23 |
{name = "Brett Cannon", email = "[email protected]"} |
| 24 |
] |
| 25 |
classifiers = [ |
| 26 |
"Development Status :: 4 - Beta", |
| 27 |
"Programming Language :: Python" |
| 28 |
] |
| 29 |
|
| 30 |
dependencies = [ |
| 31 |
"httpx", |
| 32 |
"gidgethub[httpx]>4.0.0", |
| 33 |
"django>2.1; os_name != 'nt'", |
| 34 |
"django>2.0; os_name == 'nt'" |
| 35 |
] |
| 36 |
|
| 37 |
[project.optional-dependencies] |
| 38 |
test = [ |
| 39 |
"pytest < 5.0.0", |
| 40 |
"pytest-cov[all]" |
| 41 |
] |
| 42 |
|
| 43 |
[project.urls] |
| 44 |
homepage = "example.com" |
| 45 |
documentation = "readthedocs.org" |
| 46 |
repository = "github.com" |
| 47 |
changelog = "github.com/me/spam/blob/master/CHANGELOG.md" |
| 48 |
|
| 49 |
[project.scripts] |
| 50 |
spam-cli = "spam:main_cli" |
| 51 |
|
| 52 |
[project.gui-scripts] |
| 53 |
spam-gui = "spam:main_gui" |
| 54 |
|
| 55 |
[project.entry-points."spam.magical"] |
| 56 |
tomatoes = "spam:main_tomatoes" |
| 57 |
``` |
| 58 |
|
| 59 |
## Dynamic metadata |
| 60 |
|
| 61 |
Maturin has limited support for [dynamic metadata](https://packaging.python.org/en/latest/specifications/pyproject-toml/#dynamic) in `pyproject.toml`. |
| 62 |
|
| 63 |
When the `[project]` section is not present, maturin will populate metadata from `Cargo.toml` with the following fields: |
| 64 |
|
| 65 |
* `name` - From `package.name` in Cargo.toml |
| 66 |
* `version` - From `package.version` in Cargo.toml (converted from SemVer to PEP 440 format) |
| 67 |
* `summary` - From `package.description` in Cargo.toml |
| 68 |
* `description` - From the contents of the README file specified in Cargo.toml's `package.readme` |
| 69 |
* `description_content_type` - Set based on the README file extension (e.g. `text/markdown` for `.md` files) |
| 70 |
* `keywords` - From `package.keywords` in Cargo.toml, joined with commas |
| 71 |
* `home_page` - From `package.homepage` in Cargo.toml |
| 72 |
* `author` - From `package.authors` in Cargo.toml, joined with commas |
| 73 |
* `author_email` - From `package.authors` in Cargo.toml if it contains email addresses |
| 74 |
* `license` - From `package.license` in Cargo.toml |
| 75 |
* `project_url` - From various URLs in Cargo.toml (like repository, homepage, etc.) |
| 76 |
|
| 77 |
When the `[project]` section is present, maturin will merge metadata from `Cargo.toml` and `pyproject.toml`, `pyproject.toml` takes precedence over `Cargo.toml`. |
| 78 |
Per specification, maturin is not allowed to populate fields that are not present in `project.dynamic` list when the `[project]` section is present. |
| 79 |
For example, to use the Rust crate version as the Python package version, you need to add `version` to the `project.dynamic` list: |
| 80 |
|
| 81 |
```toml |
| 82 |
[project] |
| 83 |
name = "my-awesome-project" |
| 84 |
dynamic = ["version"] |
| 85 |
``` |
| 86 |
|
| 87 |
## Add Python dependencies |
| 88 |
|
| 89 |
To specify python dependencies, add a list `dependencies` in a `[project]` section in the `pyproject.toml`. This list is equivalent to `install_requires` in setuptools: |
| 90 |
|
| 91 |
```toml |
| 92 |
[project] |
| 93 |
name = "my-project" |
| 94 |
dependencies = ["flask~=1.1.0", "toml==0.10.0"] |
| 95 |
``` |
| 96 |
|
| 97 |
## Add console scripts |
| 98 |
|
| 99 |
Pip allows adding so called console scripts, which are shell commands that execute some function in your program. You can add console scripts in a section `[project.scripts]`. |
| 100 |
The keys are the script names while the values are the path to the function in the format `some.module.path:class.function`, where the `class` part is optional. The function is called with no arguments. Example: |
| 101 |
|
| 102 |
```toml |
| 103 |
[project.scripts] |
| 104 |
get_42 = "my_project:DummyClass.get_42" |
| 105 |
``` |
| 106 |
|
| 107 |
## Add trove classifiers |
| 108 |
|
| 109 |
You can also specify [trove classifiers](https://pypi.org/classifiers/) under `project.classifiers`: |
| 110 |
|
| 111 |
```toml |
| 112 |
[project] |
| 113 |
name = "my-project" |
| 114 |
classifiers = ["Programming Language :: Python"] |
| 115 |
``` |
| 116 |
|
| 117 |
## Add SPDX license expressions |
| 118 |
|
| 119 |
A practical string value for the license key has been purposefully left out by PEP 621 |
| 120 |
to allow for a future PEP to specify support for |
| 121 |
[SPDX](https://spdx.org/licenses/) expressions. |
| 122 |
|
| 123 |
To use SPDX license expressions, you can specify it in `Cargo.toml` instead: |
| 124 |
|
| 125 |
```toml |
| 126 |
[package] |
| 127 |
name = "my-project" |
| 128 |
license = "MIT OR Apache-2.0" |
| 129 |
``` |