Skip to content

Commit

Permalink
Reorder contents of 3.10's What's New (#24687)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Fidget-Spinner
Fidget-Spinner committed Mar 3, 2021
1 parent 3a87e56 commit 727a68b
Showing 1 changed file with 129 additions and 113 deletions.
242 changes: 129 additions & 113 deletions Doc/whatsnew/3.10.rst
View file
Expand Up @@ -125,105 +125,48 @@ Check :pep:`617` for more details.
in :issue:`12782` and :issue:`40334`.)


PEP 563: Postponed Evaluation of Annotations Becomes Default
------------------------------------------------------------

In Python 3.7, postponed evaluation of annotations was added,
to be enabled with a ``from __future__ import annotations``
directive. In 3.10 this became the default behavior, even
without that future directive. With this being default, all
annotations stored in :attr:`__annotations__` will be strings.
If needed, annotations can be resolved at runtime using
:func:`typing.get_type_hints`. See :pep:`563` for a full
description. Also, the :func:`inspect.signature` will try to
resolve types from now on, and when it fails it will fall back to
showing the string annotations. (Contributed by Batuhan Taskaya
in :issue:`38605`.)

* The :class:`int` type has a new method :meth:`int.bit_count`, returning the
number of ones in the binary expansion of a given integer, also known
as the population count. (Contributed by Niklas Fiekas in :issue:`29882`.)

* The views returned by :meth:`dict.keys`, :meth:`dict.values` and
:meth:`dict.items` now all have a ``mapping`` attribute that gives a
:class:`types.MappingProxyType` object wrapping the original
dictionary. (Contributed by Dennis Sweeney in :issue:`40890`.)

* :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used
to require that all the iterables have an equal length.

PEP 613: TypeAlias Annotation
-----------------------------

:pep:`484` introduced the concept of type aliases, only requiring them to be
top-level unannotated assignments. This simplicity sometimes made it difficult
for type checkers to distinguish between type aliases and ordinary assignments,
especially when forward references or invalid types were involved. Compare::

StrCache = 'Cache[str]' # a type alias
LOG_PREFIX = 'LOG[DEBUG]' # a module constant

Now the :mod:`typing` module has a special annotation :data:`TypeAlias` to
declare type aliases more explicitly::

StrCache: TypeAlias = 'Cache[str]' # a type alias
LOG_PREFIX = 'LOG[DEBUG]' # a module constant

See :pep:`613` for more details.

(Contributed by Mikhail Golubev in :issue:`41923`.)

PEP 604: New Type Union Operator
--------------------------------

A new type union operator was introduced which enables the syntax ``X | Y``.
This provides a cleaner way of expressing 'either type X or type Y' instead of
using :data:`typing.Union`, especially in type hints (annotations).

In previous versions of Python, to apply a type hint for functions accepting
arguments of multiple types, :data:`typing.Union` was used::

def square(number: Union[int, float]) -> Union[int, float]:
return number ** 2
Better error messages in the parser
-----------------------------------

When parsing code that contains unclosed parentheses or brackets the interpreter
now includes the location of the unclosed bracket of parentheses instead of displaying
*SyntaxError: unexpected EOF while parsing* or pointing to some incorrect location.
For instance, consider the following code (notice the unclosed '{'):

Type hints can now be written in a more succinct manner::
.. code-block:: python
def square(number: int | float) -> int | float:
return number ** 2
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
38: 4, 39: 4, 45: 5, 46: 5, 47: 5, 48: 5, 49: 5, 54: 6,
some_other_code = foo()
previous versions of the interpreter reported confusing places as the location of
the syntax error:
This new syntax is also accepted as the second argument to :func:`isinstance`
and :func:`issubclass`::
.. code-block:: text
>>> isinstance(1, int | str)
True
File "example.py", line 3
some_other_code = foo()
^
SyntaxError: invalid syntax
See :ref:`types-union` and :pep:`604` for more details.
but in Python3.10 a more informative error is emitted:
(Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)
.. code-block:: text
PEP 612: Parameter Specification Variables
------------------------------------------
File "example.py", line 1
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
^
SyntaxError: '{' was never closed
Two new options to improve the information provided to static type checkers for
:pep:`484`\ 's ``Callable`` have been added to the :mod:`typing` module.
The first is the parameter specification variable. They are used to forward the
parameter types of one callable to another callable -- a pattern commonly
found in higher order functions and decorators. Examples of usage can be found
in :class:`typing.ParamSpec`. Previously, there was no easy way to type annotate
dependency of parameter types in such a precise manner.
In a similar way, errors involving unclosed string literals (single and triple
quoted) now point to the start of the string instead of reporting EOF/EOL.
The second option is the new ``Concatenate`` operator. It's used in conjunction
with parameter specification variables to type annotate a higher order callable
which adds or removes parameters of another callable. Examples of usage can
be found in :class:`typing.Concatenate`.
These improvements are inspired by previous work in the PyPy interpreter.
See :class:`typing.Callable`, :class:`typing.ParamSpec`,
:class:`typing.Concatenate` and :pep:`612` for more details.
(Contributed by Pablo Galindo in :issue:`42864` and Batuhan Taskaya in
:issue:`40176`.)
(Contributed by Ken Jin in :issue:`41559`.)
PEP 634: Structural Pattern Matching
------------------------------------
Expand Down Expand Up @@ -500,57 +443,128 @@ Several other key features:
For the full specification see :pep:`634`. Motivation and rationale
are in :pep:`635`, and a longer tutorial is in :pep:`636`.
Better error messages in the parser
-----------------------------------
When parsing code that contains unclosed parentheses or brackets the interpreter
now includes the location of the unclosed bracket of parentheses instead of displaying
*SyntaxError: unexpected EOF while parsing* or pointing to some incorrect location.
For instance, consider the following code (notice the unclosed '{'):
New Features Related to Type Annotations
========================================
.. code-block:: python
This section covers major changes affecting :pep:`484` type annotations and
the :mod:`typing` module.
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
38: 4, 39: 4, 45: 5, 46: 5, 47: 5, 48: 5, 49: 5, 54: 6,
some_other_code = foo()
previous versions of the interpreter reported confusing places as the location of
the syntax error:
PEP 563: Postponed Evaluation of Annotations Becomes Default
------------------------------------------------------------
.. code-block:: text
In Python 3.7, postponed evaluation of annotations was added,
to be enabled with a ``from __future__ import annotations``
directive. In 3.10 this became the default behavior, even
without that future directive. With this being default, all
annotations stored in :attr:`__annotations__` will be strings.
If needed, annotations can be resolved at runtime using
:func:`typing.get_type_hints`. See :pep:`563` for a full
description. Also, the :func:`inspect.signature` will try to
resolve types from now on, and when it fails it will fall back to
showing the string annotations. (Contributed by Batuhan Taskaya
in :issue:`38605`.)
File "example.py", line 3
some_other_code = foo()
^
SyntaxError: invalid syntax
but in Python3.10 a more informative error is emitted:
PEP 604: New Type Union Operator
--------------------------------
.. code-block:: text
A new type union operator was introduced which enables the syntax ``X | Y``.
This provides a cleaner way of expressing 'either type X or type Y' instead of
using :data:`typing.Union`, especially in type hints (annotations).
File "example.py", line 1
expected = {9: 1, 18: 2, 19: 2, 27: 3, 28: 3, 29: 3, 36: 4, 37: 4,
^
SyntaxError: '{' was never closed
In previous versions of Python, to apply a type hint for functions accepting
arguments of multiple types, :data:`typing.Union` was used::
def square(number: Union[int, float]) -> Union[int, float]:
return number ** 2
In a similar way, errors involving unclosed string literals (single and triple
quoted) now point to the start of the string instead of reporting EOF/EOL.
These improvements are inspired by previous work in the PyPy interpreter.
Type hints can now be written in a more succinct manner::
def square(number: int | float) -> int | float:
return number ** 2
This new syntax is also accepted as the second argument to :func:`isinstance`
and :func:`issubclass`::
>>> isinstance(1, int | str)
True
See :ref:`types-union` and :pep:`604` for more details.
(Contributed by Maggie Moss and Philippe Prados in :issue:`41428`.)
PEP 612: Parameter Specification Variables
------------------------------------------
Two new options to improve the information provided to static type checkers for
:pep:`484`\ 's ``Callable`` have been added to the :mod:`typing` module.
The first is the parameter specification variable. They are used to forward the
parameter types of one callable to another callable -- a pattern commonly
found in higher order functions and decorators. Examples of usage can be found
in :class:`typing.ParamSpec`. Previously, there was no easy way to type annotate
dependency of parameter types in such a precise manner.
The second option is the new ``Concatenate`` operator. It's used in conjunction
with parameter specification variables to type annotate a higher order callable
which adds or removes parameters of another callable. Examples of usage can
be found in :class:`typing.Concatenate`.
See :class:`typing.Callable`, :class:`typing.ParamSpec`,
:class:`typing.Concatenate` and :pep:`612` for more details.
(Contributed by Ken Jin in :issue:`41559`.)
PEP 613: TypeAlias Annotation
-----------------------------
:pep:`484` introduced the concept of type aliases, only requiring them to be
top-level unannotated assignments. This simplicity sometimes made it difficult
for type checkers to distinguish between type aliases and ordinary assignments,
especially when forward references or invalid types were involved. Compare::
StrCache = 'Cache[str]' # a type alias
LOG_PREFIX = 'LOG[DEBUG]' # a module constant
Now the :mod:`typing` module has a special annotation :data:`TypeAlias` to
declare type aliases more explicitly::
StrCache: TypeAlias = 'Cache[str]' # a type alias
LOG_PREFIX = 'LOG[DEBUG]' # a module constant
See :pep:`613` for more details.
(Contributed by Mikhail Golubev in :issue:`41923`.)
(Contributed by Pablo Galindo in :issue:`42864` and Batuhan Taskaya in
:issue:`40176`.)
Other Language Changes
======================
* The :class:`int` type has a new method :meth:`int.bit_count`, returning the
number of ones in the binary expansion of a given integer, also known
as the population count. (Contributed by Niklas Fiekas in :issue:`29882`.)
* The views returned by :meth:`dict.keys`, :meth:`dict.values` and
:meth:`dict.items` now all have a ``mapping`` attribute that gives a
:class:`types.MappingProxyType` object wrapping the original
dictionary. (Contributed by Dennis Sweeney in :issue:`40890`.)
* :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used
to require that all the iterables have an equal length.
* Builtin and extension functions that take integer arguments no longer accept
:class:`~decimal.Decimal`\ s, :class:`~fractions.Fraction`\ s and other
objects that can be converted to integers only with a loss (e.g. that have
the :meth:`~object.__int__` method but do not have the
:meth:`~object.__index__` method).
(Contributed by Serhiy Storchaka in :issue:`37999`.)
* If :func:`object.__ipow__` returns :const:`NotImplemented`, the operator will
correctly fall back to :func:`object.__pow__` and :func:`object.__rpow__` as expected.
(Contributed by Alex Shkop in :issue:`38302`.)
Expand Down Expand Up @@ -800,6 +814,8 @@ of types readily interpretable by type checkers.
typing
------
For major changes, see `New Features Related to Type Annotations`_.
The behavior of :class:`typing.Literal` was changed to conform with :pep:`586`
and to match the behavior of static type checkers specified in the PEP.
Expand Down

0 comments on commit 727a68b

Please sign in to comment.