PEP 561: Clarify \n

[adam-grant-hendry]

Stemming from this python discussion:

https://discuss.python.org/t/pep-561-clarification-regarding-n/32875/35

The purpose of this commit is to clarify the wording of the PEP where partial\n is concerned to state that the py.typed must contain the word partial and that partial should be on a line by itself.

---

📚 Documentation preview 📚: https://pep-previews--3428.org.readthedocs.build/

[AA-Turner]

This is a larger edit than I was expecting, especially given (as mentioned in the linked thread) that most Python programmers will read partial\n as "partial followed by a line break".

Perhaps just add a footnote?:

-If a stub package distribution is partial it MUST include ``partial\n`` in a
+If a stub package distribution is partial it MUST include ``partial\n`` [2]_ in a

In the footnotes section:

+.. _[2] ``partial\n`` should be read in the context of a Python string literal,
+        that is, the word "partial" followed by a single new line.

A

[merwok]

Same remark as Adam!

[adam-grant-hendry]

This is a larger edit than I was expecting, especially given (as mentioned in the linked thread) that most Python programmers will read partial\n as "partial followed by a line break".

Perhaps just add a footnote?:

-If a stub package distribution is partial it MUST include ``partial\n`` in a
+If a stub package distribution is partial it MUST include ``partial\n`` [2]_ in a

In the footnotes section:

+.. _[2] ``partial\n`` should be read in the context of a Python string literal,
+        that is, the word "partial" followed by a single new line.

A

When I read “string literal”, it makes me think I need to add partial\n verbatim. i.e. mypy is going to read in this string as a raw string from the file, which is worse.

Why not make the footnote:

The word partial should be on a separate line

This is just about POSIX convention anyway, which it seems from the discussion already goes without saying, so the \n is truly superfluous.

[merwok]

No, python devs should not mix up «string literal» (that can include escape codes) and «raw strings».

[AA-Turner]

I think we risk over-explaining (or just pedantry) here -- for a Python Enhancement Proposal, we do take some things as read, string literal being one of them.

A

[merwok]

Agreed. I read the whole discuss thread about this and got the general idea that most people interpreted it correctly, with only a possible ambiguity that we agree to make explicit with a footnote. Let’s not make a mountain out of a molehill.

[zooba]

If it's a string literal, put quotes around it: 'partial\n'. When read as rendered, it looks like literal text and there's no context to suggest it should be interpreted as escape sequences.

Saying it should be on a line by itself it the least ambiguous option and requires the least prior knowledge. It's also apparently how it has already been interpreted by the tools that read the file. I support this proposed change.

[adam-grant-hendry]

What if we just remove the \n and not add a footnote? Everybody wins: no risk of over-explaining and no room for misinterpretation.

[merwok]

If we change more than a footnote, I think we’d need approval by the author @ethanhs or @python/typing

[adam-grant-hendry]

What if we just remove the \n and not add a footnote? Everybody wins: no risk of over-explaining and no room for misinterpretation.

Great, let’s have that discussion. This PR is about removing the \n

[merwok]

I disagree, the PR is about making sure that people interpret the string partial\n correctly.
I think the PEP is correct in using that to say the word «partial» followed by a newline character (so that we’re sure it’s not another marker, or that we don’t force the exact bytes partial without a newline that is inserted that all good editors) in a concise way.
There is a little unclear point about acceptance of CRLF, and one (1) person who read it wrong and interpreted as backlash then n, that’s all we need to clarify here IMO. Please let’s not rehash the whole discuss thread here.