Skip to content

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
encukou 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 6 commits
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
74 changes: 50 additions & 24 deletions Doc/whatsnew/3.11.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,25 +203,31 @@ Irit Katriel in :issue:`45607`.)


.. _new-feat-related-type-hints-311:
.. _whatsnew311-typing-features:

New Features Related to Type Hints
==================================

This section covers major changes affecting :pep:`484` type hints and
the :mod:`typing` module.


.. _whatsnew311-pep646:

PEP 646: Variadic generics
--------------------------

:pep:`484` introduced :data:`~typing.TypeVar`, enabling creation
of generics parameterised with a single type. :pep:`646` introduces
:pep:`484` previously introduced :data:`~typing.TypeVar`, enabling creation
of generics parameterised with a single type. :pep:`646` adds
:data:`~typing.TypeVarTuple`, enabling parameterisation
with an *arbitrary* number of types. In other words,
a :data:`~typing.TypeVarTuple` is a *variadic* type variable,
enabling *variadic* generics. This enables a wide variety of use cases.
enabling *variadic* generics.

This enables a wide variety of use cases.
In particular, it allows the type of array-like structures
in numerical computing libraries such as NumPy and TensorFlow to be
parameterised with the array *shape*. Static type checkers will now
parameterised with the array *shape*, and static type checkers will now
be able to catch shape-related bugs in code that uses these libraries.

See :pep:`646` for more details.
Expand All @@ -230,26 +236,30 @@ See :pep:`646` for more details.
Serhiy Storchaka and Jelle Zijlstra. PEP written by Mark Mendoza, Matthew
Rahtz, Pradeep Kumar Srinivasan, and Vincent Siles.)


.. _whatsnew311-pep655:

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

@AlexWaygood AlexWaygood Aug 19, 2022

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

@CAM-Gerlach CAM-Gerlach Aug 20, 2022

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

@CAM-Gerlach CAM-Gerlach Aug 20, 2022

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

@AlexWaygood AlexWaygood Aug 20, 2022

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

@CAM-Gerlach CAM-Gerlach Aug 20, 2022

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

@encukou encukou Sep 19, 2022

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

@CAM-Gerlach CAM-Gerlach Sep 19, 2022

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 All @@ -262,15 +272,20 @@ See :pep:`655` for more details.
(Contributed by David Foster and Jelle Zijlstra in :issue:`47087`. PEP
written by David Foster.)


.. _whatsnew311-pep673:

PEP 673: ``Self`` type
----------------------

The new :data:`~typing.Self` annotation provides a simple and intuitive
way to annotate methods that return an instance of their class. This
behaves the same as the :data:`~typing.TypeVar`-based approach specified
in :pep:`484` but is more concise and easier to follow.
behaves the same as the :data:`~typing.TypeVar`-based approach
:pep:`specified in PEP 484<484#annotating-instance-and-class-methods>`,
but is more concise and easier to follow.

Common use cases include alternative constructors provided as classmethods
Common use cases include alternative constructors provided as
:func:`classmethod <classmethod>`\s,
and :meth:`~object.__enter__` methods that return ``self``::

class MyLock:
Expand All @@ -295,6 +310,9 @@ See :pep:`673` for more details.
(Contributed by James Hilton-Balfe in :issue:`46534`. PEP written by
Pradeep Kumar Srinivasan and James Hilton-Balfe.)


.. _whatsnew311-pep675:

PEP 675: Arbitrary literal string type
--------------------------------------

Expand Down Expand Up @@ -329,14 +347,17 @@ See :pep:`675` for more details.
(Contributed by Jelle Zijlstra in :issue:`47088`. PEP written by Pradeep
Kumar Srinivasan and Graham Bleaney.)


.. _whatsnew311-pep681:

PEP 681: Data Class Transforms
------------------------------

:data:`~typing.dataclass_transform` may be used to
decorate a class, metaclass, or a function that is itself a decorator.
The presence of ``@dataclass_transform()`` tells a static type checker that the
decorated object performs runtime "magic" that
transforms a class, giving it :func:`dataclasses.dataclass`-like behaviors.
decorated object performs runtime "magic" that transforms a class,
giving it :func:`dataclass <dataclasses.dataclass>`-like behaviors.

For example::

Expand All @@ -348,26 +369,31 @@ For example::
cls.__ne__ = ...
return cls

# The create_model decorator can now be used to create new model
# classes, like this:
# The create_model decorator can now be used to create new model classes:
@create_model
class CustomerModel:
id: int
name: str

c = CustomerModel(id=327, name="John Smith")
c = CustomerModel(id=327, name="Eric Idle")

See :pep:`681` for more details.

(Contributed by Jelle Zijlstra in :gh:`91860`. PEP written by
Erik De Bonte and Eric Traut.)

PEP 563 May Not Be the Future

.. _whatsnew311-pep563-deferred:

PEP 563 may not be the future
-----------------------------

* :pep:`563` Postponed Evaluation of Annotations, ``__future__.annotations``
that was planned for this release has been indefinitely postponed.
See `this message <https://mail.python.org/archives/list/[email protected]/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/>`_ for more information.
:pep:`563` Postponed Evaluation of Annotations
(the ``from __future__ import annotations`` :ref:`future statement <future>`)
that was originally planned for release in Python 3.10 has been deferred again.
See `this message from the Steering Council <https://mail.python.org/archives/list/[email protected]/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/>`__
for more information.


Other Language Changes
======================
Expand Down