Merge branch 'main' into decimal-logop-docs

Author: skirpichev

.devcontainer/Dockerfile

@@ -0,0 +1,24 @@
+FROM docker.io/library/fedora:37
+
+ENV CC=clang
+
+ENV WASI_SDK_VERSION=19
+ENV WASI_SDK_PATH=/opt/wasi-sdk
+
+ENV WASMTIME_HOME=/opt/wasmtime
+ENV WASMTIME_VERSION=7.0.0
+ENV WASMTIME_CPU_ARCH=x86_64
+
+RUN dnf -y --nodocs install git clang xz python3-blurb dnf-plugins-core && \
+    dnf -y --nodocs builddep python3 && \
+    dnf -y clean all
+
+RUN mkdir ${WASI_SDK_PATH} && \
+    curl --location https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_SDK_VERSION}/wasi-sdk-${WASI_SDK_VERSION}.0-linux.tar.gz | \
+    tar --strip-components 1 --directory ${WASI_SDK_PATH} --extract --gunzip
+
+RUN mkdir --parents ${WASMTIME_HOME} && \
+    curl --location "https://github.com/bytecodealliance/wasmtime/releases/download/v${WASMTIME_VERSION}/wasmtime-v${WASMTIME_VERSION}-${WASMTIME_CPU_ARCH}-linux.tar.xz" | \
+    xz --decompress | \
+    tar --strip-components 1 --directory ${WASMTIME_HOME} -x && \
+    ln -s ${WASMTIME_HOME}/wasmtime /usr/local/bin

.devcontainer/devcontainer.json

@@ -0,0 +1,75 @@
+{
+    "build": {
+        "dockerfile": "Dockerfile"
+    },
+    "onCreateCommand": [
+        // Install common tooling.
+        "dnf",
+        "install",
+        "-y",
+        "which",
+        "zsh",
+        "fish"
+    ],
+    "updateContentCommand": {
+        // Using the shell for `nproc` usage.
+        "python": "./configure --config-cache --with-pydebug && make -s -j `nproc`",
+        "docs": [
+            "make",
+            "--directory",
+            "Doc",
+            "venv",
+            "html"
+        ]
+    },
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                // Highlighting for Parser/Python.asdl.
+                "brettcannon.zephyr-asdl",
+                // Highlighting for configure.ac.
+                "maelvalais.autoconf",
+                // C auto-complete.
+                "ms-vscode.cpptools",
+                // To view built docs.
+                "ms-vscode.live-server"
+                // https://github.com/microsoft/vscode-python/issues/18073
+                // "ms-python.python"
+            ],
+            "settings": {
+                "C_Cpp.default.cStandard": "c11",
+                "C_Cpp.default.defines": [
+                    "Py_BUILD_CORE"
+                ],
+                // https://github.com/microsoft/vscode-cpptools/issues/10732
+                "C_Cpp.errorSquiggles": "disabled",
+                "editor.insertSpaces": true,
+                "editor.rulers": [
+                    80
+                ],
+                "editor.tabSize": 4,
+                "editor.trimAutoWhitespace": true,
+                "files.associations": {
+                    "*.h": "c"
+                },
+                "files.encoding": "utf8",
+                "files.eol": "\n",
+                "files.insertFinalNewline": true,
+                "files.trimTrailingWhitespace": true,
+                "python.analysis.diagnosticSeverityOverrides": {
+                    // Complains about shadowing the stdlib w/ the stdlib.
+                    "reportShadowedImports": "none",
+                    // Doesn't like _frozen_importlib.
+                    "reportMissingImports": "none"
+                },
+                "python.analysis.extraPaths": [
+                    "Lib"
+                ],
+                "python.defaultInterpreterPath": "./python",
+                "[restructuredtext]": {
+                    "editor.tabSize": 3
+                }
+            }
+        }
+    }
+}

.github/workflows/doc.yml

@@ -53,6 +53,29 @@ 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/[email protected]
+      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
+        python Doc/tools/touch-clean-files.py
+        # 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/object.rst

@@ -179,6 +179,15 @@ Object Protocol
    If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
    will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
 
+.. c:function:: PyObject* PyObject_Format(PyObject *obj, PyObject *format_spec)
+
+   Format *obj* using *format_spec*. This is equivalent to the Python
+   expression ``format(obj, format_spec)``.
+
+   *format_spec* may be ``NULL``. In this case the call is equivalent
+   to ``format(obj)``.
+   Returns the formatted string on success, ``NULL`` on failure.
+
 .. c:function:: PyObject* PyObject_Repr(PyObject *o)
 
    .. index:: builtin: repr

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/howto/logging-cookbook.rst

@@ -340,23 +340,27 @@ adding a ``filters`` section parallel to ``formatters`` and ``handlers``:
 
 .. code-block:: json
 
-    "filters": {
-        "warnings_and_below": {
-            "()" : "__main__.filter_maker",
-            "level": "WARNING"
+    {
+        "filters": {
+            "warnings_and_below": {
+                "()" : "__main__.filter_maker",
+                "level": "WARNING"
+            }
         }
     }
 
 and changing the section on the ``stdout`` handler to add it:
 
 .. code-block:: json
 
-    "stdout": {
-        "class": "logging.StreamHandler",
-        "level": "INFO",
-        "formatter": "simple",
-        "stream": "ext://sys.stdout",
-        "filters": ["warnings_and_below"]
+    {
+        "stdout": {
+            "class": "logging.StreamHandler",
+            "level": "INFO",
+            "formatter": "simple",
+            "stream": "ext://sys.stdout",
+            "filters": ["warnings_and_below"]
+        }
     }
 
 A filter is just a function, so we can define the ``filter_maker`` (a factory

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/codeop.rst

@@ -19,10 +19,10 @@ module instead.
 
 There are two parts to this job:
 
-#. Being able to tell if a line of input completes a Python  statement: in
+#. Being able to tell if a line of input completes a Python statement: in
    short, telling whether to print '``>>>``' or '``...``' next.
 
-#. Remembering which future statements the user has entered, so  subsequent
+#. Remembering which future statements the user has entered, so subsequent
    input can be compiled with these in effect.
 
 The :mod:`codeop` module provides a way of doing each of these things, and a way
@@ -33,19 +33,19 @@ To do just the former:
 .. function:: compile_command(source, filename="<input>", symbol="single")
 
    Tries to compile *source*, which should be a string of Python code and return a
-   code object if *source* is valid Python code. In that case, the filename
+   code object if *source* is valid Python code.  In that case, the filename
    attribute of the code object will be *filename*, which defaults to
-   ``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a
+   ``'<input>'``.  Returns ``None`` if *source* is *not* valid Python code, but is a
    prefix of valid Python code.
 
    If there is a problem with *source*, an exception will be raised.
    :exc:`SyntaxError` is raised if there is invalid Python syntax, and
    :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
 
    The *symbol* argument determines whether *source* is compiled as a statement
-   (``'single'``, the default), as a sequence of statements (``'exec'``) or
+   (``'single'``, the default), as a sequence of :term:`statement` (``'exec'``) or
    as an :term:`expression` (``'eval'``).  Any other value will
-   cause :exc:`ValueError` to  be raised.
+   cause :exc:`ValueError` to be raised.
 
    .. note::
 
@@ -69,5 +69,5 @@ To do just the former:
 
    Instances of this class have :meth:`__call__` methods identical in signature to
    :func:`compile_command`; the difference is that if the instance compiles program
-   text containing a ``__future__`` statement, the instance 'remembers' and
+   text containing a :mod:`__future__` statement, the instance 'remembers' and
    compiles all subsequent program texts with the statement in force.

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::