Merge branch 'main' into sorting_techniques_edits

Doc/c-api/unicode.rst

@@ -317,7 +317,7 @@ These APIs can be used to work with surrogates:
 
 .. c:function:: Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)
 
- Join two surrogate characters and return a single :c:type:`Py_UCS4` value.
+ Join two surrogate code points and return a single :c:type:`Py_UCS4` value.
  *high* and *low* are respectively the leading and trailing surrogates in a
  surrogate pair. *high* must be in the range [0xD800; 0xDBFF] and *low* must
  be in the range [0xDC00; 0xDFFF].
@@ -999,6 +999,9 @@ These are the UTF-8 codec APIs:
  object. Error handling is "strict". Return ``NULL`` if an exception was
  raised by the codec.
 
+ The function fails if the string contains surrogate code points
+ (``U+D800`` - ``U+DFFF``).
+
 
 .. c:function:: const char* PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
 
@@ -1011,6 +1014,9 @@ These are the UTF-8 codec APIs:
  On error, set an exception, set *size* to ``-1`` (if it's not NULL) and
  return ``NULL``.
 
+ The function fails if the string contains surrogate code points
+ (``U+D800`` - ``U+DFFF``).
+
  This caches the UTF-8 representation of the string in the Unicode object, and
  subsequent calls will return a pointer to the same buffer. The caller is not
  responsible for deallocating the buffer. The buffer is deallocated and
@@ -1438,8 +1444,9 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
  Compare a Unicode object with a char buffer which is interpreted as
  being UTF-8 or ASCII encoded and return true (``1``) if they are equal,
  or false (``0``) otherwise.
- If the Unicode object contains surrogate characters or
- the C string is not valid UTF-8, false (``0``) is returned.
+ If the Unicode object contains surrogate code points
+ (``U+D800`` - ``U+DFFF``) or the C string is not valid UTF-8,
+ false (``0``) is returned.
 
  This function does not raise exceptions.
 

Doc/deprecations/pending-removal-in-3.16.rst

@@ -18,6 +18,14 @@ Pending Removal in Python 3.16
  Use the ``'w'`` format code (:c:type:`Py_UCS4`)
  for Unicode characters instead.
 
+* :mod:`asyncio`:
+
+ * :mod:`asyncio`:
+ :func:`!asyncio.iscoroutinefunction` is deprecated
+ and will be removed in Python 3.16,
+ use :func:`inspect.iscoroutinefunction` instead.
+ (Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
+
 * :mod:`shutil`:
 
  * The :class:`!ExecError` exception

Doc/library/functools.rst

@@ -543,6 +543,25 @@ The :mod:`functools` module defines the following functions:
  ... print(arg.real, arg.imag)
  ...
 
+ For code that dispatches on a collections type (e.g., ``list``), but wants
+ to typehint the items of the collection (e.g., ``list[int]``), the
+ dispatch type should be passed explicitly to the decorator itself with the
+ typehint going into the function definition::
+
+ >>> @fun.register(list)
+ ... def _(arg: list[int], verbose=False):
+ ... if verbose:
+ ... print("Enumerate this:")
+ ... for i, elem in enumerate(arg):
+ ... print(i, elem)
+
+ .. note::
+
+ At runtime the function will dispatch on an instance of a list regardless
+ of the type contained within the list i.e. ``[1,2,3]`` will be
+ dispatched the same as ``["foo", "bar", "baz"]``. The annotation
+ provided in this example is for static type checkers only and has no
+ runtime impact.
 
  To enable registering :term:`lambdas<lambda>` and pre-existing functions,
  the :func:`register` attribute can also be used in a functional form::

Doc/reference/expressions.rst

@@ -1807,6 +1807,7 @@ returns a boolean value regardless of the type of its argument
  single: assignment expression
  single: walrus operator
  single: named expression
+ pair: assignment; expression
 
 Assignment expressions
 ======================

Doc/whatsnew/3.13.rst

@@ -824,6 +824,24 @@ copy
  (Contributed by Serhiy Storchaka in :gh:`108751`.)
 
 
+ctypes
+------
+
+* As a consequence of necessary internal refactoring, initialization of
+ internal metaclasses now happens in ``__init__`` rather
+ than in ``__new__``. This affects projects that subclass these internal
+ metaclasses to provide custom initialization.
+ Generally:
+
+ - Custom logic that was done in ``__new__`` after calling ``super().__new__``
+ should be moved to ``__init__``.
+ - To create a class, call the metaclass, not only the metaclass's
+ ``__new__`` method.
+
+ See :gh:`124520` for discussion and links to changes in some affected
+ projects.
+
+
 dbm
 ---
 

Doc/whatsnew/3.14.rst

@@ -185,7 +185,7 @@ Other Language Changes
  ``python -O -c 'assert (__debug__ := 1)'`` now produces a
  :exc:`SyntaxError`. (Contributed by Irit Katriel in :gh:`122245`.)
 
-* Added class methods :meth:`float.from_number` and :meth:`complex.from_number`
+* Add class methods :meth:`float.from_number` and :meth:`complex.from_number`
  to convert a number to :class:`float` or :class:`complex` type correspondingly.
  They raise an error if the argument is a string.
  (Contributed by Serhiy Storchaka in :gh:`84978`.)
@@ -206,7 +206,7 @@ Improved Modules
 ast
 ---
 
-* Added :func:`ast.compare` for comparing two ASTs.
+* Add :func:`ast.compare` for comparing two ASTs.
  (Contributed by Batuhan Taskaya and Jeremy Hylton in :issue:`15987`.)
 
 * Add support for :func:`copy.replace` for AST nodes.
@@ -215,6 +215,9 @@ ast
 * Docstrings are now removed from an optimized AST in optimization level 2.
  (Contributed by Irit Katriel in :gh:`123958`.)
 
+* The ``repr()`` output for AST nodes now includes more information.
+ (Contributed by Tomas R in :gh:`116022`.)
+
 
 ctypes
 ------
@@ -233,32 +236,31 @@ ctypes
 dis
 ---
 
-* Added support for rendering full source location information of
+* Add support for rendering full source location information of
  :class:`instructions <dis.Instruction>`, rather than only the line number.
- This feature is added to the following interfaces via the ``show_positions``
+ This feature is added to the following interfaces via the *show_positions*
  keyword argument:
 
  - :class:`dis.Bytecode`,
  - :func:`dis.dis`, :func:`dis.distb`, and
  - :func:`dis.disassemble`.
 
  This feature is also exposed via :option:`dis --show-positions`.
-
  (Contributed by Bénédikt Tran in :gh:`123165`.)
 
 
 fractions
 ---------
 
-Added support for converting any objects that have the
-:meth:`!as_integer_ratio` method to a :class:`~fractions.Fraction`.
-(Contributed by Serhiy Storchaka in :gh:`82017`.)
+* Add support for converting any objects that have the
+ :meth:`!as_integer_ratio` method to a :class:`~fractions.Fraction`.
+ (Contributed by Serhiy Storchaka in :gh:`82017`.)
 
 
 functools
 ---------
 
-* Added support to :func:`functools.partial` and
+* Add support to :func:`functools.partial` and
  :func:`functools.partialmethod` for :data:`functools.Placeholder` sentinels
  to reserve a place for positional arguments.
  (Contributed by Dominykas Grigonis in :gh:`119127`.)
@@ -267,27 +269,27 @@ functools
 http
 ----
 
-Directory lists and error pages generated by the :mod:`http.server`
-module allow the browser to apply its default dark mode.
-(Contributed by Yorik Hansen in :gh:`123430`.)
+* Directory lists and error pages generated by the :mod:`http.server`
+ module allow the browser to apply its default dark mode.
+ (Contributed by Yorik Hansen in :gh:`123430`.)
 
 
 json
 ----
 
-Add notes for JSON serialization errors that allow to identify the source
-of the error.
-(Contributed by Serhiy Storchaka in :gh:`122163`.)
+* Add notes for JSON serialization errors that allow to identify the source
+ of the error.
+ (Contributed by Serhiy Storchaka in :gh:`122163`.)
 
-Enable :mod:`json` module to work as a script using the :option:`-m` switch: ``python -m json``.
-See the :ref:`JSON command-line interface <json-commandline>` documentation.
-(Contributed by Trey Hunner in :gh:`122873`.)
+* Enable the :mod:`json` module to work as a script using the :option:`-m` switch: ``python -m json``.
+ See the :ref:`JSON command-line interface <json-commandline>` documentation.
+ (Contributed by Trey Hunner in :gh:`122873`.)
 
 
 operator
 --------
 
-* Two new functions ``operator.is_none`` and ``operator.is_not_none``
+* Two new functions :func:`operator.is_none` and :func:`operator.is_not_none`
  have been added, such that ``operator.is_none(obj)`` is equivalent
  to ``obj is None`` and ``operator.is_not_none(obj)`` is equivalent
  to ``obj is not None``.
@@ -297,13 +299,13 @@ operator
 datetime
 --------
 
-Add :meth:`datetime.time.strptime` and :meth:`datetime.date.strptime`.
-(Contributed by Wannes Boeykens in :gh:`41431`.)
+* Add :meth:`datetime.time.strptime` and :meth:`datetime.date.strptime`.
+ (Contributed by Wannes Boeykens in :gh:`41431`.)
 
 os
 --
 
-* Added the :data:`os.environ.refresh() <os.environ>` method to update
+* Add the :data:`os.environ.refresh() <os.environ>` method to update
  :data:`os.environ` with changes to the environment made by :func:`os.putenv`,
  by :func:`os.unsetenv`, or made outside Python in the same process.
  (Contributed by Victor Stinner in :gh:`120057`.)
@@ -333,15 +335,15 @@ pdb
  :pdbcmd:`commands` are preserved across hard-coded breakpoints.
  (Contributed by Tian Gao in :gh:`121450`.)
 
-* Added a new argument ``mode`` to :class:`pdb.Pdb`. Disabled ``restart``
+* Add a new argument *mode* to :class:`pdb.Pdb`. Disable the ``restart``
  command when :mod:`pdb` is in ``inline`` mode.
  (Contributed by Tian Gao in :gh:`123757`.)
 
 pickle
 ------
 
 * Set the default protocol version on the :mod:`pickle` module to 5.
- For more details, please see :ref:`pickle protocols <pickle-protocols>`.
+ For more details, see :ref:`pickle protocols <pickle-protocols>`.
 
 * Add notes for pickle serialization errors that allow to identify the source
  of the error.
@@ -379,6 +381,12 @@ asyncio
 Deprecated
 ==========
 
+* :mod:`asyncio`:
+ :func:`!asyncio.iscoroutinefunction` is deprecated
+ and will be removed in Python 3.16,
+ use :func:`inspect.iscoroutinefunction` instead.
+ (Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
+
 * :mod:`builtins`:
  Passing a complex number as the *real* or *imag* argument in the
  :func:`complex` constructor is now deprecated; it should only be passed
@@ -437,7 +445,7 @@ ast
  user-defined ``visit_Num``, ``visit_Str``, ``visit_Bytes``,
  ``visit_NameConstant`` and ``visit_Ellipsis`` methods on custom
  :class:`ast.NodeVisitor` subclasses will no longer be called when the
- ``NodeVisitor`` subclass is visiting an AST. Define a ``visit_Constant``
+ :class:`!NodeVisitor` subclass is visiting an AST. Define a ``visit_Constant``
  method instead.
 
  Also, remove the following deprecated properties on :class:`ast.Constant`,
@@ -588,18 +596,18 @@ New Features
 * Add a new :c:type:`PyUnicodeWriter` API to create a Python :class:`str`
  object:
 
- * :c:func:`PyUnicodeWriter_Create`.
- * :c:func:`PyUnicodeWriter_Discard`.
- * :c:func:`PyUnicodeWriter_Finish`.
- * :c:func:`PyUnicodeWriter_WriteChar`.
- * :c:func:`PyUnicodeWriter_WriteUTF8`.
- * :c:func:`PyUnicodeWriter_WriteUCS4`.
- * :c:func:`PyUnicodeWriter_WriteWideChar`.
- * :c:func:`PyUnicodeWriter_WriteStr`.
- * :c:func:`PyUnicodeWriter_WriteRepr`.
- * :c:func:`PyUnicodeWriter_WriteSubstring`.
- * :c:func:`PyUnicodeWriter_Format`.
- * :c:func:`PyUnicodeWriter_DecodeUTF8Stateful`.
+ * :c:func:`PyUnicodeWriter_Create`
+ * :c:func:`PyUnicodeWriter_Discard`
+ * :c:func:`PyUnicodeWriter_Finish`
+ * :c:func:`PyUnicodeWriter_WriteChar`
+ * :c:func:`PyUnicodeWriter_WriteUTF8`
+ * :c:func:`PyUnicodeWriter_WriteUCS4`
+ * :c:func:`PyUnicodeWriter_WriteWideChar`
+ * :c:func:`PyUnicodeWriter_WriteStr`
+ * :c:func:`PyUnicodeWriter_WriteRepr`
+ * :c:func:`PyUnicodeWriter_WriteSubstring`
+ * :c:func:`PyUnicodeWriter_Format`
+ * :c:func:`PyUnicodeWriter_DecodeUTF8Stateful`
 
  (Contributed by Victor Stinner in :gh:`119182`.)
 
@@ -611,11 +619,11 @@ New Features
  is backwards incompatible to any C-Extension that holds onto an interned
  string after a call to :c:func:`Py_Finalize` and is then reused after a
  call to :c:func:`Py_Initialize`. Any issues arising from this behavior will
- normally result in crashes during the exectuion of the subsequent call to
+ normally result in crashes during the execution of the subsequent call to
  :c:func:`Py_Initialize` from accessing uninitialized memory. To fix, use
  an address sanitizer to identify any use-after-free coming from
  an interned string and deallocate it during module shutdown.
- (Contribued by Eddie Elizondo in :gh:`113601`.)
+ (Contributed by Eddie Elizondo in :gh:`113601`.)
 
 * Add new functions to convert C ``<stdint.h>`` numbers from/to Python
  :class:`int`:
@@ -691,12 +699,7 @@ Deprecated
  :c:macro:`!isfinite` available from :file:`math.h`
  since C99. (Contributed by Sergey B Kirpichev in :gh:`119613`.)
 
-* :func:`!asyncio.iscoroutinefunction` is deprecated
- and will be removed in Python 3.16,
- use :func:`inspect.iscoroutinefunction` instead.
- (Contributed by Jiahao Li and Kumar Aditya in :gh:`122875`.)
-
-.. Add deprecations above alphabetically, not here at the end.
+.. Add C API deprecations above alphabetically, not here at the end.
 
 .. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
 

Lib/pydoc.py

@@ -1870,6 +1870,7 @@ class Helper:
  ':': 'SLICINGS DICTIONARYLITERALS',
  '@': 'def class',
  '\\': 'STRINGS',
+ ':=': 'ASSIGNMENTEXPRESSIONS',
  '_': 'PRIVATENAMES',
  '__': 'PRIVATENAMES SPECIALMETHODS',
  '`': 'BACKQUOTES',
@@ -1963,6 +1964,7 @@ class Helper:
  'ASSERTION': 'assert',
  'ASSIGNMENT': ('assignment', 'AUGMENTEDASSIGNMENT'),
  'AUGMENTEDASSIGNMENT': ('augassign', 'NUMBERMETHODS'),
+ 'ASSIGNMENTEXPRESSIONS': ('assignment-expressions', ''),
  'DELETION': 'del',
  'RETURNING': 'return',
  'IMPORTING': 'import',

Lib/pydoc_data/topics.py

@@ -416,6 +416,34 @@
  'some expressions (like un-parenthesized tuple expressions) '
  'caused a\n'
  'syntax error.\n',
+ 'assignment-expressions': 'Assignment expressions\n'
+ '**********************\n'
+ '\n'
+ 'An assignment expression (sometimes also called a “named expression”'
+ '\nor “walrus”) assigns an expression to an identifier, while also\n'
+ 'returning the value of the expression.\n'
+ '\n'
+ 'One common use case is when handling matched regular expressions:\n'
+ '\n'
+ ' if matching := pattern.search(data):\n'
+ ' do_something(matching)\n'
+ '\n'
+ 'Or, when processing a file stream in chunks:\n'
+ '\n'
+ ' while chunk := file.read(9000):\n'
+ ' process(chunk)\n'
+ '\n'
+ 'Assignment expressions must be surrounded by parentheses when used as\n'
+ 'expression statements and when used as sub-expressions in slicing,\n'
+ 'conditional, lambda, keyword-argument, and comprehension-if\n'
+ 'expressions and in assert, with, and assignment statements. In all\n'
+ 'other places where they can be used, parentheses are not required,\n'
+ 'including in if and while statements.\n'
+ '\n'
+ 'Added in version 3.8.\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 572** - Assignment Expressions\n',
  'async': 'Coroutines\n'
  '**********\n'
  '\n'