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>
This commit is contained in:
Ed Page 2023-08-07 09:11:22 -05:00 committed by GitHub
parent 8da14ef515
commit a3defd3f55
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 24 additions and 15 deletions

View File

@ -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 <pyproject metadata_>`_ 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 <cargo embedded manifest_>`_ 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 <cargo embedded manifest_>`_
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