Merge remote-tracking branch 'upstream/main' into csv-writer-special-bitmap

Author: serhiy-storchaka

.claude/CLAUDE.md

@@ -0,0 +1 @@
+../AGENTS.md

.github/CODEOWNERS

@@ -630,7 +630,7 @@ Lib/test/test_unittest/testmock/ @cjw296
 Doc/library/zlib.rst          @StanFromIreland
 Lib/compression/zlib.py       @StanFromIreland
 Lib/test/test_zlib.py         @StanFromIreland
-Modules/_zlibmodule.c         @StanFromIreland
+Modules/zlibmodule.c          @StanFromIreland
 
 # Zipfile.Path
 Lib/test/test_zipfile/_path/  @jaraco

.github/workflows/reusable-docs.yml

@@ -86,6 +86,9 @@ jobs:
           --fail-if-regression \
           --fail-if-improved \
           --fail-if-new-news-nit
+    - name: 'Build list of changes'
+      run: |
+        make -C Doc/ PYTHON=../python changes
     - name: 'Collect HTML IDs'
       if: github.event_name == 'pull_request'
       run: python Doc/tools/check-html-ids.py collect Doc/build/html -o Doc/build/html-ids-head.json.gz

.gitignore

@@ -178,8 +178,12 @@ Python/frozen_modules/MANIFEST
 /python
 !/Python/
 
-# People's custom https://docs.anthropic.com/en/docs/claude-code/memory configs.
-/.claude/
+# Local AI agent scratch state (per-PR and per-branch notebooks, sandbox
+# experiments) and personal agent overrides, none of which are committed.
+/.claude/pr-*
+/.claude/branch-*
+/.claude/sandbox/
+AGENTS.local.md
 CLAUDE.local.md
 
 #### main branch only stuff below this line, things to backport go above. ####

AGENTS.md

@@ -0,0 +1,16 @@
+# AI agent guidance
+
+CPython has a [policy on the use of AI tools](https://devguide.python.org/getting-started/ai-tools/).
+All use of AI tools and agents when working on or interacting with CPython
+must follow it.
+
+> [!important]
+> **Primary directive**: Read the policy before making or proposing any changes.
+
+When acting on this repository, apply the policy's core principles:
+
+- Consider whether the change is necessary.
+- Make minimal, focused changes.
+- Follow existing coding style and patterns.
+- Write tests that exercise the change.
+- Keep backwards compatibility with prior releases in mind.

Doc/c-api/bytes.rst

@@ -231,6 +231,7 @@ called with a non-bytes parameter.
    Resize a bytes object. *newsize* will be the new length of the bytes object.
    You can think of it as creating a new bytes object and destroying the old
    one, only more efficiently.
+
    Pass the address of an
    existing bytes object as an lvalue (it may be written into), and the new size
    desired.  On success, *\*bytes* holds the resized bytes object and ``0`` is
@@ -239,6 +240,11 @@ called with a non-bytes parameter.
    *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
    returned.
 
+   While bytes objects are usually immutable in Python, this special C API
+   allows mutating a bytes object in-place. The returned bytes object can still
+   be mutated using :c:func:`PyBytesWriter_GetData`; except if *newsize* is
+   zero in which case it returns the immutable empty bytes string.
+
    .. soft-deprecated:: 3.15
       Use the :c:type:`PyBytesWriter` API instead.
 
@@ -290,10 +296,10 @@ object.
 
 .. c:type:: PyBytesWriter
 
-   A bytes writer instance.
+   A bytes writer object.
 
-   The API is **not thread safe**: a writer should only be used by a single
-   thread at the same time.
+   The API is **not thread safe**. A :c:type:`PyBytesWriter` object must only
+   be used by a single thread, it must not be shared between threads.
 
    The instance must be destroyed by :c:func:`PyBytesWriter_Finish` on
    success, or :c:func:`PyBytesWriter_Discard` on error.
@@ -429,7 +435,7 @@ Low-level API
    On success, return ``0``.
    On error, set an exception and return ``-1``.
 
-   *size* can be negative to shrink the writer.
+   *grow* can be negative to shrink the writer.
 
 .. c:function:: void* PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)
 

Doc/c-api/complex.rst

@@ -197,3 +197,6 @@ the :ref:`Number Protocol <number>` API or use native complex types, like
    Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows.
 
    .. deprecated:: 3.15
+
+   .. versionchanged:: next
+      This function leaves :c:data:`errno` unchanged on success.

Doc/c-api/marshal.rst

@@ -16,6 +16,20 @@ Numeric values are stored with the least significant byte first.
 The module supports several versions of the data format; see
 the :py:mod:`Python module documentation <marshal>` for details.
 
+The following exceptions can be raised by these functions:
+:exc:`ValueError` if the value cannot be marshalled,
+:exc:`ValueError` or :exc:`TypeError` if the data is malformed,
+:exc:`EOFError` if the end of the data is reached before the value is complete,
+:exc:`OSError` if reading from or writing to a :c:expr:`FILE*` fails,
+:exc:`KeyboardInterrupt` if reading or writing is interrupted by a signal,
+and :exc:`MemoryError` if memory allocation fails.
+
+.. versionchanged:: next
+   Previously, in functions taking a :c:expr:`FILE*`,
+   the reading functions raised :exc:`EOFError`
+   instead of :exc:`OSError` and :exc:`KeyboardInterrupt`,
+   and the writing functions ignored I/O errors and interruptions.
+
 .. c:macro:: Py_MARSHAL_VERSION
 
    The current format version. See :py:data:`marshal.version`.
@@ -42,6 +56,8 @@ the :py:mod:`Python module documentation <marshal>` for details.
    Return a bytes object containing the marshalled representation of *value*.
    *version* indicates the file format.
 
+   On error, raises an exception and returns ``NULL``.
+
 
 The following functions allow marshalled values to be read back in.
 
@@ -52,8 +68,7 @@ The following functions allow marshalled values to be read back in.
    for reading.  Only a 32-bit value can be read in using this function,
    regardless of the native size of :c:expr:`long`.
 
-   On error, sets the appropriate exception (:exc:`EOFError`) and returns
-   ``-1``.
+   On error, raises an exception and returns ``-1``.
 
 
 .. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
@@ -62,17 +77,15 @@ The following functions allow marshalled values to be read back in.
    for reading.  Only a 16-bit value can be read in using this function,
    regardless of the native size of :c:expr:`short`.
 
-   On error, sets the appropriate exception (:exc:`EOFError`) and returns
-   ``-1``.
+   On error, raises an exception and returns ``-1``.
 
 
 .. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
 
    Return a Python object from the data stream in a :c:expr:`FILE*` opened for
    reading.
 
-   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
-   or :exc:`TypeError`) and returns ``NULL``.
+   On error, raises an exception and returns ``NULL``.
 
 
 .. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
@@ -85,15 +98,13 @@ The following functions allow marshalled values to be read back in.
    file.  Only use this variant if you are certain that you won't be reading
    anything else from the file.
 
-   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
-   or :exc:`TypeError`) and returns ``NULL``.
+   On error, raises an exception and returns ``NULL``.
 
 
 .. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
 
    Return a Python object from the data stream in a byte buffer
    containing *len* bytes pointed to by *data*.
 
-   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
-   or :exc:`TypeError`) and returns ``NULL``.
+   On error, raises an exception and returns ``NULL``.
 

Doc/c-api/module.rst

@@ -853,7 +853,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyModule_FromSlotsAndSpec` in new code.
 
@@ -877,7 +877,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyModule_FromSlotsAndSpec` in new code.
 
@@ -887,7 +887,7 @@ struct:
 
    .. versionadded:: 3.5
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       To run a module's own execution slots, prefer :c:func:`PyModule_Exec`,
       which works on modules that were not created from a

Doc/c-api/type.rst

@@ -828,7 +828,7 @@ They will continue to work, but new features will be added as slots for
 
    .. versionadded:: 3.12
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -859,7 +859,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -885,7 +885,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.
 
@@ -910,7 +910,7 @@ They will continue to work, but new features will be added as slots for
       Creating classes whose metaclass overrides
       :c:member:`~PyTypeObject.tp_new` is no longer allowed.
 
-   .. soft-deprecated:: next
+   .. soft-deprecated:: 3.15
 
       Prefer :c:func:`PyType_FromSlots` in new code.