Merge branch 'main' into pythongh-81079-glob-case-sensitive-arg-2

.github/workflows/doc.yml

@@ -53,6 +53,30 @@ jobs:
  - name: 'Build HTML documentation'
  run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
 
+ # Add pull request annotations for Sphinx nitpicks (missing references)
+ - name: 'Get list of changed files'
+ id: changed_files
+ uses: Ana06/get-changed-files@v2.2.0
+ with:
+ filter: "Doc/**"
+ - name: 'Build changed files in nit-picky mode'
+ continue-on-error: true
+ run: |
+ # Mark files the pull request modified
+ touch ${{ steps.changed_files.outputs.added_modified }}
+ # Build docs with the '-n' (nit-picky) option; convert warnings to annotations
+ make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n --keep-going" html 2>&1 |
+ python Doc/tools/warnings-to-gh-actions.py
+
+ # Ensure some files always pass Sphinx nit-picky mode (no missing references)
+ - name: 'Build known-good files in nit-picky mode'
+ run: |
+ # Mark files that must pass nit-picky
+ touch Doc/whatsnew/3.12.rst
+ touch Doc/library/sqlite3.rst
+ # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
+ make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
+
  # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
  doctest:
  name: 'Doctest'

Doc/c-api/exceptions.rst

@@ -86,7 +86,7 @@ Printing and clearing
 
  An exception must be set when calling this function.
 
-.. c:function: void PyErr_DisplayException(PyObject *exc)
+.. c:function:: void PyErr_DisplayException(PyObject *exc)
 
  Print the standard traceback display of ``exc`` to ``sys.stderr``, including
  chained exceptions and notes.

Doc/c-api/weakref.rst

@@ -67,3 +67,13 @@ as much as it can.
 .. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
 
  Similar to :c:func:`PyWeakref_GetObject`, but does no error checking.
+
+
+.. c:function:: void PyObject_ClearWeakRefs(PyObject *object)
+
+ This function is called by the :c:member:`~PyTypeObject.tp_dealloc` handler
+ to clear weak references.
+
+ This iterates through the weak references for *object* and calls callbacks
+ for those references which have one. It returns when all callbacks have
+ been attempted.

Doc/library/asyncio-task.rst

@@ -300,13 +300,17 @@ in the task at the next opportunity.
 It is recommended that coroutines use ``try/finally`` blocks to robustly
 perform clean-up logic. In case :exc:`asyncio.CancelledError`
 is explicitly caught, it should generally be propagated when
-clean-up is complete. Most code can safely ignore :exc:`asyncio.CancelledError`.
+clean-up is complete. :exc:`asyncio.CancelledError` directly subclasses
+:exc:`BaseException` so most code will not need to be aware of it.
 
 The asyncio components that enable structured concurrency, like
 :class:`asyncio.TaskGroup` and :func:`asyncio.timeout`,
 are implemented using cancellation internally and might misbehave if
 a coroutine swallows :exc:`asyncio.CancelledError`. Similarly, user code
-should not call :meth:`uncancel <asyncio.Task.uncancel>`.
+should not generally call :meth:`uncancel <asyncio.Task.uncancel>`.
+However, in cases when suppressing :exc:`asyncio.CancelledError` is
+truly desired, it is necessary to also call ``uncancel()`` to completely
+remove the cancellation state.
 
 .. _taskgroups:
 
@@ -620,32 +624,26 @@ Timeouts
  The context manager produced by :func:`asyncio.timeout` can be
  rescheduled to a different deadline and inspected.
 
- .. class:: Timeout()
+ .. class:: Timeout(when)
 
  An :ref:`asynchronous context manager <async-context-managers>`
- that limits time spent inside of it.
+ for cancelling overdue coroutines.
 
- .. versionadded:: 3.11
+ ``when`` should be an absolute time at which the context should time out,
+ as measured by the event loop's clock:
+
+ - If ``when`` is ``None``, the timeout will never trigger.
+ - If ``when < loop.time()``, the timeout will trigger on the next
+ iteration of the event loop.
 
  .. method:: when() -> float | None
 
  Return the current deadline, or ``None`` if the current
  deadline is not set.
 
- The deadline is a float, consistent with the time returned by
- :meth:`loop.time`.
-
  .. method:: reschedule(when: float | None)
 
- Change the time the timeout will trigger.
-
- If *when* is ``None``, any current deadline will be removed, and the
- context manager will wait indefinitely.
-
- If *when* is a float, it is set as the new deadline.
-
- if *when* is in the past, the timeout will trigger on the next
- iteration of the event loop.
+ Reschedule the timeout.
 
  .. method:: expired() -> bool
 
@@ -962,6 +960,13 @@ Introspection
  .. versionadded:: 3.7
 
 
+.. function:: iscoroutine(obj)
+
+ Return ``True`` if *obj* is a coroutine object.
+
+ .. versionadded:: 3.4
+
+
 Task Object
 ===========
 
@@ -1148,7 +1153,9 @@ Task Object
  Therefore, unlike :meth:`Future.cancel`, :meth:`Task.cancel` does
  not guarantee that the Task will be cancelled, although
  suppressing cancellation completely is not common and is actively
- discouraged.
+ discouraged. Should the coroutine nevertheless decide to suppress
+ the cancellation, it needs to call :meth:`Task.uncancel` in addition
+ to catching the exception.
 
  .. versionchanged:: 3.9
  Added the *msg* parameter.
@@ -1238,6 +1245,10 @@ Task Object
  with :meth:`uncancel`. :class:`TaskGroup` context managers use
  :func:`uncancel` in a similar fashion.
 
+ If end-user code is, for some reason, suppresing cancellation by
+ catching :exc:`CancelledError`, it needs to call this method to remove
+ the cancellation state.
+
  .. method:: cancelling()
 
  Return the number of pending cancellation requests to this Task, i.e.,

Doc/library/ctypes.rst

@@ -375,8 +375,8 @@ that they can be converted to the required C data type::
 
 .. _ctypes-calling-variadic-functions:
 
-Calling varadic functions
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Calling variadic functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 On a lot of platforms calling variadic functions through ctypes is exactly the same
 as calling functions with a fixed number of parameters. On some platforms, and in
@@ -508,7 +508,7 @@ a string pointer and a char, and returns a pointer to a string::
 
 If you want to avoid the ``ord("x")`` calls above, you can set the
 :attr:`argtypes` attribute, and the second argument will be converted from a
-single character Python bytes object into a C char::
+single character Python bytes object into a C char:
 
 .. doctest::
 

Doc/library/dis.rst

@@ -1042,15 +1042,6 @@ iterations of the loop.
  ``cmp_op[opname]``.
 
 
-.. opcode:: COMPARE_AND_BRANCH (opname)
-
- Compares the top two values on the stack, popping them, then branches.
- The direction and offset of the jump is embedded as a ``POP_JUMP_IF_TRUE``
- or ``POP_JUMP_IF_FALSE`` instruction immediately following the cache.
-
- .. versionadded:: 3.12
-
-
 .. opcode:: IS_OP (invert)
 
  Performs ``is`` comparison, or ``is not`` if ``invert`` is 1.
@@ -1152,30 +1143,6 @@ iterations of the loop.
  .. versionchanged:: 3.12
  This is no longer a pseudo-instruction.
 
-
-.. opcode:: JUMP_IF_TRUE_OR_POP (delta)
-
- If ``STACK[-1]`` is true, increments the bytecode counter by *delta* and leaves
- ``STACK[-1]`` on the stack. Otherwise (``STACK[-1]`` is false), ``STACK[-1]``
- is popped.
-
- .. versionadded:: 3.1
-
- .. versionchanged:: 3.11
- The oparg is now a relative delta rather than an absolute target.
-
-.. opcode:: JUMP_IF_FALSE_OR_POP (delta)
-
- If ``STACK[-1]`` is false, increments the bytecode counter by *delta* and leaves
- ``STACK[-1]`` on the stack. Otherwise (``STACK[-1]`` is true), ``STACK[-1]`` is
- popped.
-
- .. versionadded:: 3.1
-
- .. versionchanged:: 3.11
- The oparg is now a relative delta rather than an absolute target.
-
-
 .. opcode:: FOR_ITER (delta)
 
  ``STACK[-1]`` is an :term:`iterator`. Call its :meth:`~iterator.__next__` method.

Doc/library/exceptions.rst

@@ -948,8 +948,8 @@ their subgroups based on the types of the contained exceptions.
  these fields do not need to be updated by :meth:`derive`. ::
 
  >>> class MyGroup(ExceptionGroup):
- ... def derive(self, exc):
- ... return MyGroup(self.message, exc)
+ ... def derive(self, excs):
+ ... return MyGroup(self.message, excs)
  ...
  >>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
  >>> e.add_note("a note")

Doc/library/gzip.rst

@@ -143,6 +143,12 @@ The module defines the following items:
  :func:`time.time` and the :attr:`~os.stat_result.st_mtime` attribute of
  the object returned by :func:`os.stat`.
 
+ .. attribute:: name
+
+ The path to the gzip file on disk, as a :class:`str` or :class:`bytes`.
+ Equivalent to the output of :func:`os.fspath` on the original input path,
+ with no other normalization, resolution or expansion.
+
  .. versionchanged:: 3.1
  Support for the :keyword:`with` statement was added, along with the
  *mtime* constructor argument and :attr:`mtime` attribute.

Doc/library/inspect.rst

@@ -574,6 +574,8 @@ Retrieving source code
  object and the line number indicates where in the original source file the first
  line of code was found. An :exc:`OSError` is raised if the source code cannot
  be retrieved.
+ A :exc:`TypeError` is raised if the object is a built-in module, class, or
+ function.
 
  .. versionchanged:: 3.3
  :exc:`OSError` is raised instead of :exc:`IOError`, now an alias of the
@@ -586,6 +588,8 @@ Retrieving source code
  class, method, function, traceback, frame, or code object. The source code is
  returned as a single string. An :exc:`OSError` is raised if the source code
  cannot be retrieved.
+ A :exc:`TypeError` is raised if the object is a built-in module, class, or
+ function.
 
  .. versionchanged:: 3.3
  :exc:`OSError` is raised instead of :exc:`IOError`, now an alias of the

Doc/library/itertools.rst

@@ -936,7 +936,7 @@ which incur interpreter overhead.
  n = quotient
  if n == 1:
  return
- if n >= 2:
+ if n > 1:
  yield n
 
  def flatten(list_of_lists):

Doc/library/logging.rst

@@ -813,8 +813,9 @@ wire).
  :type lineno: int
 
  :param msg: The event description message,
- which can be a %-format string with placeholders for variable data.
- :type msg: str
+ which can be a %-format string with placeholders for variable data,
+ or an arbitrary object (see :ref:`arbitrary-object-messages`).
+ :type msg: typing.Any
 
  :param args: Variable data to merge into the *msg* argument
  to obtain the event description.