Debian Codegraph @

guide/src/metadata.md

raw
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 ```