Merge remote-tracking branch 'upstream/main' into remove-mmap-resize

Author: aisk

.pre-commit-config.yaml

@@ -14,6 +14,10 @@ repos:
         name: Run Ruff (lint) on Tools/build/
         args: [--exit-non-zero-on-fix, --config=Tools/build/.ruff.toml]
         files: ^Tools/build/
+      - id: ruff
+        name: Run Ruff (lint) on Tools/i18n/
+        args: [--exit-non-zero-on-fix, --config=Tools/i18n/.ruff.toml]
+        files: ^Tools/i18n/
       - id: ruff
         name: Run Ruff (lint) on Argument Clinic
         args: [--exit-non-zero-on-fix, --config=Tools/clinic/.ruff.toml]

Doc/extending/extending.rst

@@ -426,7 +426,7 @@ A pointer to the module definition must be returned via :c:func:`PyModuleDef_Ini
 so that the import machinery can create the module and store it in ``sys.modules``.
 
 When embedding Python, the :c:func:`!PyInit_spam` function is not called
-automatically unless there's an entry in the :c:data:`PyImport_Inittab` table.
+automatically unless there's an entry in the :c:data:`!PyImport_Inittab` table.
 To add the module to the initialization table, use :c:func:`PyImport_AppendInittab`,
 optionally followed by an import of the module::
 

Doc/glossary.rst

@@ -21,7 +21,9 @@ Glossary
         right delimiters (parentheses, square brackets, curly braces or triple
         quotes), or after specifying a decorator.
 
-      * The :const:`Ellipsis` built-in constant.
+      .. index:: single: ...; ellipsis literal
+
+      * The three dots form of the :ref:`Ellipsis <bltin-ellipsis-object>` object.
 
    abstract base class
       Abstract base classes complement :term:`duck-typing` by

Doc/howto/descriptor.rst

@@ -420,7 +420,7 @@ Here are three practical data validation utilities:
 
         def validate(self, value):
             if not isinstance(value, str):
-                raise TypeError(f'Expected {value!r} to be an str')
+                raise TypeError(f'Expected {value!r} to be a str')
             if self.minsize is not None and len(value) < self.minsize:
                 raise ValueError(
                     f'Expected {value!r} to be no smaller than {self.minsize!r}'

Doc/howto/instrumentation.rst

@@ -269,6 +269,8 @@ should instead read:
 (assuming a :ref:`debug build <debug-build>` of CPython 3.6)
 
 
+.. _static-markers:
+
 Available static markers
 ------------------------
 

Doc/library/constants.rst

@@ -65,8 +65,9 @@ A small number of constants live in the built-in namespace.  They are:
 .. index:: single: ...; ellipsis literal
 .. data:: Ellipsis
 
-   The same as the ellipsis literal "``...``". Special value used mostly in conjunction
-   with extended slicing syntax for user-defined container data types.
+   The same as the ellipsis literal "``...``", an object frequently used to
+   indicate that something is omitted. Assignment to ``Ellipsis`` is possible, but
+   assignment to  ``...`` raises a :exc:`SyntaxError`.
    ``Ellipsis`` is the sole instance of the :data:`types.EllipsisType` type.
 
 

Doc/library/curses.rst

@@ -716,8 +716,10 @@ The module :mod:`curses` defines the following functions:
 Window Objects
 --------------
 
-Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
-the following methods and attributes:
+.. class:: window
+
+   Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
+   the following methods and attributes:
 
 
 .. method:: window.addch(ch[, attr])

Doc/library/hmac.rst

@@ -50,7 +50,9 @@ cannot be used with HMAC.
    .. versionadded:: 3.7
 
 
-An HMAC object has the following methods:
+.. class:: HMAC
+
+   An HMAC object has the following methods:
 
 .. method:: HMAC.update(msg)
 

Doc/library/mmap.rst

@@ -48,10 +48,11 @@ update the underlying file.
 
 To map anonymous memory, -1 should be passed as the fileno along with the length.
 
-.. class:: mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0)
+.. class:: mmap(fileno, length, tagname=None, \
+                access=ACCESS_DEFAULT, offset=0, *, trackfd=True)
 
    **(Windows version)** Maps *length* bytes from the file specified by the
-   file handle *fileno*, and creates a mmap object.  If *length* is larger
+   file descriptor *fileno*, and creates a mmap object.  If *length* is larger
    than the current size of the file, the file is extended to contain *length*
    bytes.  If *length* is ``0``, the maximum length of the map is the current
    size of the file, except that if the file is empty Windows raises an
@@ -69,6 +70,17 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
    will be relative to the offset from the beginning of the file. *offset*
    defaults to 0.  *offset* must be a multiple of the :const:`ALLOCATIONGRANULARITY`.
 
+   If *trackfd* is ``False``, the file handle corresponding to *fileno* will
+   not be duplicated, and the resulting :class:`!mmap` object will not
+   be associated with the map's underlying file.
+   This means that the :meth:`~mmap.mmap.size` and :meth:`~mmap.mmap.resize`
+   methods will fail.
+   This mode is useful to limit the number of open file handles.
+   The original file can be renamed (but not deleted) after closing *fileno*.
+
+   .. versionchanged:: next
+      The *trackfd* parameter was added.
+
    .. audit-event:: mmap.__new__ fileno,length,access,offset mmap.mmap
 
 .. class:: mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, \
@@ -314,6 +326,10 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
 
       Return the length of the file, which can be larger than the size of the
       memory-mapped area.
+      For anonymous mapping, return its size.
+
+      .. versionchanged:: next
+         Supports anonymous mapping on Unix.
 
 
    .. method:: tell()

Doc/library/profile.rst

@@ -28,7 +28,7 @@ The Python standard library provides three different profiling implementations:
 
 **Statistical Profiler:**
 
-1. :mod:`profile.sample` provides statistical profiling of running Python processes
+1. :mod:`!profiling.sampling` provides statistical profiling of running Python processes
    using periodic stack sampling. It can attach to any running Python process without
    requiring code modification or restart, making it ideal for production debugging.
 
@@ -55,26 +55,26 @@ The Python standard library provides three different profiling implementations:
 
 **Profiler Comparison:**
 
-+-------------------+----------------------+----------------------+----------------------+
-| Feature           | Statistical          | Deterministic        | Deterministic        |
-|                   | (``profile.sample``) | (``cProfile``)       | (``profile``)        |
-+===================+======================+======================+======================+
-| **Target**        | Running process      | Code you run         | Code you run         |
-+-------------------+----------------------+----------------------+----------------------+
-| **Overhead**      | Virtually none       | Moderate             | High                 |
-+-------------------+----------------------+----------------------+----------------------+
-| **Accuracy**      | Statistical approx.  | Exact call counts    | Exact call counts    |
-+-------------------+----------------------+----------------------+----------------------+
-| **Setup**         | Attach to any PID    | Instrument code      | Instrument code      |
-+-------------------+----------------------+----------------------+----------------------+
-| **Use Case**      | Production debugging | Development/testing  | Profiler extension   |
-+-------------------+----------------------+----------------------+----------------------+
-| **Implementation**| C extension          | C extension          | Pure Python          |
-+-------------------+----------------------+----------------------+----------------------+
++-------------------+--------------------------+----------------------+----------------------+
+| Feature           | Statistical              | Deterministic        | Deterministic        |
+|                   | (``profiling.sampling``) | (``cProfile``)       | (``profile``)        |
++===================+==========================+======================+======================+
+| **Target**        | Running process          | Code you run         | Code you run         |
++-------------------+--------------------------+----------------------+----------------------+
+| **Overhead**      | Virtually none           | Moderate             | High                 |
++-------------------+--------------------------+----------------------+----------------------+
+| **Accuracy**      | Statistical approx.      | Exact call counts    | Exact call counts    |
++-------------------+--------------------------+----------------------+----------------------+
+| **Setup**         | Attach to any PID        | Instrument code      | Instrument code      |
++-------------------+--------------------------+----------------------+----------------------+
+| **Use Case**      | Production debugging     | Development/testing  | Profiler extension   |
++-------------------+--------------------------+----------------------+----------------------+
+| **Implementation**| C extension              | C extension          | Pure Python          |
++-------------------+--------------------------+----------------------+----------------------+
 
 .. note::
 
-   The statistical profiler (:mod:`profile.sample`) is recommended for most production
+   The statistical profiler (:mod:`!profiling.sampling`) is recommended for most production
    use cases due to its extremely low overhead and ability to profile running processes
    without modification. It can attach to any Python process and collect performance
    data with minimal impact on execution speed, making it ideal for debugging
@@ -138,11 +138,11 @@ on an existing application.
 
 To profile an existing running process::
 
-   python -m profile.sample 1234
+   python -m profiling.sampling 1234
 
 To profile with custom settings::
 
-   python -m profile.sample -i 50 -d 30 1234
+   python -m profiling.sampling -i 50 -d 30 1234
 
 **Deterministic Profiling (Development/Testing):**
 
@@ -218,34 +218,34 @@ them in various ways.
 Statistical Profiler Command Line Interface
 ===========================================
 
-.. program:: profile.sample
+.. program:: profiling.sampling
 
-The :mod:`profile.sample` module can be invoked as a script to profile running processes::
+The :mod:`!profiling.sampling` module can be invoked as a script to profile running processes::
 
-   python -m profile.sample [options] PID
+   python -m profiling.sampling [options] PID
 
 **Basic Usage Examples:**
 
 Profile process 1234 for 10 seconds with default settings::
 
-   python -m profile.sample 1234
+   python -m profiling.sampling 1234
 
 Profile with custom interval and duration, save to file::
 
-   python -m profile.sample -i 50 -d 30 -o profile.stats 1234
+   python -m profiling.sampling -i 50 -d 30 -o profile.stats 1234
 
 Generate collapsed stacks to use with tools like `flamegraph.pl
 <https://github.com/brendangregg/FlameGraph>`_::
 
-   python -m profile.sample --collapsed 1234
+   python -m profiling.sampling --collapsed 1234
 
 Profile all threads, sort by total time::
 
-   python -m profile.sample -a --sort-tottime 1234
+   python -m profiling.sampling -a --sort-tottime 1234
 
 Profile with real-time sampling statistics::
 
-   python -m profile.sample --realtime-stats 1234
+   python -m profiling.sampling --realtime-stats 1234
 
 **Command Line Options:**
 
@@ -339,13 +339,13 @@ The statistical profiler produces output similar to deterministic profilers but
 
 .. _profile-cli:
 
-:mod:`profile.sample` Module Reference
+:mod:`!profiling.sampling` Module Reference
 =======================================================
 
-.. module:: profile.sample
+.. module:: profiling.sampling
    :synopsis: Python statistical profiler.
 
-This section documents the programmatic interface for the :mod:`profile.sample` module.
+This section documents the programmatic interface for the :mod:`!profiling.sampling` module.
 For command-line usage, see :ref:`sampling-profiler-cli`. For conceptual information
 about statistical profiling, see :ref:`statistical-profiling`
 
@@ -373,14 +373,14 @@ about statistical profiling, see :ref:`statistical-profiling`
    Examples::
 
        # Basic usage - profile process 1234 for 10 seconds
-       import profile.sample
-       profile.sample.sample(1234)
+       import profiling.sampling
+       profiling.sampling.sample(1234)
 
        # Profile with custom settings
-       profile.sample.sample(1234, duration_sec=30, sample_interval_usec=50, all_threads=True)
+       profiling.sampling.sample(1234, duration_sec=30, sample_interval_usec=50, all_threads=True)
 
        # Generate collapsed stack traces for flamegraph.pl
-       profile.sample.sample(1234, output_format='collapsed', filename='profile.collapsed')
+       profiling.sampling.sample(1234, output_format='collapsed', filename='profile.collapsed')
 
 .. class:: SampleProfiler(pid, sample_interval_usec, all_threads)
 
@@ -856,7 +856,7 @@ What Is Deterministic Profiling?
 call*, *function return*, and *exception* events are monitored, and precise
 timings are made for the intervals between these events (during which time the
 user's code is executing).  In contrast, :dfn:`statistical profiling` (which is
-provided by the :mod:`profile.sample` module) periodically samples the effective instruction pointer, and
+provided by the :mod:`!profiling.sampling` module) periodically samples the effective instruction pointer, and
 deduces where time is being spent.  The latter technique traditionally involves
 less overhead (as the code does not need to be instrumented), but provides only
 relative indications of where time is being spent.