Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

gh-95913: Copyedit, link & format Typing Features section in 3.11 What's New #96097

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Sep 19, 2022
Merged

gh-95913: Copyedit, link & format Typing Features section in 3.11 What's New #96097

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5a32734
Ensure consistant headings, ref target labels & line breaks
CAM-Gerlach Aug 19, 2022
412671d
PEP 646: Copyedit & split description into two shorter paragraphs
CAM-Gerlach Aug 19, 2022
f36b343
PEP 655: Describe interaction with total more clearly & copyedit
CAM-Gerlach Aug 19, 2022
e13edd0
PEP 673: Link referred to PEP section directly & classmethod func
CAM-Gerlach Aug 19, 2022
814dbab
PEP 681: Copyedit for minor formatting/textual issues
CAM-Gerlach Aug 19, 2022
dc75401
PEP 563: Clarify wording, links/references and structure
CAM-Gerlach Aug 19, 2022
8bff5eb
Implement minor changes from review feedback
CAM-Gerlach Aug 19, 2022
346a23f
Apply further reviewer textual suggestions
CAM-Gerlach Aug 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
PEP 655: Describe interaction with total more clearly & copyedit
  • Loading branch information
@CAM-Gerlach
CAM-Gerlach committed Aug 19, 2022
commit f36b3438fffb21c290ed2109424749c92a838a31
17 changes: 9 additions & 8 deletions 17 Doc/whatsnew/3.11.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,21 +244,22 @@ PEP 655: Marking individual ``TypedDict`` items as required or not-required

:data:`~typing.Required` and :data:`~typing.NotRequired` provide a
straightforward way to mark whether individual items in a
:data:`~typing.TypedDict` must be present. Previously this was only possible
:class:`~typing.TypedDict` must be present. Previously, this was only possible
using inheritance.

Fields are still required by default, unless the ``total=False``
parameter is set.
For example, the following specifies a dictionary with one required and
one not-required key::
All fields are still required by default,
unless the *total* parameter is set to ``False``,
in which case all fields are still not-required by default.
For example, the following specifies a :class:`!TypedDict`
with one required and one not-required key::

class Movie(TypedDict):
title: str
year: NotRequired[int]

m1: Movie = {"title": "Black Panther", "year": 2018} # ok
m2: Movie = {"title": "Star Wars"} # ok (year is not required)
m3: Movie = {"year": 2022} # error (missing required field title)
m1: Movie = {"title": "Black Panther", "year": 2018} # OK
m2: Movie = {"title": "Star Wars"} # OK (year is not required)
m3: Movie = {"year": 2022} # ERROR (missing required field title)
Copy link
Member

@AlexWaygood AlexWaygood Aug 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the motivation for the ALLCAPS change here? It looks like shouting to me.

("OK" is fine but I'm not a fan of "ERROR".)

Copy link
Member Author

@CAM-Gerlach CAM-Gerlach Aug 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is intended to draw emphasis to the key contrast these examples are included to illustrate—the first and second are valid, while the third is invalid and produces an error. Also, "OK" is of course the correct, canonical capitalization of "OK", while it is "Error" is ALLCAPSed given the particular importance and best practice of prominently marking bad code as such.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"ERROR" still seems ugly and unnecessary to me; I don't really see the need for a change here.

Copy link
Member

@AlexWaygood AlexWaygood Aug 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also goes against the prevailing style in the typing docs — there are several # error comments, but none of them are ALLCAPS: https://docs.python.org/3/library/typing.html

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally, I value clarity and explicitness over subjective aesthetic preference, given a stated rationale. Also, I'm not sure how relevant the conventions of the typing stdlib doc are here, given it is a separate document from this one, and those particular choices may or may not have a clear, thought-out rationale.

But what do others think? @ezio-melotti @JelleZijlstra ?

If an all-caps ERROR is simply too objectionable, we can at least give it proper case

Suggested change
m3: Movie = {"year": 2022} # ERROR (missing required field title)
m3: Movie = {"year": 2022} # Error (missing required field title)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AlexWaygood what about if we go with @ezio-melotti 's suggestion and not ALLCAPSing Error, like this?

Suggested change
m3: Movie = {"year": 2022} # ERROR (missing required field title)
m3: Movie = {"year": 2022} # Error (title is required, but missing)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AlexWaygood what about if we go with @ezio-melotti 's suggestion and not ALLCAPSing Error, like this?

Sounds good to me.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For inline comments like these I tend to use all lowercase and no full stops at the end, so even ok and error would be fine with me.

Same, I don't add a period at the end either for inline or single-line comments...but I notice you do use period for titles (and commit summary lines), which slightly confuses me :) (To note, I do start them with a capital letter, which follows the examples in PEP 8 and avoids looking (IMO) sloppy—though that latter point is personal aesthetic preference)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, in this general document, I'd appreciate a subtle indication that this is a typing error -- not a SyntaxError or runtime exception. Perhaps Wrong, in whatever case you prefer.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a great point—to be more specific, we could say something like Type check error or Incompatible type


The following definition is equivalent::

Expand Down
Morty Proxy This is a proxified and sanitized view of the page, visit original site.