Pull in main

Author: erlend-aasland

.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,81 @@
+{
+    "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.compilerPath": "/usr/bin/clang",
+                "C_Cpp.default.cStandard": "c11",
+                "C_Cpp.default.defines": [
+                    "CONFIG_64",
+                    "Py_BUILD_CORE"
+                ],
+                "C_Cpp.default.includePath": [
+                    "${workspaceFolder}/*",
+                    "${workspaceFolder}/Include/**"
+                ],
+                // 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

@@ -72,8 +72,7 @@ jobs:
     - 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
+        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
 

Doc/howto/enum.rst

@@ -284,6 +284,7 @@ The values are chosen by :func:`_generate_next_value_`, which can be
 overridden::
 
     >>> class AutoName(Enum):
+    ...     @staticmethod
     ...     def _generate_next_value_(name, start, count, last_values):
     ...         return name
     ...
@@ -372,6 +373,11 @@ below)::
     >>> Color.BLUE == 2
     False
 
+.. warning::
+
+   It is possible to reload modules -- if a reloaded module contains
+   enums, they will be recreated, and the new members may not
+   compare identical/equal to the original members.
 
 Allowed members and attributes of enumerations
 ----------------------------------------------

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

@@ -141,9 +141,8 @@ Module Contents
    :func:`global_enum`
 
       Modify the :class:`str() <str>` and :func:`repr` of an enum
-      to show its members as belonging to the module instead of its class.
-      Should only be used if the enum members will be exported to the
-      module global namespace.
+      to show its members as belonging to the module instead of its class,
+      and export the enum members to the global namespace.
 
    :func:`show_flag_values`
 
@@ -170,6 +169,27 @@ Data Types
    final *enum*, as well as creating the enum members, properly handling
    duplicates, providing iteration over the enum class, etc.
 
+   .. method:: EnumType.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
+
+      This method is called in two different ways:
+
+      * to look up an existing member:
+
+         :cls:   The enum class being called.
+         :value: The value to lookup.
+
+      * to use the ``cls`` enum to create a new enum (only if the existing enum
+        does not have any members):
+
+         :cls:   The enum class being called.
+         :value: The name of the new Enum to create.
+         :names: The names/values of the members for the new Enum.
+         :module:    The name of the module the new Enum is created in.
+         :qualname:  The actual location in the module where this Enum can be found.
+         :type:  A mix-in type for the new Enum.
+         :start: The first integer value for the Enum (used by :class:`auto`).
+         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only).
+
    .. method:: EnumType.__contains__(cls, member)
 
       Returns ``True`` if member belongs to the ``cls``::
@@ -255,26 +275,6 @@ Data Types
       names will also be removed from the completed enumeration.  See
       :ref:`TimePeriod <enum-time-period>` for an example.
 
-   .. method:: Enum.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
-
-      This method is called in two different ways:
-
-      * to look up an existing member:
-
-         :cls:   The enum class being called.
-         :value: The value to lookup.
-
-      * to use the ``cls`` enum to create a new enum:
-
-         :cls:   The enum class being called.
-         :value: The name of the new Enum to create.
-         :names: The names/values of the members for the new Enum.
-         :module:    The name of the module the new Enum is created in.
-         :qualname:  The actual location in the module where this Enum can be found.
-         :type:  A mix-in type for the new Enum.
-         :start: The first integer value for the Enum (used by :class:`auto`).
-         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only).
-
    .. method:: Enum.__dir__(self)
 
       Returns ``['__class__', '__doc__', '__module__', 'name', 'value']`` and
@@ -728,7 +728,6 @@ Data Types
    .. attribute:: EJECT
 
       Out-of-range values lose their *Flag* membership and revert to :class:`int`.
-      This is the default for :class:`IntFlag`::
 
          >>> from enum import Flag, EJECT, auto
          >>> class EjectFlag(Flag, boundary=EJECT):
@@ -741,8 +740,8 @@ Data Types
 
    .. attribute:: KEEP
 
-      Out-of-range values are kept, and the *Flag* membership is kept. This is
-      used for some stdlib flags::
+      Out-of-range values are kept, and the *Flag* membership is kept.
+      This is the default for :class:`IntFlag`::
 
          >>> from enum import Flag, KEEP, auto
          >>> class KeepFlag(Flag, boundary=KEEP):

Doc/library/gc.rst

@@ -251,7 +251,7 @@ values but should not rebind them):
       are printed.
 
    .. versionchanged:: 3.4
-      Following :pep:`442`, objects with a :meth:`__del__` method don't end
+      Following :pep:`442`, objects with a :meth:`~object.__del__` method don't end
       up in :attr:`gc.garbage` anymore.
 
 .. data:: callbacks

Doc/library/profile.rst

@@ -82,7 +82,7 @@ the following::
 
 The first line indicates that 214 calls were monitored.  Of those calls, 207
 were :dfn:`primitive`, meaning that the call was not induced via recursion. The
-next line: ``Ordered by: cumulative name``, indicates that the text string in the
+next line: ``Ordered by: cumulative time``, indicates that the text string in the
 far right column was used to sort the output. The column headings include:
 
 ncalls

Doc/library/string.rst

@@ -310,7 +310,7 @@ non-empty format specification typically modifies the result.
 The general form of a *standard format specifier* is:
 
 .. productionlist:: format-spec
-   format_spec: [[`fill`]`align`][`sign`][z][#][0][`width`][`grouping_option`][.`precision`][`type`]
+   format_spec: [[`fill`]`align`][`sign`]["z"]["#"]["0"][`width`][`grouping_option`]["." `precision`][`type`]
    fill: <any character>
    align: "<" | ">" | "=" | "^"
    sign: "+" | "-" | " "

Doc/library/test.rst

@@ -1691,6 +1691,21 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes
 .. versionadded:: 3.10
 
 
+.. function:: ignore_warnings(*, category)
+
+   Suppress warnings that are instances of *category*,
+   which must be :exc:`Warning` or a subclass.
+   Roughly equivalent to :func:`warnings.catch_warnings`
+   with :meth:`warnings.simplefilter('ignore', category=category) <warnings.simplefilter>`.
+   For example::
+
+      @warning_helper.ignore_warnings(category=DeprecationWarning)
+      def test_suppress_warning():
+          # do something
+
+   .. versionadded:: 3.8
+
+
 .. function:: check_no_resource_warning(testcase)
 
    Context manager to check that no :exc:`ResourceWarning` was raised.  You

Doc/library/typing.rst

@@ -41,10 +41,17 @@ For a summary of deprecated features and a deprecation timeline, please see
 
 .. seealso::
 
+   For a quick overview of type hints, refer to
+   `this cheat sheet <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_.
+
+   The "Type System Reference" section of https://mypy.readthedocs.io/ -- since
+   the Python typing system is standardised via PEPs, this reference should
+   broadly apply to most Python type checkers, although some parts may still be
+   specific to mypy.
+
    The documentation at https://typing.readthedocs.io/ serves as useful reference
    for type system features, useful typing related tools and typing best practices.
 
-
 .. _relevant-peps:
 
 Relevant PEPs
@@ -1591,6 +1598,15 @@ These are not used in annotations. They are building blocks for creating generic
       import threading
       assert isinstance(threading.Thread(name='Bob'), Named)
 
+   .. versionchanged:: 3.12
+      The internal implementation of :func:`isinstance` checks against
+      runtime-checkable protocols now uses :func:`inspect.getattr_static`
+      to look up attributes (previously, :func:`hasattr` was used).
+      As a result, some objects which used to be considered instances
+      of a runtime-checkable protocol may no longer be considered instances
+      of that protocol on Python 3.12+, and vice versa.
+      Most users are unlikely to be affected by this change.
+
    .. note::
 
         :func:`!runtime_checkable` will check only the presence of the required