2
2
Inline script metadata
3
3
======================
4
4
5
- .. warning ::
6
- This specification has been **provisionally accepted **. It is subject
7
- to being changed or abandoned. See the
8
- `PEP 723 conditional acceptance thread <pep723-thread _>`_ for details.
9
-
10
- .. _pep723-thread : https://discuss.python.org/t/36763
11
-
12
5
This specification defines a metadata format that can be embedded in single-file
13
6
Python scripts to assist launchers, IDEs and other external tools which may need
14
7
to interact with such scripts.
@@ -73,20 +66,22 @@ In circumstances where there is a discrepancy between the text specification
73
66
and the regular expression, the text specification takes precedence.
74
67
75
68
Tools MUST NOT read from metadata blocks with types that have not been
76
- standardized by this PEP or future ones .
69
+ standardized by this specification .
77
70
78
- pyproject type
79
- --------------
71
+ script type
72
+ -----------
80
73
81
- The first type of metadata block is named ``pyproject `` which represents
82
- content similar to what one would see in a `` pyproject.toml `` file .
74
+ The first type of metadata block is named ``script `` which contains
75
+ script metadata (dependency data and tool configuration) .
83
76
84
- This document MAY include the ``[run] `` and ``[tool] `` tables.
77
+ This document MAY include top-level fields ``dependencies `` and ``requires-python ``,
78
+ and MAY optionally include a ``[tool] `` table.
85
79
86
- The :ref: `tool table <pyproject-tool-table >` MAY be used by any tool,
87
- script runner or otherwise, to configure behavior.
80
+ The ``[tool] `` MAY be used by any tool, script runner or otherwise, to configure
81
+ behavior. It has the same semantics as the :ref: `[tool] table in pyproject.toml
82
+ <pyproject-tool-table>`
88
83
89
- The `` [run] `` table MAY include the following optional fields:
84
+ The top-level fields are :
90
85
91
86
* ``dependencies ``: A list of strings that specifies the runtime dependencies
92
87
of the script. Each entry MUST be a valid
@@ -107,11 +102,11 @@ Script runners SHOULD error if no version of Python that satisfies the specified
107
102
Example
108
103
-------
109
104
110
- The following is an example of a script with an embedded `` pyproject.toml `` :
105
+ The following is an example of a script with embedded metadata :
111
106
112
107
.. code :: python
113
108
114
- # /// pyproject
109
+ # /// script
115
110
# [run]
116
111
# requires-python = ">=3.11"
117
112
# dependencies = [
@@ -127,23 +122,6 @@ The following is an example of a script with an embedded ``pyproject.toml``:
127
122
data = resp.json()
128
123
pprint([(k, v[" title" ]) for k, v in data.items()][:10 ])
129
124
130
- The following is an example of a proposed syntax for single-file Rust
131
- projects that embeds their equivalent of ``pyproject.toml ``, which is called
132
- ``Cargo.toml ``:
133
-
134
- .. code :: rust
135
-
136
- #!/usr/bin/env cargo
137
-
138
- //! ```cargo
139
- //! [dependencies]
140
- //! regex = "1.8.0"
141
- //! ```
142
-
143
- fn main() {
144
- let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
145
- println!("Did our date match? {}", re.is_match("2014-01-01"));
146
- }
147
125
148
126
Reference Implementation
149
127
========================
@@ -159,7 +137,7 @@ higher.
159
137
REGEX = r ' (?m) ^ # /// ( ?P<type> [a-zA-Z0-9- ]+ ) $ \s ( ?P<content> ( ^ #( | . * ) $ \s ) + ) ^ # ///$ '
160
138
161
139
def read (script : str ) -> dict | None :
162
- name = ' pyproject '
140
+ name = ' script '
163
141
matches = list (
164
142
filter (lambda m : m.group(' type' ) == name, re.finditer(REGEX , script))
165
143
)
@@ -196,7 +174,7 @@ __ https://tomlkit.readthedocs.io/en/latest/
196
174
)
197
175
198
176
config = tomlkit.parse(content)
199
- config[' project ' ][ ' dependencies' ].append(dependency)
177
+ config[' dependencies' ].append(dependency)
200
178
new_content = ' ' .join(
201
179
f ' # { line} ' if line.strip() else f ' # { line} '
202
180
for line in tomlkit.dumps(config).splitlines(keepends = True )
@@ -239,3 +217,7 @@ History
239
217
=======
240
218
241
219
- October 2023: This specification was conditionally approved through :pep: `723 `.
220
+ - January 2024: Through amendments to :pep: `723 `, the ``pyproject `` metadata
221
+ block type was renamed to ``script ``, and the ``[run] `` table was dropped,
222
+ making the ``dependencies `` and ``requires-python `` keys
223
+ top-level. Additionally, the specification is no longer provisional.
0 commit comments