| **************************** |
| What's New In Python 3.10 |
| **************************** |
| |
| :Release: |release| |
| :Date: |today| |
| |
| .. Rules for maintenance: |
| |
| * Anyone can add text to this document. Do not spend very much time |
| on the wording of your changes, because your text will probably |
| get rewritten to some degree. |
| |
| * The maintainer will go through Misc/NEWS periodically and add |
| changes; it's therefore more important to add your changes to |
| Misc/NEWS than to this file. |
| |
| * This is not a complete list of every single change; completeness |
| is the purpose of Misc/NEWS. Some changes I consider too small |
| or esoteric to include. If such a change is added to the text, |
| I'll just remove it. (This is another reason you shouldn't spend |
| too much time on writing your addition.) |
| |
| * If you want to draw your new text to the attention of the |
| maintainer, add 'XXX' to the beginning of the paragraph or |
| section. |
| |
| * It's OK to just add a fragmentary note about a change. For |
| example: "XXX Describe the transmogrify() function added to the |
| socket module." The maintainer will research the change and |
| write the necessary text. |
| |
| * You can comment out your additions if you like, but it's not |
| necessary (especially when a final release is some months away). |
| |
| * Credit the author of a patch or bugfix. Just the name is |
| sufficient; the e-mail address isn't necessary. |
| |
| * It's helpful to add the bug/patch number as a comment: |
| |
| XXX Describe the transmogrify() function added to the socket |
| module. |
| (Contributed by P.Y. Developer in :issue:`12345`.) |
| |
| This saves the maintainer the effort of going through the Mercurial log |
| when researching a change. |
| |
| This article explains the new features in Python 3.10, compared to 3.9. |
| |
| For full details, see the :ref:`changelog <changelog>`. |
| |
| .. note:: |
| |
| Prerelease users should be aware that this document is currently in draft |
| form. It will be updated substantially as Python 3.10 moves towards release, |
| so it's worth checking back even after reading earlier versions. |
| |
| |
| Summary -- Release highlights |
| ============================= |
| |
| .. This section singles out the most important changes in Python 3.10. |
| Brevity is key. |
| |
| |
| .. PEP-sized items next. |
| |
| |
| |
| New Features |
| ============ |
| |
| .. _whatsnew310-pep563: |
| |
| Parenthesized context managers |
| ------------------------------ |
| |
| Using enclosing parentheses for continuation across multiple lines |
| in context managers is now supported. This allows formatting a long |
| collection of context managers in multiple lines in a similar way |
| as it was previously possible with import statements. For instance, |
| all these examples are now valid: |
| |
| .. code-block:: python |
| |
| with (CtxManager() as example): |
| ... |
| |
| with ( |
| CtxManager1(), |
| CtxManager2() |
| ): |
| ... |
| |
| with (CtxManager1() as example, |
| CtxManager2()): |
| ... |
| |
| with (CtxManager1(), |
| CtxManager2() as example): |
| ... |
| |
| with ( |
| CtxManager1() as example1, |
| CtxManager2() as example2 |
| ): |
| ... |
| |
| it is also possible to use a trailing comma at the end of the |
| enclosed group: |
| |
| .. code-block:: python |
| |
| with ( |
| CtxManager1() as example1, |
| CtxManager2() as example2, |
| CtxManager3() as example3, |
| ): |
| ... |
| |
| This new syntax uses the non LL(1) capacities of the new parser. |
| Check :pep:`617` for more details. |
| |
| (Contributed by Guido van Rossum, Pablo Galindo and Lysandros Nikolaou |
| in :issue:`12782` and :issue:`40334`.) |
| |
| |
| 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 '{'): |
| |
| .. code-block:: python |
| |
| 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: |
| |
| .. code-block:: text |
| |
| File "example.py", line 3 |
| some_other_code = foo() |
| ^ |
| SyntaxError: invalid syntax |
| |
| but in Python3.10 a more informative error is emitted: |
| |
| .. code-block:: text |
| |
| 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 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. |
| |
| (Contributed by Pablo Galindo in :issue:`42864` and Batuhan Taskaya in |
| :issue:`40176`.) |
| |
| PEP 626: Precise line numbers for debugging and other tools |
| ----------------------------------------------------------- |
| |
| PEP 626 brings more precise and reliable line numbers for debugging, profiling and coverage tools. |
| Tracing events, with the correct line number, are generated for all lines of code executed and only for lines of code that are executed. |
| |
| The ``f_lineo`` attribute of frame objects will always contain the expected line number. |
| |
| The ``co_lnotab`` attribute of code objects is deprecated and will be removed in 3.12. |
| Code that needs to convert from offset to line number should use the new ``co_lines()`` method instead. |
| |
| PEP 634: Structural Pattern Matching |
| ------------------------------------ |
| |
| Structural pattern matching has been added in the form of a *match statement* |
| and *case statements* of patterns with associated actions. Patterns |
| consist of sequences, mappings, primitive data types as well as class instances. |
| Pattern matching enables programs to extract information from complex data types, |
| branch on the structure of data, and apply specific actions based on different |
| forms of data. |
| |
| Syntax and operations |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| The generic syntax of pattern matching is:: |
| |
| match subject: |
| case <pattern_1>: |
| <action_1> |
| case <pattern_2>: |
| <action_2> |
| case <pattern_3>: |
| <action_3> |
| case _: |
| <action_wildcard> |
| |
| A match statement takes an expression and compares its value to successive |
| patterns given as one or more case blocks. Specifically, pattern matching |
| operates by: |
| |
| 1. using data with type and shape (the ``subject``) |
| 2. evaluating the ``subject`` in the ``match`` statement |
| 3. comparing the subject with each pattern in a ``case`` statement |
| from top to bottom until a match is confirmed. |
| 4. executing the action associated with the pattern of the confirmed |
| match |
| 5. If an exact match is not confirmed, the last case, a wildcard ``_``, |
| if provided, will be used as the matching case. If an exact match is |
| not confirmed and a wildcard case does not exists, the entire match |
| block is a no-op. |
| |
| Declarative approach |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| Readers may be aware of pattern matching through the simple example of matching |
| a subject (data object) to a literal (pattern) with the switch statement found |
| in C, Java or JavaScript (and many other languages). Often the switch statement |
| is used for comparison of an object/expression with case statements containing |
| literals. |
| |
| More powerful examples of pattern matching can be found in languages, such as |
| Scala and Elixir. With structural pattern matching, the approach is "declarative" and |
| explicitly states the conditions (the patterns) for data to match. |
| |
| While an "imperative" series of instructions using nested "if" statements |
| could be used to accomplish something similar to structural pattern matching, |
| it is less clear than the "declarative" approach. Instead the "declarative" |
| approach states the conditions to meet for a match and is more readable through |
| its explicit patterns. While structural pattern matching can be used in its |
| simplest form comparing a variable to a literal in a case statement, its |
| true value for Python lies in its handling of the subject's type and shape. |
| |
| Simple pattern: match to a literal |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Let's look at this example as pattern matching in its simplest form: a value, |
| the subject, being matched to several literals, the patterns. In the example |
| below, ``status`` is the subject of the match statement. The patterns are |
| each of the case statements, where literals represent request status codes. |
| The associated action to the case is executed after a match:: |
| |
| def http_error(status): |
| match status: |
| case 400: |
| return "Bad request" |
| case 404: |
| return "Not found" |
| case 418: |
| return "I'm a teapot" |
| case _: |
| return "Something's wrong with the Internet" |
| |
| If the above function is passed a ``status`` of 418, "I'm a teapot" is returned. |
| If the above function is passed a ``status`` of 500, the case statement with |
| ``_`` will match as a wildcard, and "Something's wrong with the Internet" is |
| returned. |
| Note the last block: the variable name, ``_``, acts as a *wildcard* and insures |
| the subject will always match. The use of ``_`` is optional. |
| |
| You can combine several literals in a single pattern using ``|`` ("or"):: |
| |
| case 401 | 403 | 404: |
| return "Not allowed" |
| |
| Behavior without the wildcard |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| If we modify the above example by removing the last case block, the example |
| becomes:: |
| |
| def http_error(status): |
| match status: |
| case 400: |
| return "Bad request" |
| case 404: |
| return "Not found" |
| case 418: |
| return "I'm a teapot" |
| |
| Without the use of ``_`` in a case statement, a match may not exist. If no |
| match exists, the behavior is a no-op. For example, if ``status`` of 500 is |
| passed, a no-op occurs. |
| |
| Patterns with a literal and variable |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| Patterns can look like unpacking assignments, and a pattern may be used to bind |
| variables. In this example, a data point can be unpacked to its x-coordinate |
| and y-coordinate:: |
| |
| # point is an (x, y) tuple |
| match point: |
| case (0, 0): |
| print("Origin") |
| case (0, y): |
| print(f"Y={y}") |
| case (x, 0): |
| print(f"X={x}") |
| case (x, y): |
| print(f"X={x}, Y={y}") |
| case _: |
| raise ValueError("Not a point") |
| |
| The first pattern has two literals, ``(0, 0)``, and may be thought of as an |
| extension of the literal pattern shown above. The next two patterns combine a |
| literal and a variable, and the variable *binds* a value from the subject |
| (``point``). The fourth pattern captures two values, which makes it |
| conceptually similar to the unpacking assignment ``(x, y) = point``. |
| |
| Patterns and classes |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| If you are using classes to structure your data, you can use as a pattern |
| the class name followed by an argument list resembling a constructor. This |
| pattern has the ability to capture class attributes into variables:: |
| |
| class Point: |
| x: int |
| y: int |
| |
| def location(point): |
| match point: |
| case Point(x=0, y=0): |
| print("Origin is the point's location.") |
| case Point(x=0, y=y): |
| print(f"Y={y} and the point is on the y-axis.") |
| case Point(x=x, y=0): |
| print(f"X={x} and the point is on the x-axis.") |
| case Point(): |
| print("The point is located somewhere else on the plane.") |
| case _: |
| print("Not a point") |
| |
| Patterns with positional parameters |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| You can use positional parameters with some builtin classes that provide an |
| ordering for their attributes (e.g. dataclasses). You can also define a specific |
| position for attributes in patterns by setting the ``__match_args__`` special |
| attribute in your classes. If it's set to ("x", "y"), the following patterns |
| are all equivalent (and all bind the ``y`` attribute to the ``var`` variable):: |
| |
| Point(1, var) |
| Point(1, y=var) |
| Point(x=1, y=var) |
| Point(y=var, x=1) |
| |
| Nested patterns |
| ~~~~~~~~~~~~~~~ |
| |
| Patterns can be arbitrarily nested. For example, if our data is a short |
| list of points, it could be matched like this:: |
| |
| match points: |
| case []: |
| print("No points in the list.") |
| case [Point(0, 0)]: |
| print("The origin is the only point in the list.") |
| case [Point(x, y)]: |
| print(f"A single point {x}, {y} is in the list.") |
| case [Point(0, y1), Point(0, y2)]: |
| print(f"Two points on the Y axis at {y1}, {y2} are in the list.") |
| case _: |
| print("Something else is found in the list.") |
| |
| Complex patterns and the wildcard |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| To this point, the examples have used ``_`` alone in the last case statement. |
| A wildcard can be used in more complex patterns, such as ``('error', code, _)``. |
| For example:: |
| |
| match test_variable: |
| case ('warning', code, 40): |
| print("A warning has been received.") |
| case ('error', code, _): |
| print(f"An error {code} occured.") |
| |
| In the above case, ``test_variable`` will match for ('error', code, 100) and |
| ('error', code, 800). |
| |
| Guard |
| ~~~~~ |
| |
| We can add an ``if`` clause to a pattern, known as a "guard". If the |
| guard is false, ``match`` goes on to try the next case block. Note |
| that value capture happens before the guard is evaluated:: |
| |
| match point: |
| case Point(x, y) if x == y: |
| print(f"The point is located on the diagonal Y=X at {x}.") |
| case Point(x, y): |
| print(f"Point is not on the diagonal.") |
| |
| Other Key Features |
| ~~~~~~~~~~~~~~~~~~ |
| |
| Several other key features: |
| |
| - Like unpacking assignments, tuple and list patterns have exactly the |
| same meaning and actually match arbitrary sequences. Technically, |
| the subject must be an instance of ``collections.abc.Sequence``. |
| Therefore, an important exception is that patterns don't match iterators. |
| Also, to prevent a common mistake, sequence patterns don't match strings. |
| |
| - Sequence patterns support wildcards: ``[x, y, *rest]`` and ``(x, y, |
| *rest)`` work similar to wildcards in unpacking assignments. The |
| name after ``*`` may also be ``_``, so ``(x, y, *_)`` matches a sequence |
| of at least two items without binding the remaining items. |
| |
| - Mapping patterns: ``{"bandwidth": b, "latency": l}`` captures the |
| ``"bandwidth"`` and ``"latency"`` values from a dict. Unlike sequence |
| patterns, extra keys are ignored. A wildcard ``**rest`` is also |
| supported. (But ``**_`` would be redundant, so it not allowed.) |
| |
| - Subpatterns may be captured using the ``as`` keyword:: |
| |
| case (Point(x1, y1), Point(x2, y2) as p2): ... |
| |
| This binds x1, y1, x2, y2 like you would expect without the ``as`` clause, |
| and p2 to the entire second item of the subject. |
| |
| - Most literals are compared by equality. However, the singletons ``True``, |
| ``False`` and ``None`` are compared by identity. |
| |
| - Named constants may be used in patterns. These named constants must be |
| dotted names to prevent the constant from being interpreted as a capture |
| variable:: |
| |
| from enum import Enum |
| class Color(Enum): |
| RED = 0 |
| GREEN = 1 |
| BLUE = 2 |
| |
| match color: |
| case Color.RED: |
| print("I see red!") |
| case Color.GREEN: |
| print("Grass is green") |
| case Color.BLUE: |
| print("I'm feeling the blues :(") |
| |
| For the full specification see :pep:`634`. Motivation and rationale |
| are in :pep:`635`, and a longer tutorial is in :pep:`636`. |
| |
| |
| New Features Related to Type Annotations |
| ======================================== |
| |
| This section covers major changes affecting :pep:`484` type annotations and |
| the :mod:`typing` module. |
| |
| |
| 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`.) |
| |
| |
| 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 |
| |
| |
| 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`.) |
| |
| |
| 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`.) |
| |
| * Assignment expressions can now be used unparenthesized within set literals |
| and set comprehensions, as well as in sequence indexes (but not slices). |
| |
| * Functions have a new ``__builtins__`` attribute which is used to look for |
| builtin symbols when a function is executed, instead of looking into |
| ``__globals__['__builtins__']``. The attribute is initialized from |
| ``__globals__["__builtins__"]`` if it exists, else from the current builtins. |
| (Contributed by Mark Shannon in :issue:`42990`.) |
| |
| * Two new builtin functions -- :func:`aiter` and :func:`anext` have been added |
| to provide asynchronous counterparts to :func:`iter` and :func:`next`, |
| respectively. |
| (Contributed by Joshua Bronson, Daniel Pope, and Justin Wang in :issue:`31861`.) |
| |
| |
| New Modules |
| =========== |
| |
| * None yet. |
| |
| |
| Improved Modules |
| ================ |
| |
| argparse |
| -------- |
| |
| Misleading phrase "optional arguments" was replaced with "options" in argparse help. Some tests might require adaptation if they rely on exact output match. |
| (Contributed by Raymond Hettinger in :issue:`9694`.) |
| |
| base64 |
| ------ |
| |
| Add :func:`base64.b32hexencode` and :func:`base64.b32hexdecode` to support the |
| Base32 Encoding with Extended Hex Alphabet. |
| |
| codecs |
| ------ |
| |
| Add a :func:`codecs.unregister` function to unregister a codec search function. |
| (Contributed by Hai Shi in :issue:`41842`.) |
| |
| collections.abc |
| --------------- |
| |
| The ``__args__`` of the :ref:`parameterized generic <types-genericalias>` for |
| :class:`collections.abc.Callable` are now consistent with :data:`typing.Callable`. |
| :class:`collections.abc.Callable` generic now flattens type parameters, similar |
| to what :data:`typing.Callable` currently does. This means that |
| ``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of |
| ``(int, str, str)``; previously this was ``([int, str], str)``. To allow this |
| change, :class:`types.GenericAlias` can now be subclassed, and a subclass will |
| be returned when subscripting the :class:`collections.abc.Callable` type. Note |
| that a :exc:`TypeError` may be raised for invalid forms of parameterizing |
| :class:`collections.abc.Callable` which may have passed silently in Python 3.9. |
| (Contributed by Ken Jin in :issue:`42195`.) |
| |
| contextlib |
| ---------- |
| |
| Add a :func:`contextlib.aclosing` context manager to safely close async generators |
| and objects representing asynchronously released resources. |
| (Contributed by Joongi Kim and John Belmonte in :issue:`41229`.) |
| |
| Add asynchronous context manager support to :func:`contextlib.nullcontext`. |
| (Contributed by Tom Gringauz in :issue:`41543`.) |
| |
| curses |
| ------ |
| |
| The extended color functions added in ncurses 6.1 will be used transparently |
| by :func:`curses.color_content`, :func:`curses.init_color`, |
| :func:`curses.init_pair`, and :func:`curses.pair_content`. A new function, |
| :func:`curses.has_extended_color_support`, indicates whether extended color |
| support is provided by the underlying ncurses library. |
| (Contributed by Jeffrey Kintscher and Hans Petter Jansson in :issue:`36982`.) |
| |
| The ``BUTTON5_*`` constants are now exposed in the :mod:`curses` module if |
| they are provided by the underlying curses library. |
| (Contributed by Zackery Spytz in :issue:`39273`.) |
| |
| .. _distutils-deprecated: |
| |
| distutils |
| --------- |
| |
| The entire ``distutils`` package is deprecated, to be removed in Python |
| 3.12. Its functionality for specifying package builds has already been |
| completely replaced by third-party packages ``setuptools`` and |
| ``packaging``, and most other commonly used APIs are available elsewhere |
| in the standard library (such as :mod:`platform`, :mod:`shutil`, |
| :mod:`subprocess` or :mod:`sysconfig`). There are no plans to migrate |
| any other functionality from ``distutils``, and applications that are |
| using other functions should plan to make private copies of the code. |
| Refer to :pep:`632` for discussion. |
| |
| The ``bdist_wininst`` command deprecated in Python 3.8 has been removed. |
| The ``bdist_wheel`` command is now recommended to distribute binary packages |
| on Windows. |
| (Contributed by Victor Stinner in :issue:`42802`.) |
| |
| doctest |
| ------- |
| |
| When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| (Contributed by Brett Cannon in :issue:`42133`.) |
| |
| encodings |
| --------- |
| |
| :func:`encodings.normalize_encoding` now ignores non-ASCII characters. |
| (Contributed by Hai Shi in :issue:`39337`.) |
| |
| gc |
| -- |
| |
| Added audit hooks for :func:`gc.get_objects`, :func:`gc.get_referrers` and |
| :func:`gc.get_referents`. (Contributed by Pablo Galindo in :issue:`43439`.) |
| |
| glob |
| ---- |
| |
| Added the *root_dir* and *dir_fd* parameters in :func:`~glob.glob` and |
| :func:`~glob.iglob` which allow to specify the root directory for searching. |
| (Contributed by Serhiy Storchaka in :issue:`38144`.) |
| |
| importlib.metadata |
| ------------------ |
| |
| Feature parity with ``importlib_metadata`` 3.7. |
| |
| :func:`importlib.metadata.entry_points` now provides a nicer experience |
| for selecting entry points by group and name through a new |
| :class:`importlib.metadata.EntryPoints` class. |
| |
| Added :func:`importlib.metadata.packages_distributions` for resolving |
| top-level Python modules and packages to their |
| :class:`importlib.metadata.Distribution`. |
| |
| inspect |
| ------- |
| |
| When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| (Contributed by Brett Cannon in :issue:`42133`.) |
| |
| Added *globalns* and *localns* parameters in :func:`~inspect.signature` and |
| :meth:`inspect.Signature.from_callable` to retrieve the annotations in given |
| local and global namespaces. |
| (Contributed by Batuhan Taskaya in :issue:`41960`.) |
| |
| linecache |
| --------- |
| |
| When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| (Contributed by Brett Cannon in :issue:`42133`.) |
| |
| os |
| -- |
| |
| Added :func:`os.cpu_count()` support for VxWorks RTOS. |
| (Contributed by Peixing Xin in :issue:`41440`.) |
| |
| Added a new function :func:`os.eventfd` and related helpers to wrap the |
| ``eventfd2`` syscall on Linux. |
| (Contributed by Christian Heimes in :issue:`41001`.) |
| |
| Added :func:`os.splice()` that allows to move data between two file |
| descriptors without copying between kernel address space and user |
| address space, where one of the file descriptors must refer to a |
| pipe. (Contributed by Pablo Galindo in :issue:`41625`.) |
| |
| Added :data:`~os.O_EVTONLY`, :data:`~os.O_FSYNC`, :data:`~os.O_SYMLINK` |
| and :data:`~os.O_NOFOLLOW_ANY` for macOS. |
| (Contributed by Dong-hee Na in :issue:`43106`.) |
| |
| pathlib |
| ------- |
| |
| Added slice support to :attr:`PurePath.parents <pathlib.PurePath.parents>`. |
| (Contributed by Joshua Cannon in :issue:`35498`) |
| |
| Added negative indexing support to :attr:`PurePath.parents |
| <pathlib.PurePath.parents>`. |
| (Contributed by Yaroslav Pankovych in :issue:`21041`) |
| |
| platform |
| -------- |
| |
| Added :func:`platform.freedesktop_os_release()` to retrieve operation system |
| identification from `freedesktop.org os-release |
| <https://www.freedesktop.org/software/systemd/man/os-release.html>`_ standard file. |
| (Contributed by Christian Heimes in :issue:`28468`) |
| |
| py_compile |
| ---------- |
| |
| Added ``--quiet`` option to command-line interface of :mod:`py_compile`. |
| (Contributed by Gregory Schevchenko in :issue:`38731`.) |
| |
| pyclbr |
| ------ |
| |
| Added an ``end_lineno`` attribute to the ``Function`` and ``Class`` |
| objects in the tree returned by :func:`pyclbr.readline` and |
| :func:`pyclbr.readline_ex`. It matches the existing (start) ``lineno``. |
| (Contributed by Aviral Srivastava in :issue:`38307`.) |
| |
| shelve |
| ------ |
| |
| The :mod:`shelve` module now uses :data:`pickle.DEFAULT_PROTOCOL` by default |
| instead of :mod:`pickle` protocol ``3`` when creating shelves. |
| (Contributed by Zackery Spytz in :issue:`34204`.) |
| |
| site |
| ---- |
| |
| When a module does not define ``__loader__``, fall back to ``__spec__.loader``. |
| (Contributed by Brett Cannon in :issue:`42133`.) |
| |
| socket |
| ------ |
| |
| The exception :exc:`socket.timeout` is now an alias of :exc:`TimeoutError`. |
| (Contributed by Christian Heimes in :issue:`42413`.) |
| |
| Added option to create MPTCP sockets with ``IPPROTO_MPTCP`` |
| (Contributed by Rui Cunha in :issue:`43571`.) |
| |
| sys |
| --- |
| |
| Add :data:`sys.orig_argv` attribute: the list of the original command line |
| arguments passed to the Python executable. |
| (Contributed by Victor Stinner in :issue:`23427`.) |
| |
| Add :data:`sys.stdlib_module_names`, containing the list of the standard library |
| module names. |
| (Contributed by Victor Stinner in :issue:`42955`.) |
| |
| _thread |
| ------- |
| |
| :func:`_thread.interrupt_main` now takes an optional signal number to |
| simulate (the default is still :data:`signal.SIGINT`). |
| (Contributed by Antoine Pitrou in :issue:`43356`.) |
| |
| threading |
| --------- |
| |
| Added :func:`threading.gettrace` and :func:`threading.getprofile` to |
| retrieve the functions set by :func:`threading.settrace` and |
| :func:`threading.setprofile` respectively. |
| (Contributed by Mario Corchero in :issue:`42251`.) |
| |
| Add :data:`threading.__excepthook__` to allow retrieving the original value |
| of :func:`threading.excepthook` in case it is set to a broken or a different |
| value. |
| (Contributed by Mario Corchero in :issue:`42308`.) |
| |
| traceback |
| --------- |
| |
| The :func:`~traceback.format_exception`, |
| :func:`~traceback.format_exception_only`, and |
| :func:`~traceback.print_exception` functions can now take an exception object |
| as a positional-only argument. |
| (Contributed by Zackery Spytz and Matthias Bussonnier in :issue:`26389`.) |
| |
| types |
| ----- |
| |
| Reintroduced the :data:`types.EllipsisType`, :data:`types.NoneType` |
| and :data:`types.NotImplementedType` classes, providing a new set |
| of types readily interpretable by type checkers. |
| (Contributed by Bas van Beek in :issue:`41810`.) |
| |
| 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. |
| |
| 1. ``Literal`` now de-duplicates parameters. |
| 2. Equality comparisons between ``Literal`` objects are now order independent. |
| 3. ``Literal`` comparisons now respects types. For example, |
| ``Literal[0] == Literal[False]`` previously evaluated to ``True``. It is |
| now ``False``. To support this change, the internally used type cache now |
| supports differentiating types. |
| 4. ``Literal`` objects will now raise a :exc:`TypeError` exception during |
| equality comparisons if one of their parameters are not :term:`immutable`. |
| Note that declaring ``Literal`` with mutable parameters will not throw |
| an error:: |
| |
| >>> from typing import Literal |
| >>> Literal[{0}] |
| >>> Literal[{0}] == Literal[{False}] |
| Traceback (most recent call last): |
| File "<stdin>", line 1, in <module> |
| TypeError: unhashable type: 'set' |
| |
| (Contributed by Yurii Karabas in :issue:`42345`.) |
| |
| unittest |
| -------- |
| |
| Add new method :meth:`~unittest.TestCase.assertNoLogs` to complement the |
| existing :meth:`~unittest.TestCase.assertLogs`. (Contributed by Kit Yan Choi |
| in :issue:`39385`.) |
| |
| urllib.parse |
| ------------ |
| |
| Python versions earlier than Python 3.10 allowed using both ``;`` and ``&`` as |
| query parameter separators in :func:`urllib.parse.parse_qs` and |
| :func:`urllib.parse.parse_qsl`. Due to security concerns, and to conform with |
| newer W3C recommendations, this has been changed to allow only a single |
| separator key, with ``&`` as the default. This change also affects |
| :func:`cgi.parse` and :func:`cgi.parse_multipart` as they use the affected |
| functions internally. For more details, please see their respective |
| documentation. |
| (Contributed by Adam Goldschmidt, Senthil Kumaran and Ken Jin in :issue:`42967`.) |
| |
| xml |
| --- |
| |
| Add a :class:`~xml.sax.handler.LexicalHandler` class to the |
| :mod:`xml.sax.handler` module. |
| (Contributed by Jonathan Gossage and Zackery Spytz in :issue:`35018`.) |
| |
| zipimport |
| --------- |
| Add methods related to :pep:`451`: :meth:`~zipimport.zipimporter.find_spec`, |
| :meth:`zipimport.zipimporter.create_module`, and |
| :meth:`zipimport.zipimporter.exec_module`. |
| (Contributed by Brett Cannon in :issue:`42131`. |
| |
| |
| Optimizations |
| ============= |
| |
| * Constructors :func:`str`, :func:`bytes` and :func:`bytearray` are now faster |
| (around 30--40% for small objects). |
| (Contributed by Serhiy Storchaka in :issue:`41334`.) |
| |
| * The :mod:`runpy` module now imports fewer modules. |
| The ``python3 -m module-name`` command startup time is 1.4x faster in |
| average. On Linux, ``python3 -I -m module-name`` imports 69 modules on Python |
| 3.9, whereas it only imports 51 modules (-18) on Python 3.10. |
| (Contributed by Victor Stinner in :issue:`41006` and :issue:`41718`.) |
| |
| * The ``LOAD_ATTR`` instruction now uses new "per opcode cache" mechanism. It |
| is about 36% faster now for regular attributes and 44% faster for slots. |
| (Contributed by Pablo Galindo and Yury Selivanov in :issue:`42093` and Guido |
| van Rossum in :issue:`42927`, based on ideas implemented originally in PyPy |
| and MicroPython.) |
| |
| * When building Python with ``--enable-optimizations`` now |
| ``-fno-semantic-interposition`` is added to both the compile and link line. |
| This speeds builds of the Python interpreter created with ``--enable-shared`` |
| with ``gcc`` by up to 30%. See `this article |
| <https://developers.redhat.com/blog/2020/06/25/red-hat-enterprise-linux-8-2-brings-faster-python-3-8-run-speeds/>`_ |
| for more details. (Contributed by Victor Stinner and Pablo Galindo in |
| :issue:`38980`.) |
| |
| |
| * Function parameters and their annotations are no longer computed at runtime, |
| but rather at compilation time. They are stored as a tuple of strings at the |
| bytecode level. It is now around 2 times faster to create a function with |
| parameter annotations. (Contributed by Yurii Karabas and Inada Naoki |
| in :issue:`42202`) |
| |
| * Substring search functions such as ``str1 in str2`` and ``str2.find(str1)`` |
| now sometimes use Crochemore & Perrin's "Two-Way" string searching |
| algorithm to avoid quadratic behavior on long strings. (Contributed |
| by Dennis Sweeney in :issue:`41972`) |
| |
| Deprecated |
| ========== |
| |
| * Starting in this release, there will be a concerted effort to begin |
| cleaning up old import semantics that were kept for Python 2.7 |
| compatibility. Specifically, |
| :meth:`~importlib.abc.PathEntryFinder.find_loader`/:meth:`~importlib.abc.Finder.find_module` |
| (superseded by :meth:`~importlib.abc.Finder.find_spec`), |
| :meth:`~importlib.abc.Loader.load_module` |
| (superseded by :meth:`~importlib.abc.Loader.exec_module`), |
| :meth:`~importlib.abc.Loader.module_repr` (which the import system |
| takes care of for you), the ``__package__`` attribute |
| (superseded by ``__spec__.parent``), the ``__loader__`` attribute |
| (superseded by ``__spec__.loader``), and the ``__cached__`` attribute |
| (superseded by ``__spec__.cached``) will slowly be removed (as well |
| as other classes and methods in :mod:`importlib`). |
| :exc:`ImportWarning` and/or :exc:`DeprecationWarning` will be raised |
| as appropriate to help identify code which needs updating during |
| this transition. |
| |
| * The entire ``distutils`` namespace is deprecated, to be removed in |
| Python 3.12. Refer to the :ref:`module changes <distutils-deprecated>` |
| section for more information. |
| |
| * Non-integer arguments to :func:`random.randrange` are deprecated. |
| The :exc:`ValueError` is deprecated in favor of a :exc:`TypeError`. |
| (Contributed by Serhiy Storchaka and Raymond Hettinger in :issue:`37319`.) |
| |
| * The various ``load_module()`` methods of :mod:`importlib` have been |
| documented as deprecated since Python 3.6, but will now also trigger |
| a :exc:`DeprecationWarning`. Use |
| :meth:`~importlib.abc.Loader.exec_module` instead. |
| (Contributed by Brett Cannon in :issue:`26131`.) |
| |
| * :meth:`zimport.zipimporter.load_module` has been deprecated in |
| preference for :meth:`~zipimport.zipimporter.exec_module`. |
| (Contributed by Brett Cannon in :issue:`26131`.) |
| |
| * The use of :meth:`~importlib.abc.Loader.load_module` by the import |
| system now triggers an :exc:`ImportWarning` as |
| :meth:`~importlib.abc.Loader.exec_module` is preferred. |
| (Contributed by Brett Cannon in :issue:`26131`.) |
| |
| * ``sqlite3.OptimizedUnicode`` has been undocumented and obsolete since Python |
| 3.3, when it was made an alias to :class:`str`. It is now deprecated, |
| scheduled for removal in Python 3.12. |
| (Contributed by Erlend E. Aasland in :issue:`42264`.) |
| |
| * The undocumented built-in function ``sqlite3.enable_shared_cache`` is now |
| deprecated, scheduled for removal in Python 3.12. Its use is strongly |
| discouraged by the SQLite3 documentation. See `the SQLite3 docs |
| <https://sqlite.org/c3ref/enable_shared_cache.html>`_ for more details. |
| If shared cache must be used, open the database in URI mode using the |
| ``cache=shared`` query parameter. |
| (Contributed by Erlend E. Aasland in :issue:`24464`.) |
| |
| |
| Removed |
| ======= |
| |
| * Removed special methods ``__int__``, ``__float__``, ``__floordiv__``, |
| ``__mod__``, ``__divmod__``, ``__rfloordiv__``, ``__rmod__`` and |
| ``__rdivmod__`` of the :class:`complex` class. They always raised |
| a :exc:`TypeError`. |
| (Contributed by Serhiy Storchaka in :issue:`41974`.) |
| |
| * The ``ParserBase.error()`` method from the private and undocumented ``_markupbase`` |
| module has been removed. :class:`html.parser.HTMLParser` is the only subclass of |
| ``ParserBase`` and its ``error()`` implementation has already been removed in |
| Python 3.5. |
| (Contributed by Berker Peksag in :issue:`31844`.) |
| |
| * Removed the ``unicodedata.ucnhash_CAPI`` attribute which was an internal |
| PyCapsule object. The related private ``_PyUnicode_Name_CAPI`` structure was |
| moved to the internal C API. |
| (Contributed by Victor Stinner in :issue:`42157`.) |
| |
| * Removed the ``parser`` module, which was deprecated in 3.9 due to the |
| switch to the new PEG parser, as well as all the C source and header files |
| that were only being used by the old parser, including ``node.h``, ``parser.h``, |
| ``graminit.h`` and ``grammar.h``. |
| |
| * Removed the Public C API functions :c:func:`PyParser_SimpleParseStringFlags`, |
| :c:func:`PyParser_SimpleParseStringFlagsFilename`, |
| :c:func:`PyParser_SimpleParseFileFlags` and :c:func:`PyNode_Compile` |
| that were deprecated in 3.9 due to the switch to the new PEG parser. |
| |
| * Removed the ``formatter`` module, which was deprecated in Python 3.4. |
| It is somewhat obsolete, little used, and not tested. It was originally |
| scheduled to be removed in Python 3.6, but such removals were delayed until |
| after Python 2.7 EOL. Existing users should copy whatever classes they use |
| into their code. |
| (Contributed by Dong-hee Na and Terry J. Reedy in :issue:`42299`.) |
| |
| * Removed the :c:func:`PyModule_GetWarningsModule` function that was useless |
| now due to the _warnings module was converted to a builtin module in 2.6. |
| (Contributed by Hai Shi in :issue:`42599`.) |
| |
| * Remove deprecated aliases to :ref:`collections-abstract-base-classes` from |
| the :mod:`collections` module. |
| (Contributed by Victor Stinner in :issue:`37324`.) |
| |
| * The ``loop`` parameter has been removed from most of :mod:`asyncio`\ 's |
| :doc:`high-level API <../library/asyncio-api-index>` following deprecation |
| in Python 3.8. The motivation behind this change is multifold: |
| |
| 1. This simplifies the high-level API. |
| 2. The functions in the high-level API have been implicitly getting the |
| current thread's running event loop since Python 3.7. There isn't a need to |
| pass the event loop to the API in most normal use cases. |
| 3. Event loop passing is error-prone especially when dealing with loops |
| running in different threads. |
| |
| Note that the low-level API will still accept ``loop``. |
| See `Changes in the Python API`_ for examples of how to replace existing code. |
| |
| (Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley |
| in :issue:`42392`.) |
| |
| |
| Porting to Python 3.10 |
| ====================== |
| |
| This section lists previously described changes and other bugfixes |
| that may require changes to your code. |
| |
| |
| Changes in the Python API |
| ------------------------- |
| |
| * The *etype* parameters of the :func:`~traceback.format_exception`, |
| :func:`~traceback.format_exception_only`, and |
| :func:`~traceback.print_exception` functions in the :mod:`traceback` module |
| have been renamed to *exc*. |
| (Contributed by Zackery Spytz and Matthias Bussonnier in :issue:`26389`.) |
| |
| * :mod:`atexit`: At Python exit, if a callback registered with |
| :func:`atexit.register` fails, its exception is now logged. Previously, only |
| some exceptions were logged, and the last exception was always silently |
| ignored. |
| (Contributed by Victor Stinner in :issue:`42639`.) |
| |
| * :class:`collections.abc.Callable` generic now flattens type parameters, similar |
| to what :data:`typing.Callable` currently does. This means that |
| ``collections.abc.Callable[[int, str], str]`` will have ``__args__`` of |
| ``(int, str, str)``; previously this was ``([int, str], str)``. Code which |
| accesses the arguments via :func:`typing.get_args` or ``__args__`` need to account |
| for this change. Furthermore, :exc:`TypeError` may be raised for invalid forms |
| of parameterizing :class:`collections.abc.Callable` which may have passed |
| silently in Python 3.9. |
| (Contributed by Ken Jin in :issue:`42195`.) |
| |
| * :meth:`socket.htons` and :meth:`socket.ntohs` now raise :exc:`OverflowError` |
| instead of :exc:`DeprecationWarning` if the given parameter will not fit in |
| a 16-bit unsigned integer. |
| (Contributed by Erlend E. Aasland in :issue:`42393`.) |
| |
| * The ``loop`` parameter has been removed from most of :mod:`asyncio`\ 's |
| :doc:`high-level API <../library/asyncio-api-index>` following deprecation |
| in Python 3.8. |
| |
| A coroutine that currently look like this:: |
| |
| async def foo(loop): |
| await asyncio.sleep(1, loop=loop) |
| |
| Should be replaced with this:: |
| |
| async def foo(): |
| await asyncio.sleep(1) |
| |
| If ``foo()`` was specifically designed *not* to run in the current thread's |
| running event loop (e.g. running in another thread's event loop), consider |
| using :func:`asyncio.run_coroutine_threadsafe` instead. |
| |
| (Contributed by Yurii Karabas, Andrew Svetlov, Yury Selivanov and Kyle Stanley |
| in :issue:`42392`.) |
| |
| * The :data:`types.FunctionType` constructor now inherits the current builtins |
| if the *globals* dictionary has no ``"__builtins__"`` key, rather than using |
| ``{"None": None}`` as builtins: same behavior as :func:`eval` and |
| :func:`exec` functions. Defining a function with ``def function(...): ...`` |
| in Python is not affected, globals cannot be overriden with this syntax: it |
| also inherits the current builtins. |
| (Contributed by Victor Stinner in :issue:`42990`.) |
| |
| CPython bytecode changes |
| ======================== |
| |
| * The ``MAKE_FUNCTION`` instruction accepts tuple of strings as annotations |
| instead of dictionary. |
| (Contributed by Yurii Karabas and Inada Naoki in :issue:`42202`) |
| |
| Build Changes |
| ============= |
| |
| * The C99 functions :c:func:`snprintf` and :c:func:`vsnprintf` are now required |
| to build Python. |
| (Contributed by Victor Stinner in :issue:`36020`.) |
| |
| * :mod:`sqlite3` requires SQLite 3.7.15 or higher. (Contributed by Sergey Fedoseev |
| and Erlend E. Aasland :issue:`40744` and :issue:`40810`.) |
| |
| * The :mod:`atexit` module must now always be built as a built-in module. |
| (Contributed by Victor Stinner in :issue:`42639`.) |
| |
| * Added ``--disable-test-modules`` option to the ``configure`` script: |
| don't build nor install test modules. |
| (Contributed by Xavier de Gaye, Thomas Petazzoni and Peixing Xin in :issue:`27640`.) |
| |
| * Add ``--with-wheel-pkg-dir=PATH`` option to the ``./configure`` script. If |
| specified, the :mod:`ensurepip` module looks for ``setuptools`` and ``pip`` |
| wheel packages in this directory: if both are present, these wheel packages |
| are used instead of ensurepip bundled wheel packages. |
| |
| Some Linux distribution packaging policies recommend against bundling |
| dependencies. For example, Fedora installs wheel packages in the |
| ``/usr/share/python-wheels/`` directory and don't install the |
| ``ensurepip._bundled`` package. |
| |
| (Contributed by Victor Stinner in :issue:`42856`.) |
| |
| * Add a new configure ``--without-static-libpython`` option to not build the |
| ``libpythonMAJOR.MINOR.a`` static library and not install the ``python.o`` |
| object file. |
| |
| (Contributed by Victor Stinner in :issue:`43103`.) |
| |
| * The ``configure`` script now uses the ``pkg-config`` utility, if available, |
| to detect the location of Tcl/Tk headers and libraries. As before, those |
| locations can be explicitly specified with the ``--with-tcltk-includes`` |
| and ``--with-tcltk-libs`` configuration options. |
| (Contributed by Manolis Stamatogiannakis in :issue:`42603`.) |
| |
| * Add ``--with-openssl-rpath`` option to ``configure`` script. The option |
| simplifies building Python with a custom OpenSSL installation, e.g. |
| ``./configure --with-openssl=/path/to/openssl --with-openssl-rpath=auto``. |
| (Contributed by Christian Heimes in :issue:`43466`.) |
| |
| |
| |
| C API Changes |
| ============= |
| |
| New Features |
| ------------ |
| |
| * The result of :c:func:`PyNumber_Index` now always has exact type :class:`int`. |
| Previously, the result could have been an instance of a subclass of ``int``. |
| (Contributed by Serhiy Storchaka in :issue:`40792`.) |
| |
| * Add a new :c:member:`~PyConfig.orig_argv` member to the :c:type:`PyConfig` |
| structure: the list of the original command line arguments passed to the |
| Python executable. |
| (Contributed by Victor Stinner in :issue:`23427`.) |
| |
| * The :c:func:`PyDateTime_DATE_GET_TZINFO` and |
| :c:func:`PyDateTime_TIME_GET_TZINFO` macros have been added for accessing |
| the ``tzinfo`` attributes of :class:`datetime.datetime` and |
| :class:`datetime.time` objects. |
| (Contributed by Zackery Spytz in :issue:`30155`.) |
| |
| * Add a :c:func:`PyCodec_Unregister` function to unregister a codec |
| search function. |
| (Contributed by Hai Shi in :issue:`41842`.) |
| |
| * The :c:func:`PyIter_Send` function was added to allow |
| sending value into iterator without raising ``StopIteration`` exception. |
| (Contributed by Vladimir Matveev in :issue:`41756`.) |
| |
| * Added :c:func:`PyUnicode_AsUTF8AndSize` to the limited C API. |
| (Contributed by Alex Gaynor in :issue:`41784`.) |
| |
| * Added :c:func:`PyModule_AddObjectRef` function: similar to |
| :c:func:`PyModule_AddObject` but don't steal a reference to the value on |
| success. |
| (Contributed by Victor Stinner in :issue:`1635741`.) |
| |
| * Added :c:func:`Py_NewRef` and :c:func:`Py_XNewRef` functions to increment the |
| reference count of an object and return the object. |
| (Contributed by Victor Stinner in :issue:`42262`.) |
| |
| * The :c:func:`PyType_FromSpecWithBases` and :c:func:`PyType_FromModuleAndSpec` |
| functions now accept a single class as the *bases* argument. |
| (Contributed by Serhiy Storchaka in :issue:`42423`.) |
| |
| * The :c:func:`PyType_FromModuleAndSpec` function now accepts NULL ``tp_doc`` |
| slot. |
| (Contributed by Hai Shi in :issue:`41832`.) |
| |
| * The :c:func:`PyType_GetSlot` function can accept static types. |
| (Contributed by Hai Shi and Petr Viktorin in :issue:`41073`.) |
| |
| * Add a new :c:func:`PySet_CheckExact` function to the C-API to check if an |
| object is an instance of :class:`set` but not an instance of a subtype. |
| (Contributed by Pablo Galindo in :issue:`43277`.) |
| |
| * Added :c:func:`PyErr_SetInterruptEx` which allows passing a signal number |
| to simulate. |
| (Contributed by Antoine Pitrou in :issue:`43356`.) |
| |
| |
| Porting to Python 3.10 |
| ---------------------- |
| |
| * The ``PY_SSIZE_T_CLEAN`` macro must now be defined to use |
| :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` formats which use |
| ``#``: ``es#``, ``et#``, ``s#``, ``u#``, ``y#``, ``z#``, ``U#`` and ``Z#``. |
| See :ref:`Parsing arguments and building values |
| <arg-parsing>` and the :pep:`353`. |
| (Contributed by Victor Stinner in :issue:`40943`.) |
| |
| * Since :c:func:`Py_REFCNT()` is changed to the inline static function, |
| ``Py_REFCNT(obj) = new_refcnt`` must be replaced with ``Py_SET_REFCNT(obj, new_refcnt)``: |
| see :c:func:`Py_SET_REFCNT()` (available since Python 3.9). For backward |
| compatibility, this macro can be used:: |
| |
| #if PY_VERSION_HEX < 0x030900A4 |
| # define Py_SET_REFCNT(obj, refcnt) ((Py_REFCNT(obj) = (refcnt)), (void)0) |
| #endif |
| |
| (Contributed by Victor Stinner in :issue:`39573`.) |
| |
| * Calling :c:func:`PyDict_GetItem` without :term:`GIL` held had been allowed |
| for historical reason. It is no longer allowed. |
| (Contributed by Victor Stinner in :issue:`40839`.) |
| |
| * ``PyUnicode_FromUnicode(NULL, size)`` and ``PyUnicode_FromStringAndSize(NULL, size)`` |
| raise ``DeprecationWarning`` now. Use :c:func:`PyUnicode_New` to allocate |
| Unicode object without initial data. |
| (Contributed by Inada Naoki in :issue:`36346`.) |
| |
| * The private ``_PyUnicode_Name_CAPI`` structure of the PyCapsule API |
| ``unicodedata.ucnhash_CAPI`` has been moved to the internal C API. |
| (Contributed by Victor Stinner in :issue:`42157`.) |
| |
| * :c:func:`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, |
| :c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome` and |
| :c:func:`Py_GetProgramName` functions now return ``NULL`` if called before |
| :c:func:`Py_Initialize` (before Python is initialized). Use the new |
| :ref:`Python Initialization Configuration API <init-config>` to get the |
| :ref:`Python Path Configuration. <init-path-config>`. |
| (Contributed by Victor Stinner in :issue:`42260`.) |
| |
| * :c:func:`PyList_SET_ITEM`, :c:func:`PyTuple_SET_ITEM` and |
| :c:func:`PyCell_SET` macros can no longer be used as l-value or r-value. |
| For example, ``x = PyList_SET_ITEM(a, b, c)`` and |
| ``PyList_SET_ITEM(a, b, c) = x`` now fail with a compiler error. It prevents |
| bugs like ``if (PyList_SET_ITEM (a, b, c) < 0) ...`` test. |
| (Contributed by Zackery Spytz and Victor Stinner in :issue:`30459`.) |
| |
| * The non-limited API files ``odictobject.h``, ``parser_interface.h``, |
| ``picklebufobject.h``, ``pyarena.h``, ``pyctype.h``, ``pydebug.h``, |
| ``pyfpe.h``, and ``pytime.h`` have been moved to the ``Include/cpython`` |
| directory. These files must not be included directly, as they are already |
| included in ``Python.h``: :ref:`Include Files <api-includes>`. If they have |
| been included directly, consider including ``Python.h`` instead. |
| (Contributed by Nicholas Sim in :issue:`35134`) |
| |
| Deprecated |
| ---------- |
| |
| * The ``PyUnicode_InternImmortal()`` function is now deprecated |
| and will be removed in Python 3.12: use :c:func:`PyUnicode_InternInPlace` |
| instead. |
| (Contributed by Victor Stinner in :issue:`41692`.) |
| |
| Removed |
| ------- |
| |
| * ``PyObject_AsCharBuffer()``, ``PyObject_AsReadBuffer()``, ``PyObject_CheckReadBuffer()``, |
| and ``PyObject_AsWriteBuffer()`` are removed. Please migrate to new buffer protocol; |
| :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release`. |
| (Contributed by Inada Naoki in :issue:`41103`.) |
| |
| * Removed ``Py_UNICODE_str*`` functions manipulating ``Py_UNICODE*`` strings. |
| (Contributed by Inada Naoki in :issue:`41123`.) |
| |
| * ``Py_UNICODE_strlen``: use :c:func:`PyUnicode_GetLength` or |
| :c:macro:`PyUnicode_GET_LENGTH` |
| * ``Py_UNICODE_strcat``: use :c:func:`PyUnicode_CopyCharacters` or |
| :c:func:`PyUnicode_FromFormat` |
| * ``Py_UNICODE_strcpy``, ``Py_UNICODE_strncpy``: use |
| :c:func:`PyUnicode_CopyCharacters` or :c:func:`PyUnicode_Substring` |
| * ``Py_UNICODE_strcmp``: use :c:func:`PyUnicode_Compare` |
| * ``Py_UNICODE_strncmp``: use :c:func:`PyUnicode_Tailmatch` |
| * ``Py_UNICODE_strchr``, ``Py_UNICODE_strrchr``: use |
| :c:func:`PyUnicode_FindChar` |
| |
| * Removed ``PyUnicode_GetMax()``. Please migrate to new (:pep:`393`) APIs. |
| (Contributed by Inada Naoki in :issue:`41103`.) |
| |
| * Removed ``PyLong_FromUnicode()``. Please migrate to :c:func:`PyLong_FromUnicodeObject`. |
| (Contributed by Inada Naoki in :issue:`41103`.) |
| |
| * Removed ``PyUnicode_AsUnicodeCopy()``. Please use :c:func:`PyUnicode_AsUCS4Copy` or |
| :c:func:`PyUnicode_AsWideCharString` |
| (Contributed by Inada Naoki in :issue:`41103`.) |
| |
| * Removed ``_Py_CheckRecursionLimit`` variable: it has been replaced by |
| ``ceval.recursion_limit`` of the :c:type:`PyInterpreterState` structure. |
| (Contributed by Victor Stinner in :issue:`41834`.) |
| |
| * Removed undocumented macros ``Py_ALLOW_RECURSION`` and |
| ``Py_END_ALLOW_RECURSION`` and the ``recursion_critical`` field of the |
| :c:type:`PyInterpreterState` structure. |
| (Contributed by Serhiy Storchaka in :issue:`41936`.) |
| |
| * Removed the undocumented ``PyOS_InitInterrupts()`` function. Initializing |
| Python already implicitly installs signal handlers: see |
| :c:member:`PyConfig.install_signal_handlers`. |
| (Contributed by Victor Stinner in :issue:`41713`.) |
| |
| * Remove the ``PyAST_Validate()`` function. It is no longer possible to build a |
| AST object (``mod_ty`` type) with the public C API. The function was already |
| excluded from the limited C API (:pep:`384`). |
| (Contributed by Victor Stinner in :issue:`43244`.) |
| |
| * Remove the ``symtable.h`` header file and the undocumented functions: |
| |
| * ``PyST_GetScope()`` |
| * ``PySymtable_Build()`` |
| * ``PySymtable_BuildObject()`` |
| * ``PySymtable_Free()`` |
| * ``Py_SymtableString()`` |
| * ``Py_SymtableStringObject()`` |
| |
| The ``Py_SymtableString()`` function was part the stable ABI by mistake but |
| it could not be used, because the ``symtable.h`` header file was excluded |
| from the limited C API. |
| |
| Use Python :mod:`symtable` module instead. |
| (Contributed by Victor Stinner in :issue:`43244`.) |
| |
| * Remove ``ast.h``, ``asdl.h``, and ``Python-ast.h`` header files. |
| These functions were undocumented and excluded from the limited C API. |
| Most names defined by these header files were not prefixed by ``Py`` and so |
| could create names conflicts. For example, ``Python-ast.h`` defined a |
| ``Yield`` macro which was conflict with the ``Yield`` name used by the |
| Windows ``<winbase.h>`` header. Use the Python :mod:`ast` module instead. |
| (Contributed by Victor Stinner in :issue:`43244`.) |
| |
| * Remove the compiler functions using ``struct _mod`` type, because the public |
| AST C API was removed: |
| |
| * ``PyAST_Compile()`` |
| * ``PyAST_CompileEx()`` |
| * ``PyAST_CompileObject()`` |
| * ``PyFuture_FromAST()`` |
| * ``PyFuture_FromASTObject()`` |
| |
| These functions were undocumented and excluded from the limited C API. |
| (Contributed by Victor Stinner in :issue:`43244`.) |