From a3defd3f55c39caff56d3a5b25c251ff921115db Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 7 Aug 2023 09:11:22 -0500 Subject: [PATCH] PEP 723: Correct the comparison with Rust (#3277) In working on the Rust design for single-file packages, we found that there were too many decisions to make up-front in an RFC, so we instead opted to approve an experiment (eRFC) to figure out the design incrementally and then come back with a final proposal. This implementation is considered unstable and requires a special flag (``-Zscript``) to access within the nightly builds of Rust. This commit updates the description of Rust's approach to align with these facts. Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com> --- pep-0723.rst | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) 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