Merge remote-tracking branch 'origin/main' into fix-tg

Doc/c-api/unicode.rst

@@ -523,7 +523,7 @@ APIs:
  - Get the fully qualified name of an object type;
  call :c:func:`PyType_GetFullyQualifiedName`.
 
- * - ``T#``
+ * - ``#T``
  - :c:expr:`PyObject*`
  - Similar to ``T`` format, but use a colon (``:``) as separator between
  the module name and the qualified name.
@@ -533,7 +533,7 @@ APIs:
  - Get the fully qualified name of a type;
  call :c:func:`PyType_GetFullyQualifiedName`.
 
- * - ``N#``
+ * - ``#N``
  - :c:expr:`PyTypeObject*`
  - Similar to ``N`` format, but use a colon (``:``) as separator between
  the module name and the qualified name.
@@ -574,7 +574,7 @@ APIs:
  copied as-is to the result string, and any extra arguments discarded.
 
  .. versionchanged:: 3.13
- Support for ``%T``, ``%T#``, ``%N`` and ``%N#`` formats added.
+ Support for ``%T``, ``%#T``, ``%N`` and ``%#N`` formats added.
 
 
 .. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)

Doc/library/asyncio-queue.rst

@@ -62,6 +62,9 @@ Queue
  Remove and return an item from the queue. If queue is empty,
  wait until an item is available.
 
+ Raises :exc:`QueueShutDown` if the queue has been shut down and
+ is empty, or if the queue has been shut down immediately.
+
  .. method:: get_nowait()
 
  Return an item if one is immediately available, else raise
@@ -82,6 +85,8 @@ Queue
  Put an item into the queue. If the queue is full, wait until a
  free slot is available before adding the item.
 
+ Raises :exc:`QueueShutDown` if the queue has been shut down.
+
  .. method:: put_nowait(item)
 
  Put an item into the queue without blocking.
@@ -92,6 +97,22 @@ Queue
 
  Return the number of items in the queue.
 
+ .. method:: shutdown(immediate=False)
+
+ Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put`
+ raise :exc:`QueueShutDown`.
+
+ By default, :meth:`~Queue.get` on a shut down queue will only
+ raise once the queue is empty. Set *immediate* to true to make
+ :meth:`~Queue.get` raise immediately instead.
+
+ All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get`
+ will be unblocked. If *immediate* is true, a task will be marked
+ as done for each remaining item in the queue, which may unblock
+ callers of :meth:`~Queue.join`.
+
+ .. versionadded:: 3.13
+
  .. method:: task_done()
 
  Indicate that a formerly enqueued task is complete.
@@ -105,6 +126,9 @@ Queue
  call was received for every item that had been :meth:`~Queue.put`
  into the queue).
 
+ ``shutdown(immediate=True)`` calls :meth:`task_done` for each
+ remaining item in the queue.
+
  Raises :exc:`ValueError` if called more times than there were
  items placed in the queue.
 
@@ -145,6 +169,14 @@ Exceptions
  on a queue that has reached its *maxsize*.
 
 
+.. exception:: QueueShutDown
+
+ Exception raised when :meth:`~Queue.put` or :meth:`~Queue.get` is
+ called on a queue which has been shut down.
+
+ .. versionadded:: 3.13
+
+
 Examples
 ========
 

Doc/library/asyncio-stream.rst

@@ -260,8 +260,19 @@ StreamReader
  buffer is reset. The :attr:`IncompleteReadError.partial` attribute
  may contain a portion of the separator.
 
+ The *separator* may also be an :term:`iterable` of separators. In this
+ case the return value will be the shortest possible that has any
+ separator as the suffix. For the purposes of :exc:`LimitOverrunError`,
+ the shortest possible separator is considered to be the one that
+ matched.
+
  .. versionadded:: 3.5.2
 
+ .. versionchanged:: 3.13
+
+ The *separator* parameter may now be an :term:`iterable` of
+ separators.
+
  .. method:: at_eof()
 
  Return ``True`` if the buffer is empty and :meth:`feed_eof`

Doc/library/code.rst

@@ -41,7 +41,7 @@ build applications which provide an interactive interpreter prompt.
  the :meth:`InteractiveConsole.raw_input` method, if provided. If *local* is
  provided, it is passed to the :class:`InteractiveConsole` constructor for
  use as the default namespace for the interpreter loop. If *local_exit* is provided,
- it is passed to the :class:`InteractiveConsole` constructor. The :meth:`interact`
+ it is passed to the :class:`InteractiveConsole` constructor. The :meth:`~InteractiveConsole.interact`
  method of the instance is then run with *banner* and *exitmsg* passed as the
  banner and exit message to use, if provided. The console object is discarded
  after use.

Doc/library/sqlite3.rst

@@ -16,6 +16,8 @@
  src = sqlite3.connect(":memory:", isolation_level=None)
  dst = sqlite3.connect("tutorial.db", isolation_level=None)
  src.backup(dst)
+ src.close()
+ dst.close()
  del src, dst
 
 .. _sqlite3-intro:
@@ -220,6 +222,7 @@ creating a new cursor, then querying the database:
  >>> title, year = res.fetchone()
  >>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
  The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
+ >>> new_con.close()
 
 You've now created an SQLite database using the :mod:`!sqlite3` module,
 inserted data and retrieved values from it in multiple ways.
@@ -394,29 +397,11 @@ Module functions
  will get tracebacks from callbacks on :data:`sys.stderr`. Use ``False``
  to disable the feature again.
 
- Register an :func:`unraisable hook handler <sys.unraisablehook>` for an
- improved debug experience:
-
- .. testsetup:: sqlite3.trace
-
- import sqlite3
+ .. note::
 
- .. doctest:: sqlite3.trace
-
- >>> sqlite3.enable_callback_tracebacks(True)
- >>> con = sqlite3.connect(":memory:")
- >>> def evil_trace(stmt):
- ... 5/0
- ...
- >>> con.set_trace_callback(evil_trace)
- >>> def debug(unraisable):
- ... print(f"{unraisable.exc_value!r} in callback {unraisable.object.__name__}")
- ... print(f"Error message: {unraisable.err_msg}")
- >>> import sys
- >>> sys.unraisablehook = debug
- >>> cur = con.execute("SELECT 1")
- ZeroDivisionError('division by zero') in callback evil_trace
- Error message: None
+ Errors in user-defined function callbacks are logged as unraisable exceptions.
+ Use an :func:`unraisable hook handler <sys.unraisablehook>` for
+ introspection of the failed callback.
 
 .. function:: register_adapter(type, adapter, /)
 
@@ -762,6 +747,7 @@ Connection objects
  >>> for row in con.execute("SELECT md5(?)", (b"foo",)):
  ... print(row)
  ('acbd18db4cc2f85cedef654fccc4a4d8',)
+ >>> con.close()
 
  .. versionchanged:: 3.13
 
@@ -908,6 +894,7 @@ Connection objects
  FROM test ORDER BY x
  """)
  print(cur.fetchall())
+ con.close()
 
  .. testoutput::
  :hide:
@@ -1068,13 +1055,10 @@ Connection objects
  .. versionchanged:: 3.10
  Added the ``sqlite3.enable_load_extension`` auditing event.
 
- .. testsetup:: sqlite3.loadext
-
- import sqlite3
- con = sqlite3.connect(":memory:")
+ .. We cannot doctest the load extension API, since there is no convenient
+ way to skip it.
 
- .. testcode:: sqlite3.loadext
- :skipif: True # not testable at the moment
+ .. code-block::
 
  con.enable_load_extension(True)
 
@@ -1098,14 +1082,6 @@ Connection objects
  for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
  print(row)
 
- con.close()
-
- .. testoutput:: sqlite3.loadext
- :hide:
-
- (2, 'broccoli pie', 'broccoli cheese onions flour')
- (3, 'pumpkin pie', 'pumpkin sugar flour butter')
-
  .. method:: load_extension(path, /, *, entrypoint=None)
 
  Load an SQLite extension from a shared library.
@@ -1230,6 +1206,8 @@ Connection objects
  src = sqlite3.connect('example.db')
  dst = sqlite3.connect(':memory:')
  src.backup(dst)
+ dst.close()
+ src.close()
 
  .. versionadded:: 3.7
 
@@ -1296,6 +1274,10 @@ Connection objects
  >>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
  1
 
+ .. testcleanup:: sqlite3.limits
+
+ con.close()
+
  .. versionadded:: 3.11
 
  .. _SQLite limit category: https://www.sqlite.org/c3ref/c_limit_attached.html
@@ -1577,6 +1559,10 @@ Cursor objects
  # cur is an sqlite3.Cursor object
  cur.executemany("INSERT INTO data VALUES(?)", rows)
 
+ .. testcleanup:: sqlite3.cursor
+
+ con.close()
+
  .. note::
 
  Any resulting rows are discarded,
@@ -1682,6 +1668,7 @@ Cursor objects
  >>> cur = con.cursor()
  >>> cur.connection == con
  True
+ >>> con.close()
 
  .. attribute:: description
 
@@ -1802,6 +1789,7 @@ Blob objects
  greeting = blob.read()
 
  print(greeting) # outputs "b'Hello, world!'"
+ con.close()
 
  .. testoutput::
  :hide:
@@ -2114,6 +2102,7 @@ Here's an example of both styles:
  params = (1972,)
  cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
  print(cur.fetchall())
+ con.close()
 
 .. testoutput::
  :hide:
@@ -2172,6 +2161,7 @@ The object passed to *protocol* will be of type :class:`PrepareProtocol`.
 
  cur.execute("SELECT ?", (Point(4.0, -3.2),))
  print(cur.fetchone()[0])
+ con.close()
 
 .. testoutput::
  :hide:
@@ -2202,6 +2192,7 @@ This function can then be registered using :func:`register_adapter`.
 
  cur.execute("SELECT ?", (Point(1.0, 2.5),))
  print(cur.fetchone()[0])
+ con.close()
 
 .. testoutput::
  :hide:
@@ -2286,6 +2277,8 @@ The following example illustrates the implicit and explicit approaches:
  cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
  cur.execute('SELECT p AS "p [point]" FROM test')
  print("with column names:", cur.fetchone()[0])
+ cur.close()
+ con.close()
 
 .. testoutput::
  :hide:
@@ -2492,6 +2485,8 @@ Some useful URI tricks include:
  res = con2.execute("SELECT data FROM shared")
  assert res.fetchone() == (28,)
 
+ con1.close()
+ con2.close()
 
 More information about this feature, including a list of parameters,
 can be found in the `SQLite URI documentation`_.
@@ -2538,6 +2533,7 @@ Queries now return :class:`!Row` objects:
  'Earth'
  >>> row["RADIUS"] # Column names are case-insensitive.
  6378
+ >>> con.close()
 
 .. note::
 
@@ -2564,6 +2560,7 @@ Using it, queries now return a :class:`!dict` instead of a :class:`!tuple`:
  >>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
  ... print(row)
  {'a': 1, 'b': 2}
+ >>> con.close()
 
 The following row factory returns a :term:`named tuple`:
 
@@ -2590,6 +2587,7 @@ The following row factory returns a :term:`named tuple`:
  1
  >>> row.b # Attribute access.
  2
+ >>> con.close()
 
 With some adjustments, the above recipe can be adapted to use a
 :class:`~dataclasses.dataclass`, or any other custom class,
@@ -2747,3 +2745,11 @@ regardless of the value of :attr:`~Connection.isolation_level`.
 
 .. _SQLite transaction behaviour:
  https://www.sqlite.org/lang_transaction.html#deferred_immediate_and_exclusive_transactions
+
+.. testcleanup::
+
+ import os
+ os.remove("backup.db")
+ os.remove("dump.sql")
+ os.remove("example.db")
+ os.remove("tutorial.db")

Doc/whatsnew/3.13.rst

@@ -316,6 +316,10 @@ asyncio
 
  (Inspired by an issue reported by Arthur Tacca in :gh:`116720`.)
 
+* Add :meth:`asyncio.Queue.shutdown` (along with
+ :exc:`asyncio.QueueShutDown`) for queue termination.
+ (Contributed by Laurie Opperman and Yves Duprat in :gh:`104228`.)
+
 base64
 ------
 
@@ -1791,7 +1795,7 @@ New Features
  Equivalent to getting the ``type.__module__`` attribute.
  (Contributed by Eric Snow and Victor Stinner in :gh:`111696`.)
 
-* Add support for ``%T``, ``%T#``, ``%N`` and ``%N#`` formats to
+* Add support for ``%T``, ``%#T``, ``%N`` and ``%#N`` formats to
  :c:func:`PyUnicode_FromFormat`: format the fully qualified name of an object
  type and of a type: call :c:func:`PyType_GetModuleName`. See :pep:`737` for
  more information.
@@ -2022,11 +2026,6 @@ Removed
 
  (Contributed by Victor Stinner in :gh:`105182`.)
 
-* Remove private ``_PyObject_FastCall()`` function:
- use ``PyObject_Vectorcall()`` which is available since Python 3.8
- (:pep:`590`).
- (Contributed by Victor Stinner in :gh:`106023`.)
-
 * Remove ``cpython/pytime.h`` header file: it only contained private functions.
  (Contributed by Victor Stinner in :gh:`106316`.)
 

Include/cpython/weakrefobject.h

@@ -30,6 +30,14 @@ struct _PyWeakReference {
  PyWeakReference *wr_prev;
  PyWeakReference *wr_next;
  vectorcallfunc vectorcall;
+
+#ifdef Py_GIL_DISABLED
+ /* Pointer to the lock used when clearing in free-threaded builds.
+ * Normally this can be derived from wr_object, but in some cases we need
+ * to lock after wr_object has been set to Py_None.
+ */
+ struct _PyMutex *weakrefs_lock;
+#endif
 };
 
 Py_DEPRECATED(3.13) static inline PyObject* PyWeakref_GET_OBJECT(PyObject *ref_obj)