PEP 621: Incorrect example for authors in pyproject.toml

[frgfm]

Hello there 👋

I believe that I spotted a mistake in the pyproject.toml example for the authors in PEP 621:

authors = [
  {email = "hi@pradyunsg.me"},
  {name = "Tzu-Ping Chung"}
]

while it should be:

authors = [
  {name = "Tzu-Ping Chung", email = "hi@pradyunsg.me"}
]

Let me know if I can help fixing that!

[CAM-Gerlach]

Thanks, but I can assure you that @pradyunsg and @uranusjr are two different people 😄

In more detail, the original example is perfectly valid, as the authors field is specified to be an array of tables (dictionaries), each containing one or both of the keys name and email. The modified field, however, is not only invalid PEP 621, but also invalid TOML syntax.

Sorry about that!

[Rosuav]

Would it be clearer if the entries had associated comments?

[pradyunsg]

Maybe? I'd actually tweak this example to add a full name+email entry in the middle. We'll cover this nuance better in the packaging.python.org pages for this spec though, which are being worked on right now.

I have a mild preference to not modify already accepted PEPs to make them better reference material on their own, but to direct folks to packaging.python.org instead.

[frgfm]

Yes sorry, I got confused:

• it is stated that the syntax for authors and maintainers is the same
• I way have missed the part saying "one of" the email and name is required
• thus in the example, we have a full maintainer example, but got confused with the authors part 😅

Adding an example with both name and email might clear that out indeed 👍 (from the email only, it's not obvious that it doesn't belong to the name person honestly)

[brettcannon]

I'm not sure if updating the PEP is the right place to be placing an example at this point. The official spec for [project] exists at https://packaging.python.org/en/latest/specifications/declaring-project-metadata/ (which #2684 is going to add a note to the PEP about), and so that's where I think people should be looking for details rather than the PEP as it will slowly drift out of sync with the spec.

[frgfm]

No worries if you think it's better to leave it this way. I only brought that up out of confusion 👍

[CAM-Gerlach]

Maybe? I'd actually tweak this example to add a full name+email entry in the middle. We'll cover this nuance better in the packaging.python.org pages for this spec though, which are being worked on right now.

Right now, the current spec over there doesn't currently have examples at all—is it the plan to add them, or something else? I don't seem to see any public discussion on that repo about what those plans are...is that occurring somewhere else?

One related ambiguity in the current spec, though—it states that both keys are optional, so would an empty table simply be ignored, an error or something else?

[brettcannon]

is it the plan to add them

No specific plan, but that doesn't say much either. 😉 I think I left them out when I wrote the docs simply because the other specs didn't have them. But that doesn't mean it wouldn't be a good idea to have examples.

it states that both keys are optional, so would an empty table simply be ignored, an error or something else?

The spec should have said both keys are optional, but at least one key is required. I've opened pypa/packaging.python.org#1103 to fix that.

[CAM-Gerlach]

No specific plan, but that doesn't say much either. wink I think I left them out when I wrote the docs simply because the other specs didn't have them. But that doesn't mean it wouldn't be a good idea to have examples.

Thanks for the insight! I think it would be a good idea to add them, FWIW, and could help with that, since its a pretty mechanical task. Diataxis advocates for succinct examples in reference material, and I find them to be a major aid to understanding when reading other PyPA specs, particularly if there's any ambiguity or lack of complete explicit detail in the specification text (which is often difficult to realize a priori as a spec author).

And as for the other specs, of those fully migrated to the spec page, it seems like they now pretty much all do (perhaps added later):

• Core Metadata, probably the closest equivalent, has them for each field
• Recording installed projects has some, a fact explicitly called out in the PEP
• Entry points has a number of examples
• Direct URL has a whole examples section
• The wheel spec has a few scattered throughout
• The .pypirc file spec is mostly examples

So really, now Declaring Project [Source] Metadata is the only odd one out 😆

The spec should have said both keys are optional, but at least one key is required. I've opened pypa/packaging.python.org#1103 to fix that.

💯