Merge remote-tracking branch 'upstream/main' into gh-116146-initfunc-docs-tests

Author: itamaro

.github/workflows/build.yml

@@ -491,53 +491,6 @@ jobs:
     if: fromJSON(needs.build-context.outputs.run-tests)
     uses: ./.github/workflows/reusable-test-lazy-imports-all.yml
 
-  build-asan:
-    name: 'Address sanitizer'
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 60
-    needs: build-context
-    if: needs.build-context.outputs.run-ubuntu == 'true'
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-26.04]
-    env:
-      OPENSSL_VER: 3.5.9
-      PYTHONSTRICTEXTENSIONBUILD: 1
-      ASAN_OPTIONS: detect_leaks=0:allocator_may_return_null=1:handle_segv=0
-    steps:
-    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      with:
-        persist-credentials: false
-    - name: Runner image version
-      run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
-    - name: Register gcc problem matcher
-      run: echo "::add-matcher::.github/problem-matchers/gcc.json"
-    - name: Install dependencies
-      run: sudo ./.github/workflows/posix-deps-apt.sh
-    - name: Configure OpenSSL env vars
-      run: |
-        echo "MULTISSL_DIR=${GITHUB_WORKSPACE}/multissl" >> "$GITHUB_ENV"
-        echo "OPENSSL_DIR=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}" >> "$GITHUB_ENV"
-        echo "LD_LIBRARY_PATH=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}/lib" >> "$GITHUB_ENV"
-    - name: 'Restore OpenSSL build'
-      id: cache-openssl
-      uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-      with:
-        path: ./multissl/openssl/${{ env.OPENSSL_VER }}
-        key: ${{ matrix.os }}-multissl-openssl-${{ env.OPENSSL_VER }}
-    - name: Install OpenSSL
-      if: steps.cache-openssl.outputs.cache-hit != 'true'
-      run: python3 Tools/ssl/multissltests.py --steps=library --base-directory "$MULTISSL_DIR" --openssl "$OPENSSL_VER" --system Linux
-    - name: Configure CPython
-      run: ./configure --config-cache --with-address-sanitizer --without-pymalloc --with-openssl="$OPENSSL_DIR"
-    - name: Build CPython
-      run: make -j4
-    - name: Display build info
-      run: make pythoninfo
-    - name: Tests
-      run: xvfb-run make ci
-
   build-san:
     # ${{ '' } is a hack to nest jobs under the same sidebar category.
     name: Sanitizers${{ '' }}  # zizmor: ignore[obfuscation]
@@ -554,6 +507,9 @@ jobs:
         sanitizer:
         - TSan
         include:
+        - check-name: Address
+          sanitizer: ASan
+          free-threading: false
         - check-name: Undefined behavior
           sanitizer: UBSan
           free-threading: false
@@ -667,7 +623,6 @@ jobs:
     - build-wasi
     - test-hypothesis
     - test-lazy-imports-all
-    - build-asan
     - build-san
     - cross-build-linux
     - cifuzz
@@ -714,7 +669,6 @@ jobs:
             build-ubuntu-installed,
             build-ubuntu-ssltests,
             test-hypothesis,
-            build-asan,
             build-san,
             cross-build-linux,
             '

.github/workflows/reusable-san.yml

@@ -43,6 +43,15 @@ jobs:
         # please update the versions in `Tools/pixi-packages/variants.yaml` too.
         echo "CC=clang" >> "$GITHUB_ENV"
         echo "CXX=clang++" >> "$GITHUB_ENV"
+    - name: ASan option setup
+      if: inputs.sanitizer == 'ASan'
+      run: |
+        echo "MULTISSL_DIR=${GITHUB_WORKSPACE}/multissl" >> "$GITHUB_ENV"
+        echo "OPENSSL_DIR=${GITHUB_WORKSPACE}/multissl/openssl/${OPENSSL_VER}" >> "$GITHUB_ENV"
+        echo "ASAN_OPTIONS=${SAN_LOG_OPTION} detect_leaks=0 allocator_may_return_null=1 handle_segv=0" >> "$GITHUB_ENV"
+        echo "PYTHONSTRICTEXTENSIONBUILD=1" >> "$GITHUB_ENV"
+      env:
+        SAN_LOG_OPTION: log_path=${{ github.workspace }}/san_log
     - name: TSan option setup
       if: inputs.sanitizer == 'TSan'
       run: |
@@ -88,24 +97,27 @@ jobs:
     - name: Add ccache to PATH
       run: |
         echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
-    - name: 'Restore OpenSSL build (TSan)'
+    - name: 'Restore OpenSSL build'
       id: cache-openssl
-      if: inputs.sanitizer == 'TSan'
+      if: inputs.sanitizer == 'TSan' || inputs.sanitizer == 'ASan'
       uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
       with:
         path: ./multissl/openssl/${{ env.OPENSSL_VER }}
-        key: ${{ env.IMAGE_OS_VERSION }}-multissl-openssl-tsan-${{ env.OPENSSL_VER }}
-    - name: Install OpenSSL (TSan)
+        key: >-
+          ${{ env.IMAGE_OS_VERSION }}-multissl-openssl-${{
+            inputs.sanitizer == 'TSan' && 'tsan-' || ''
+          }}${{ env.OPENSSL_VER }}
+    - name: Install OpenSSL
       if: >-
-        inputs.sanitizer == 'TSan'
+        (inputs.sanitizer == 'TSan' || inputs.sanitizer == 'ASan')
         && steps.cache-openssl.outputs.cache-hit != 'true'
       run: >-
         python3 Tools/ssl/multissltests.py
         --steps=library
         --base-directory="${MULTISSL_DIR}"
         --openssl="${OPENSSL_VER}"
         --system=Linux
-        --tsan
+        ${{ inputs.sanitizer == 'TSan' && '--tsan' || '' }}
     # gh-157958: -O2 instead of the pydebug default -Og to avoid a clang 21
     # compile-time blowup on some interpreter files.
     # (https://github.com/llvm/llvm-project/issues/179695)
@@ -117,14 +129,20 @@ jobs:
         --config-cache
         OPT="-O2 -g"
         ${{
-          inputs.sanitizer == 'TSan'
+          inputs.sanitizer == 'ASan'
+          && '--with-address-sanitizer --without-pymalloc'
+          || inputs.sanitizer == 'TSan'
           && '--with-thread-sanitizer'
           || inputs.sanitizer == 'MSan'
           && '--with-memory-sanitizer'
           || '--with-undefined-behavior-sanitizer --with-strict-overflow'
         }}
         ${{ inputs.sanitizer == 'MSan' && '--with-assertions' || '--with-pydebug' }}
-        ${{ inputs.sanitizer == 'TSan' && '--with-openssl="$OPENSSL_DIR" --with-openssl-rpath=auto' || '' }}
+        ${{
+          (inputs.sanitizer == 'TSan' || inputs.sanitizer == 'ASan')
+          && '--with-openssl="$OPENSSL_DIR" --with-openssl-rpath=auto'
+          || ''
+        }}
         ${{ inputs.free-threading && '--disable-gil' || '' }}
     - name: Build CPython
       run: make -j4

Doc/c-api/function.rst

@@ -14,6 +14,10 @@ There are a few functions specific to Python functions.
 
    The C structure used for functions.
 
+   In the free-threaded build, direct access to mutable fields requires
+   synchronization if another thread may modify the function. See
+   :ref:`freethreading-extensions-howto`.
+
 
 .. c:var:: PyTypeObject PyFunction_Type
 
@@ -71,6 +75,11 @@ There are a few functions specific to Python functions.
    This is normally a :class:`string <str>` containing the module name,
    but can be set to any other object by Python code.
 
+   In the free-threaded build, if the attribute may be modified concurrently,
+   convert the borrowed reference to a strong reference with :c:func:`Py_XNewRef`
+   immediately, before calling any other Python API. The same applies to
+   :c:func:`PyFunction_GET_MODULE`.
+
 
 .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
 

Doc/c-api/init_config.rst

@@ -1439,6 +1439,10 @@ PyConfig
 
       See also the :c:member:`~PyConfig.filesystem_errors` member.
 
+      See also :c:func:`PyUnicode_EncodeFSDefault` and
+      :ref:`related functions <capi-filesystem-encoding>`
+      for encoding paths at runtime.
+
    .. c:member:: wchar_t* filesystem_errors
 
       :term:`Filesystem error handler <filesystem encoding and error handler>`:

Doc/c-api/interp-lifecycle.rst

@@ -514,7 +514,7 @@ Process-wide parameters
    Return the version of this Python interpreter.  This is a string that looks
    something like ::
 
-      "3.15.0rc2 (3.15.0~rc2-1.fc44.x86_64, Sep  3 2026, 00:00:00) [GCC 16.2.1 20260819 (Red Hat 16.2.1-2)]"
+      "3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) \n[GCC 4.2.3]"
 
    .. index:: single: version (in module sys)
 

Doc/c-api/reflection.rst

@@ -96,6 +96,12 @@ Reflection
    Return the name of *func* if it is a function, class or instance object, else the
    name of *func*\s type.
 
+   For a Python function or method, the returned pointer refers to the
+   function's name and must not be retained across operations that may change
+   that name. In the free-threaded build, copy the string before detaching
+   the thread state or executing Python code if the name may be modified
+   concurrently.
+
 
 .. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)
 

Doc/c-api/unicode.rst

@@ -812,6 +812,8 @@ system.
       used for ``strict``.
 
 
+.. _capi-filesystem-encoding:
+
 File System Encoding
 """"""""""""""""""""
 

Doc/howto/remote_debugging.rst

@@ -16,7 +16,7 @@ To disable remote debugging support, use any of the following:
 
 * Set the :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` environment variable to ``1`` before
   starting the interpreter.
-* Use the :option:`-X disable_remote_debug` command-line option.
+* Use the :option:`-X disable-remote-debug` command-line option.
 * Compile Python with the :option:`--without-remote-debug` build flag.
 
 .. _permission-requirements:
@@ -717,7 +717,7 @@ When to use ``PYTHON_DISABLE_REMOTE_DEBUG``
 -------------------------------------------
 
 The environment variable :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` (and the
-equivalent :option:`-X disable_remote_debug` flag) allows operators to disable
+equivalent :option:`-X disable-remote-debug` flag) allows operators to disable
 the in-process side of the protocol as a **defence-in-depth** measure.  This
 may be useful in hardened or sandboxed deployment environments where no
 debugging or profiling of the process is expected and reducing attack surface

Doc/library/calendar.rst

@@ -169,10 +169,10 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       the specified width, representing an empty day. The *weekday* parameter
       is unused.
 
-   .. method:: formatweek(theweek, w=0)
+   .. method:: formatweek(theweek, width)
 
-      Return a single week in a string with no newline. If *w* is provided, it
-      specifies the width of the date columns, which are centered. Depends
+      Return a single week in a string with no newline. *width* specifies
+      the width of the date columns, which are centered. Depends
       on the first weekday as specified in the constructor or set by the
       :meth:`setfirstweekday` method.
 
@@ -200,7 +200,7 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       :meth:`setfirstweekday` method.
 
 
-   .. method:: formatmonthname(theyear, themonth, width=0, withyear=True)
+   .. method:: formatmonthname(theyear, themonth, width, withyear=True)
 
       Return a string representing the month's name centered within the
       specified *width*. If *withyear* is ``True``, include the year in the

Doc/library/dbm.rst

@@ -100,7 +100,8 @@ The :meth:`!setdefault` method requires two arguments.
 
 Key and values are always stored as :class:`bytes`. This means that when
 strings are used they are implicitly converted to the default encoding before
-being stored.
+being stored. For detailed information about accepted types, see
+:ref:`dbm-key-value-types`.
 
 These objects also support being used in a :keyword:`with` statement, which
 will automatically close them when done.
@@ -121,6 +122,47 @@ will automatically close them when done.
    :meth:`!clear` methods are now available for all :mod:`!dbm` backends.
 
 
+.. _dbm-key-value-types:
+
+Key and value types
+-------------------
+
+The accepted types for keys and values vary by backend. Keys and values are
+handled the same way, except where noted below:
+
+* **Traditional backends:**
+
+  * :mod:`dbm.gnu` and :mod:`dbm.ndbm`: Accept :class:`str` and :class:`bytes`
+    objects.
+  * :mod:`dbm.dumb`: Accepts :class:`str` and :class:`bytes` objects;
+    :class:`bytearray` is acceptable as a value, but not as a key.
+
+* **SQLite backend** (:mod:`dbm.sqlite3`): Accepts :class:`str`, :class:`bytes`,
+  :class:`int`, :class:`float`, :class:`bool`, :class:`bytearray`,
+  :class:`memoryview`, and :class:`array.array` objects.
+
+**Storage format:**
+
+All keys and values are stored as :class:`bytes` objects in the database.
+When retrieving, you'll always get bytes back, regardless of the original
+type stored.
+
+**Type conversion examples:**
+
+* ``db['key'] = 'string'`` stored as ``b'string'``
+* ``db['key'] = bytearray(b'data')`` stored as ``b'data'``
+  (:mod:`dbm.dumb` and :mod:`dbm.sqlite3` only)
+* ``db['key'] = 42`` stored as ``b'42'`` (:mod:`dbm.sqlite3` only)
+* ``db['key'] = 3.14`` stored as ``b'3.14'`` (:mod:`dbm.sqlite3` only)
+* ``db['key'] = True`` stored as ``b'1'`` (:mod:`dbm.sqlite3` only)
+* ``db['key'] = False`` stored as ``b'0'`` (:mod:`dbm.sqlite3` only)
+* ``db['key'] = memoryview(b'data')`` stored as ``b'data'``
+  (:mod:`dbm.sqlite3` only)
+* ``db['key'] = array.array('i', [1, 2, 3])`` stored as bytes (for example, on
+  little-endian: ``b'\x01\x00\x00\x00\x02\x00\x00\x00\x03\x00\x00\x00'``)
+  (:mod:`dbm.sqlite3` only)
+
+
 The following example records some hostnames and a corresponding title,  and
 then prints out the contents of the database::
 
@@ -142,8 +184,9 @@ then prints out the contents of the database::
        # Often-used methods of the dict interface work too.
        print(db.get('python.org', b'not present'))
 
-       # Storing a non-string key or value will raise an exception (most
-       # likely a TypeError).
+       # Storing a non-string key or value behavior depends on the backend:
+       # - Traditional backends (ndbm, gnu, dumb) will raise a TypeError
+       # - The sqlite3 backend accepts it and converts to bytes
        db['www.yahoo.com'] = 4
 
    # db is automatically closed when leaving the with statement.