diff --git a/pep-0723.rst b/pep-0723.rst index cef338337..2b950614b 100644 --- a/pep-0723.rst +++ b/pep-0723.rst @@ -54,11 +54,11 @@ This PEP defines a mechanism for embedding metadata *within the script itself*, and not in an external file. We choose to follow the latest developments of other modern packaging -ecosystems (namely `Rust`__ and `Go`__) by embedding the existing +ecosystems (namely `Go`__ and provisionally `Rust`__) by embedding the existing `metadata standard `_ that is used to describe projects. -__ https://github.com/rust-lang/rfcs/blob/master/text/3424-cargo-script.md +__ https://rust-lang.github.io/rfcs/3424-cargo-script.html __ https://github.com/erning/gorun The format is intended to bridge the gap between different types of users @@ -139,8 +139,9 @@ The following is an example of a script with an embedded ``pyproject.toml``: data = resp.json() pprint([(k, v["title"]) for k, v in data.items()][:10]) -The following is an example of a single-file Rust project that embeds their -version of ``pyproject.toml``, which is called ``Cargo.toml``: +The following is an example of a proposed syntax for single-file Rust project +that embeds their equivalent of ``pyproject.toml``, +which is called ``Cargo.toml``: .. code:: rust @@ -156,19 +157,25 @@ version of ``pyproject.toml``, which is called ``Cargo.toml``: println!("Did our date match? {}", re.is_match("2014-01-01")); } -One important thing to note is that the metadata is embedded in a comment -mostly for introspection since Rust documentation is generated from comments. -Another is that users rarely edit dependencies manually, but rather use their -Cargo package manager. +One important thing to note is that the metadata is embedded in a +`doc-comment`_ (their equivalent of docstrings). +`Other syntaxes `_ are under consideration +within the Rust project, +including using attributes which are somewhat like a +syntactically recognized equivalent of dunder variables, +with the key difference between Rust's choice and this PEP being that +any valid Rust syntax will be allowed, +requiring one of the Rust syntax parsers to work with it, like `syn`__. -We argue that our choice, in comparison to the Rust format, is easier to read -and provides easier edits for humans by virtue of the contents starting at the -beginning of lines so would precisely match the contents of a -``pyproject.toml`` file. It is also is easier for tools to parse and modify -this continuous block of text which was `one of the concerns`__ raised in the -Rust pre-RFC. +__ https://crates.io/crates/syn -__ https://github.com/epage/cargo-script-mvs/blob/main/0000-cargo-script.md#embedded-manifest-format +We argue that our choice, in comparison to the `doc-comment`_ approach, +is easier to read and provides easier edits for humans by virtue +of the contents starting at the beginning of lines so would precisely match +the contents of a ``pyproject.toml`` file. +It is also is easier for tools to parse and modify this continuous block +of text which was `one of the concerns `_ +raised in the Rust pre-RFC. Reference Implementation ======================== @@ -561,6 +568,8 @@ References ========== .. _pyproject metadata: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/ +.. _doc-comment: https://doc.rust-lang.org/stable/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments +.. _cargo embedded manifest: https://github.com/epage/cargo-script-mvs/blob/main/0000-cargo-script.md#embedded-manifest-format .. _pip-run issue: https://github.com/jaraco/pip-run/issues/44 .. _pyproject without wheels: https://discuss.python.org/t/projects-that-arent-meant-to-generate-a-wheel-and-pyproject-toml/29684