Merge branch 'python:main' into main

.github/CODEOWNERS

@@ -11,7 +11,7 @@
 configure* @erlend-aasland @corona10
 
 # asyncio
-**/*asyncio* @1st1 @asvetlov @gvanrossum @kumaraditya303
+**/*asyncio* @1st1 @asvetlov @gvanrossum @kumaraditya303 @willingc
 
 # Core
 **/*context* @1st1

.github/workflows/doc.yml

@@ -56,11 +56,13 @@ jobs:
 
  # Add pull request annotations for Sphinx nitpicks (missing references)
  - name: 'Get list of changed files'
+ if: github.event_name == 'pull_request'
  id: changed_files
  uses: Ana06/get-changed-files@v2.2.0
  with:
  filter: "Doc/**"
  - name: 'Build changed files in nit-picky mode'
+ if: github.event_name == 'pull_request'
  continue-on-error: true
  run: |
  # Mark files the pull request modified

Doc/c-api/unicode.rst

@@ -509,6 +509,15 @@ APIs:
  arguments.
 
 
+.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
+
+ Copy an instance of a Unicode subtype to a new true Unicode object if
+ necessary. If *obj* is already a true Unicode object (not a subtype),
+ return the reference with incremented refcount.
+
+ Objects other than Unicode or its subtypes will cause a :exc:`TypeError`.
+
+
 .. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, \
  const char *encoding, const char *errors)
 
@@ -616,15 +625,6 @@ APIs:
  .. versionadded:: 3.3
 
 
-.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
-
- Copy an instance of a Unicode subtype to a new true Unicode object if
- necessary. If *obj* is already a true Unicode object (not a subtype),
- return the reference with incremented refcount.
-
- Objects other than Unicode or its subtypes will cause a :exc:`TypeError`.
-
-
 Locale Encoding
 """""""""""""""
 

Doc/constraints.txt

@@ -0,0 +1,29 @@
+# We have upper bounds on our transitive dependencies here
+# To avoid new releases unexpectedly breaking our build.
+# This file can be updated on an ad-hoc basis,
+# though it will probably have to be updated
+# whenever Doc/requirements.txt is updated.
+
+# Direct dependencies of Sphinx
+babel<3
+colorama<0.5
+imagesize<1.5
+Jinja2<3.2
+packaging<24
+# Pygments==2.15.0 breaks CI
+Pygments<2.16,!=2.15.0
+requests<3
+snowballstemmer<3
+sphinxcontrib-applehelp<1.1
+sphinxcontrib-devhelp<1.1
+sphinxcontrib-htmlhelp<2.1
+sphinxcontrib-jsmath<1.1
+sphinxcontrib-qthelp<1.1
+sphinxcontrib-serializinghtml<1.2
+
+# Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
+MarkupSafe<2.2
+
+# Direct dependencies of sphinx-lint
+polib<1.3
+regex<2024

Doc/library/asyncio-eventloop.rst

@@ -1438,9 +1438,7 @@ async/await code consider using the high-level
 
  * *stdin* can be any of these:
 
- * a file-like object representing a pipe to be connected to the
- subprocess's standard input stream using
- :meth:`~loop.connect_write_pipe`
+ * a file-like object
  * the :const:`subprocess.PIPE` constant (default) which will create a new
  pipe and connect it,
  * the value ``None`` which will make the subprocess inherit the file
@@ -1450,9 +1448,7 @@ async/await code consider using the high-level
 
  * *stdout* can be any of these:
 
- * a file-like object representing a pipe to be connected to the
- subprocess's standard output stream using
- :meth:`~loop.connect_write_pipe`
+ * a file-like object
  * the :const:`subprocess.PIPE` constant (default) which will create a new
  pipe and connect it,
  * the value ``None`` which will make the subprocess inherit the file
@@ -1462,9 +1458,7 @@ async/await code consider using the high-level
 
  * *stderr* can be any of these:
 
- * a file-like object representing a pipe to be connected to the
- subprocess's standard error stream using
- :meth:`~loop.connect_write_pipe`
+ * a file-like object
  * the :const:`subprocess.PIPE` constant (default) which will create a new
  pipe and connect it,
  * the value ``None`` which will make the subprocess inherit the file
@@ -1483,6 +1477,11 @@ async/await code consider using the high-level
  as text. :func:`bytes.decode` can be used to convert the bytes returned
  from the stream to text.
 
+ If a file-like object passed as *stdin*, *stdout* or *stderr* represents a
+ pipe, then the other side of this pipe should be registered with
+ :meth:`~loop.connect_write_pipe` or :meth:`~loop.connect_read_pipe` for use
+ with the event loop.
+
  See the constructor of the :class:`subprocess.Popen` class
  for documentation on other arguments.
 

Doc/library/smtplib.rst

@@ -25,7 +25,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
 
  An :class:`SMTP` instance encapsulates an SMTP connection. It has methods
  that support a full repertoire of SMTP and ESMTP operations. If the optional
- host and port parameters are given, the SMTP :meth:`connect` method is
+ *host* and *port* parameters are given, the SMTP :meth:`connect` method is
  called with those parameters during initialization. If specified,
  *local_hostname* is used as the FQDN of the local host in the HELO/EHLO
  command. Otherwise, the local hostname is found using
@@ -34,12 +34,12 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
  *timeout* parameter specifies a timeout in seconds for blocking operations
  like the connection attempt (if not specified, the global default timeout
  setting will be used). If the timeout expires, :exc:`TimeoutError` is
- raised. The optional source_address parameter allows binding
+ raised. The optional *source_address* parameter allows binding
  to some specific source address in a machine with multiple network
  interfaces, and/or to some specific source TCP port. It takes a 2-tuple
- (host, port), for the socket to bind to as its source address before
- connecting. If omitted (or if host or port are ``''`` and/or 0 respectively)
- the OS default behavior will be used.
+ ``(host, port)``, for the socket to bind to as its source address before
+ connecting. If omitted (or if *host* or *port* are ``''`` and/or ``0``
+ respectively) the OS default behavior will be used.
 
  For normal use, you should only require the initialization/connect,
  :meth:`sendmail`, and :meth:`SMTP.quit` methods.

Doc/library/sqlite3.rst

@@ -573,6 +573,38 @@ Module constants
  package, a third-party library which used to upstream changes to
  :mod:`!sqlite3`. Today, it carries no meaning or practical value.
 
+.. _sqlite3-dbconfig-constants:
+
+.. data:: SQLITE_DBCONFIG_DEFENSIVE
+ SQLITE_DBCONFIG_DQS_DDL
+ SQLITE_DBCONFIG_DQS_DML
+ SQLITE_DBCONFIG_ENABLE_FKEY
+ SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER
+ SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
+ SQLITE_DBCONFIG_ENABLE_QPSG
+ SQLITE_DBCONFIG_ENABLE_TRIGGER
+ SQLITE_DBCONFIG_ENABLE_VIEW
+ SQLITE_DBCONFIG_LEGACY_ALTER_TABLE
+ SQLITE_DBCONFIG_LEGACY_FILE_FORMAT
+ SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE
+ SQLITE_DBCONFIG_RESET_DATABASE
+ SQLITE_DBCONFIG_TRIGGER_EQP
+ SQLITE_DBCONFIG_TRUSTED_SCHEMA
+ SQLITE_DBCONFIG_WRITABLE_SCHEMA
+
+ These constants are used for the :meth:`Connection.setconfig`
+ and :meth:`~Connection.getconfig` methods.
+
+ The availability of these constants varies depending on the version of SQLite
+ Python was compiled with.
+
+ .. versionadded:: 3.12
+
+ .. seealso::
+
+ https://www.sqlite.org/c3ref/c_dbconfig_defensive.html
+ SQLite docs: Database Connection Configuration Options
+
 
 .. _sqlite3-connection-objects:
 
@@ -1041,19 +1073,37 @@ Connection objects
  (2, 'broccoli pie', 'broccoli cheese onions flour')
  (3, 'pumpkin pie', 'pumpkin sugar flour butter')
 
- .. method:: load_extension(path, /)
+ .. method:: load_extension(path, /, *, entrypoint=None)
 
- Load an SQLite extension from a shared library located at *path*.
+ Load an SQLite extension from a shared library.
  Enable extension loading with :meth:`enable_load_extension` before
  calling this method.
 
+ :param str path:
+
+ The path to the SQLite extension.
+
+ :param entrypoint:
+
+ Entry point name.
+ If ``None`` (the default),
+ SQLite will come up with an entry point name of its own;
+ see the SQLite docs `Loading an Extension`_ for details.
+
+ :type entrypoint: str | None
+
  .. audit-event:: sqlite3.load_extension connection,path sqlite3.Connection.load_extension
 
  .. versionadded:: 3.2
 
  .. versionchanged:: 3.10
  Added the ``sqlite3.load_extension`` auditing event.
 
+ .. versionadded:: 3.12
+ The *entrypoint* parameter.
+
+ .. _Loading an Extension: https://www.sqlite.org/loadext.html#loading_an_extension_
+
  .. method:: iterdump
 
  Return an :term:`iterator` to dump the database as SQL source code.
@@ -1201,6 +1251,30 @@ Connection objects
  .. _SQLite limit category: https://www.sqlite.org/c3ref/c_limit_attached.html
 
 
+ .. method:: getconfig(op, /)
+
+ Query a boolean connection configuration option.
+
+ :param int op:
+ A :ref:`SQLITE_DBCONFIG code <sqlite3-dbconfig-constants>`.
+
+ :rtype: bool
+
+ .. versionadded:: 3.12
+
+ .. method:: setconfig(op, enable=True, /)
+
+ Set a boolean connection configuration option.
+
+ :param int op:
+ A :ref:`SQLITE_DBCONFIG code <sqlite3-dbconfig-constants>`.
+
+ :param bool enable:
+ ``True`` if the configuration option should be enabled (default);
+ ``False`` if it should be disabled.
+
+ .. versionadded:: 3.12
+
  .. method:: serialize(*, name="main")
 
  Serialize a database into a :class:`bytes` object. For an

Doc/library/typing.rst

@@ -98,6 +98,9 @@ annotations. These include:
  *Introducing* :data:`LiteralString`
 * :pep:`681`: Data Class Transforms
  *Introducing* the :func:`@dataclass_transform<dataclass_transform>` decorator
+* :pep:`692`: Using ``TypedDict`` for more precise ``**kwargs`` typing
+ *Introducing* a new way of typing ``**kwargs`` with :data:`Unpack` and
+ :data:`TypedDict`
 * :pep:`698`: Adding an override decorator to typing
  *Introducing* the :func:`@override<override>` decorator
 
@@ -1417,8 +1420,10 @@ These are not used in annotations. They are building blocks for creating generic
  tup: tuple[Unpack[Ts]]
 
  In fact, ``Unpack`` can be used interchangeably with ``*`` in the context
- of types. You might see ``Unpack`` being used explicitly in older versions
- of Python, where ``*`` couldn't be used in certain places::
+ of :class:`typing.TypeVarTuple <TypeVarTuple>` and
+ :class:`builtins.tuple <tuple>` types. You might see ``Unpack`` being used
+ explicitly in older versions of Python, where ``*`` couldn't be used in
+ certain places::
 
  # In older versions of Python, TypeVarTuple and Unpack
  # are located in the `typing_extensions` backports package.
@@ -1428,6 +1433,21 @@ These are not used in annotations. They are building blocks for creating generic
  tup: tuple[*Ts] # Syntax error on Python <= 3.10!
  tup: tuple[Unpack[Ts]] # Semantically equivalent, and backwards-compatible
 
+ ``Unpack`` can also be used along with :class:`typing.TypedDict` for typing
+ ``**kwargs`` in a function signature::
+
+ from typing import TypedDict, Unpack
+
+ class Movie(TypedDict):
+ name: str
+ year: int
+
+ # This function expects two keyword arguments - `name` of type `str`
+ # and `year` of type `int`.
+ def foo(**kwargs: Unpack[Movie]): ...
+
+ See :pep:`692` for more details on using ``Unpack`` for ``**kwargs`` typing.
+
  .. versionadded:: 3.11
 
 .. class:: ParamSpec(name, *, bound=None, covariant=False, contravariant=False)

Doc/library/unittest.rst

@@ -2281,7 +2281,8 @@ Loading and running tests
 
  The *testRunner* argument can either be a test runner class or an already
  created instance of it. By default ``main`` calls :func:`sys.exit` with
- an exit code indicating success or failure of the tests run.
+ an exit code indicating success (0) or failure (1) of the tests run.
+ An exit code of 5 indicates that no tests were run.
 
  The *testLoader* argument has to be a :class:`TestLoader` instance,
  and defaults to :data:`defaultTestLoader`.

Doc/library/urllib.request.rst

@@ -28,8 +28,8 @@ The :mod:`urllib.request` module defines the following functions:
 
 .. function:: urlopen(url, data=None[, timeout], *, cafile=None, capath=None, cadefault=False, context=None)
 
- Open the URL *url*, which can be either a string or a
- :class:`Request` object.
+ Open *url*, which can be either a string containing a valid, properly
+ encoded URL, or a :class:`Request` object.
 
  *data* must be an object specifying additional data to be sent to the
  server, or ``None`` if no such data is needed. See :class:`Request`
@@ -192,7 +192,7 @@ The following classes are provided:
 
  This class is an abstraction of a URL request.
 
- *url* should be a string containing a valid URL.
+ *url* should be a string containing a valid, properly encoded URL.
 
  *data* must be an object specifying additional data to send to the
  server, or ``None`` if no such data is needed. Currently HTTP

Doc/requirements.txt

@@ -1,4 +1,7 @@
 # Requirements to build the Python documentation
+#
+# Note that when updating this file, you will likely also have to update
+# the Doc/constraints.txt file.
 
 # Sphinx version is pinned so that new versions that introduce new warnings
 # won't suddenly cause build failures. Updating the version is fine as long
@@ -13,3 +16,5 @@ sphinxext-opengraph==0.7.5
 # The theme used by the documentation is stored separately, so we need
 # to install that as well.
 python-docs-theme>=2022.1
+
+-c constraints.txt