PEP 655: Marking individual TypedDict items as required

[davidfstr]

...or potentially missing

[gvanrossum]

FYI please use PEP number 655 (rename the file and change the pep number field).

[davidfstr]

First round of comments has been integrated. Ready for another round of review.

[davidfstr]

Oi. I just realized I linked to my TypeForm mypy issue when this is the Required PEP. Working on too many PEPs at once...

Let me just rewrite that reference...

[davidfstr]

Okay. Actually ready for code review again. ✨

[gvanrossum]

Since you apparently used git push -f, I can’t easily compare what you changed since my review, so I’ll just assume you addressed everything. :-)

However, I feel the PEP is pretty repetitive, with (almost) the same being said several times. That makes it look formal but not easy to read. Can you think of ways to improve this?

[davidfstr]

Since you apparently used git push -f, I can’t easily compare what you changed since my review, so I’ll just assume you addressed everything. :-)

I'll add incremental commits next time :-) Can always squash before commit.

I feel the PEP is pretty repetitive, with (almost) the same being said several times.

If it's a concern about length, the longest sections are {How to Teach This, Rejected Ideas}:

• "How to Teach This" in particular is meant as a standalone tutorial on how to use the syntax, so it certainly repeats some content from other sections. This section I think was most important when we only had Required (lacking NotRequired) and so I felt it necessary to explain the gymnastics with total=False that were necessary to selectively mark keys as not required. But now there's less need for a tutorial with NotRequired being directly spellable. I could see removing this section, perhaps integrating the guidance of preferring X|Y form when using Required[] elsewhere. ⭐

• "Rejected Ideas" is long because there were a lot of rejected ideas. :)

---

"Motivation", "Rationale", and "Specification" - which form the meat of the PEP - are each a handful of paragraphs when you ignore the illustrative code snippets. Not entirely clear what I can cut without losing content.

The most common example of a TypedDict I used (Movie) has 4 keys, and appears 8 times. Could reduce it to just 2 keys - one required and one potentially missing. What do you think? ⭐

---

Perhaps you could give specific examples of some items you found repetitive?

[gvanrossum]

"Permission to speak frankly, sir." :-) We always squash upon merge into master. My concern is really about repetitiveness, not length per se -- it's a short PEP, proposing a simple idea. (As you say, most of it is in Rejected Ideas -- and that is as it should be, since this simple idea was debated from many sides before it came out victorious. :-) First you explain the idea in the Abstract, and that's enough for someone interested in using the proposed feature. Then there's both Motivation and Rationale. I think the problem starts because the Motivation ends up showing by elaborate example exactly what the proposal is. I think you could end the Motivation at " Having to declare two different TypedDict types for this purpose is cumbersome.", cutting the next paragraph ("Instead, this PEP defines ...") and the two examples. (People looking for examples will find them in the Specification.) In Rationale, you could replace the Python version with a single line showing just ``` directors: Optional[List[str]] ``` and put the explanation "means `List[str]|None`, not potentially-missing" in the text rather than in a comment. The text explaining the need for `NotRequired` doesn't need another full example. In Specification, I recommend giving less airtime to `NotRequired` and using a shorter example class that's not called `Movie`. I also don't think you need to show examples of all the various places that are *not* allowed. The How to Teach This section doesn't have the entire tutorial in it (maybe this is not abundantly clear from PEPs 1 and 12). I honestly think that this feature is easy to teach and the section could just say that and refer to the two examples from the Specification. Finally (and this is not about length/repetitiveness) I wonder if we really need to prohibit the combinations `total=True / Required` and `total=False / NotRequired` -- I could see that some people might want to be explicit for all fields in a given class. What do you think of that?

…

On Wed, Feb 24, 2021 at 6:11 PM David Foster ***@***.***> wrote: Since you apparently used git push -f, I can’t easily compare what you changed since my review, so I’ll just assume you addressed everything. :-) I'll add incremental commits next time :-) Can always squash before commit. I feel the PEP is pretty repetitive, with (almost) the same being said several times. If it's a concern about length, the longest sections are {How to Teach This, Rejected Ideas}: - "How to Teach This" in particular is meant as a standalone tutorial on how to use the syntax, so it certainly repeats some content from other sections. This section I think was most important when we only had Required (lacking NotRequired) and so I felt it necessary to explain the gymnastics with total=False that were necessary to selectively mark keys as not required. But now there's less need for a tutorial with NotRequired being directly spellable. I could see removing this section, perhaps integrating the guidance of preferring X|Y form when using Required[] elsewhere. ⭐ - "Rejected Ideas" is long because there were a lot of rejected ideas. :) ------------------------------ "Motivation", "Rationale", and "Specification" - which form the meat of the PEP - are each a handful of paragraphs when you ignore the illustrative code snippets. Not entirely clear what I can cut without losing content. The most common example of a TypedDict I used (Movie) has 4 keys, and appears 8 times. Could reduce it to just 2 keys - one required and one potentially missing. What do you think? ⭐ ------------------------------ Perhaps you could give specific examples of some items you found repetitive? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1829 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAWCWMXGR5CJNH6HTYE5ND3TAWWTJANCNFSM4X7K3RUA> .

-- --Guido van Rossum (python.org/~guido)

[davidfstr]

Thanks for taking the time to provide more detailed feedback! Definitely applying the "less is more" principle in this latest revision. :)

I did remove the restriction disallowing Required[] and NotRequired[] in redundant locations, since I agree that think there may be some folks who want to be explicit about requiredness for all keys.

[gvanrossum]

LGTM. Thanks for shortening the main text quite a bit from the first revision! I'll merge now and then you can post to typing-sig again (and send a tiny PR with an updated post-history).