Skip to content

Commit c730a82

Browse files
jeanaswebknjaz
authored andcommitted
Update inline script metadata spec with latest PEP 723 changes
1 parent 1735f70 commit c730a82

File tree

1 file changed

+19
-37
lines changed

1 file changed

+19
-37
lines changed

source/specifications/inline-script-metadata.rst

Lines changed: 19 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,6 @@
22
Inline script metadata
33
======================
44

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-
125
This specification defines a metadata format that can be embedded in single-file
136
Python scripts to assist launchers, IDEs and other external tools which may need
147
to interact with such scripts.
@@ -73,20 +66,22 @@ In circumstances where there is a discrepancy between the text specification
7366
and the regular expression, the text specification takes precedence.
7467

7568
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.
7770

78-
pyproject type
79-
--------------
71+
script type
72+
-----------
8073

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).
8376

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.
8579

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

89-
The ``[run]`` table MAY include the following optional fields:
84+
The top-level fields are:
9085

9186
* ``dependencies``: A list of strings that specifies the runtime dependencies
9287
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
107102
Example
108103
-------
109104

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:
111106

112107
.. code:: python
113108
114-
# /// pyproject
109+
# /// script
115110
# [run]
116111
# requires-python = ">=3.11"
117112
# dependencies = [
@@ -127,23 +122,6 @@ The following is an example of a script with an embedded ``pyproject.toml``:
127122
data = resp.json()
128123
pprint([(k, v["title"]) for k, v in data.items()][:10])
129124
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-
}
147125
148126
Reference Implementation
149127
========================
@@ -159,7 +137,7 @@ higher.
159137
REGEX = r'(?m)^# /// (?P<type>[a-zA-Z0-9-]+)$\s(?P<content>(^#(| .*)$\s)+)^# ///$'
160138
161139
def read(script: str) -> dict | None:
162-
name = 'pyproject'
140+
name = 'script'
163141
matches = list(
164142
filter(lambda m: m.group('type') == name, re.finditer(REGEX, script))
165143
)
@@ -196,7 +174,7 @@ __ https://tomlkit.readthedocs.io/en/latest/
196174
)
197175
198176
config = tomlkit.parse(content)
199-
config['project']['dependencies'].append(dependency)
177+
config['dependencies'].append(dependency)
200178
new_content = ''.join(
201179
f'# {line}' if line.strip() else f'#{line}'
202180
for line in tomlkit.dumps(config).splitlines(keepends=True)
@@ -239,3 +217,7 @@ History
239217
=======
240218

241219
- 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

Comments
 (0)