Merge pull request #1 from python/main

docs.github.com>desktop

Author: tngoc3395-stack

Doc/c-api/exceptions.rst

@@ -119,6 +119,21 @@ Printing and clearing
    .. versionadded:: 3.12
 
 
+.. c:function:: void PyErr_Display(PyObject *unused, PyObject *value, PyObject *tb)
+
+   Legacy variant of :c:func:`PyErr_DisplayException`.
+
+   Print the exception *value* with its traceback to :data:`sys.stderr`.
+   If *value* has no traceback set, *tb* is used as its traceback.
+   The first argument is ignored.
+
+   If :data:`sys.stderr` is ``None``, nothing is printed.
+   If :data:`sys.stderr` is not set, the exception is dumped to the
+   C ``stderr`` stream instead.
+
+   .. deprecated:: 3.12
+      Use :c:func:`PyErr_DisplayException` instead.
+
 Raising exceptions
 ==================
 

Doc/c-api/init_config.rst

@@ -1235,9 +1235,9 @@ PyConfig
 
    .. c:member:: wchar_t* base_executable
 
-      Python base executable: :data:`sys._base_executable`.
+      Python base executable: ``sys._base_executable``.
 
-      Set by the :envvar:`__PYVENV_LAUNCHER__` environment variable.
+      Set by the ``__PYVENV_LAUNCHER__`` environment variable.
 
       Set from :c:member:`PyConfig.executable` if ``NULL``.
 
@@ -1748,7 +1748,7 @@ PyConfig
 
       * On macOS, use :envvar:`PYTHONEXECUTABLE` environment variable if set.
       * If the ``WITH_NEXT_FRAMEWORK`` macro is defined, use
-        :envvar:`__PYVENV_LAUNCHER__` environment variable if set.
+        ``__PYVENV_LAUNCHER__`` environment variable if set.
       * Use ``argv[0]`` of :c:member:`~PyConfig.argv` if available and
         non-empty.
       * Otherwise, use ``L"python"`` on Windows, or ``L"python3"`` on other
@@ -1984,8 +1984,7 @@ PyConfig
 
       The :mod:`warnings` module adds :data:`sys.warnoptions` in the reverse
       order: the last :c:member:`PyConfig.warnoptions` item becomes the first
-      item of :data:`warnings.filters` which is checked first (highest
-      priority).
+      item of ``warnings.filters`` which is checked first (highest priority).
 
       The :option:`-W` command line options adds its value to
       :c:member:`~PyConfig.warnoptions`, it can be used multiple times.

Doc/c-api/intro.rst

@@ -1163,7 +1163,7 @@ when defined by the compiler, will also implicitly enable :c:macro:`!Py_DEBUG`.
 In addition to the reference count debugging described below, extra checks are
 performed. See :ref:`Python Debug Build <debug-build>` for more details.
 
-Defining :c:macro:`Py_TRACE_REFS` enables reference tracing
+Defining ``Py_TRACE_REFS`` enables reference tracing
 (see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
 When defined, a circular doubly linked list of active objects is maintained by adding two extra
 fields to every :c:type:`PyObject`.  Total allocations are tracked as well.  Upon

Doc/library/asyncio-task.rst

@@ -433,6 +433,10 @@ unless it is :exc:`asyncio.CancelledError`,
 is also included in the exception group.
 The same special case is made for
 :exc:`KeyboardInterrupt` and :exc:`SystemExit` as in the previous paragraph.
+There is an additional special case made only for the body of the
+``async with``: if it raises :exc:`GeneratorExit` and none of the
+other tasks raise exceptions that would be reported, then the
+:exc:`GeneratorExit` is reraised.
 
 Task groups are careful not to mix up the internal cancellation used to
 "wake up" their :meth:`~object.__aexit__` with cancellation requests
@@ -456,6 +460,10 @@ reported by :meth:`asyncio.Task.cancelling`.
    Improved handling of simultaneous internal and external cancellations
    and correct preservation of cancellation counts.
 
+.. versionchanged:: 3.15
+
+   Addition of the special case for :exc:`GeneratorExit`.
+
 Sleeping
 ========
 

Doc/library/multiprocessing.rst

@@ -2536,7 +2536,7 @@ with the :class:`Pool` class.
       Callbacks should complete immediately since otherwise the thread which
       handles the results will get blocked.
 
-   .. method:: imap(func, iterable[, chunksize])
+   .. method:: imap(func, iterable, chunksize=1, *, buffersize=None)
 
       A lazier version of :meth:`.map`.
 
@@ -2550,12 +2550,27 @@ with the :class:`Pool` class.
       ``next(timeout)`` will raise :exc:`multiprocessing.TimeoutError` if the
       result cannot be returned within *timeout* seconds.
 
-   .. method:: imap_unordered(func, iterable[, chunksize])
+      The *iterable* is collected immediately rather than lazily, unless a
+      *buffersize* is specified to limit the number of submitted tasks whose
+      results have not yet been yielded. If the buffer is full, iteration over
+      the *iterables* pauses until a result is yielded from the buffer.
+      To fully utilize pool's capacity when using this feature,
+      set *buffersize* at least to the number of processes in pool
+      (to consume *iterable* as you go), or even higher
+      (to prefetch the next ``N=buffersize-processes`` arguments).
+
+      .. versionchanged:: next
+         Added the *buffersize* parameter.
+
+   .. method:: imap_unordered(func, iterable, chunksize=1, *, buffersize=None)
 
       The same as :meth:`imap` except that the ordering of the results from the
       returned iterator should be considered arbitrary.  (Only when there is
       only one worker process is the order guaranteed to be "correct".)
 
+      .. versionchanged:: next
+         Added the *buffersize* parameter.
+
    .. method:: starmap(func, iterable[, chunksize])
 
       Like :meth:`~multiprocessing.pool.Pool.map` except that the

Doc/library/os.rst

@@ -802,9 +802,9 @@ process and user.
    Returns information identifying the current operating system.
    The return value is a :class:`uname_result`.
 
-   On macOS, iOS and Android, this returns the *kernel* name and version (i.e.,
+   On macOS, iOS and Android, this returns the *kernel* name and release (i.e.,
    ``'Darwin'`` on macOS and iOS; ``'Linux'`` on Android). :func:`platform.uname`
-   can be used to get the user-facing operating system name and version on iOS and
+   can be used to get the user-facing operating system name and release on iOS and
    Android.
 
    .. seealso::

Doc/library/platform.rst

@@ -141,6 +141,8 @@ Cross platform
    Returns the system's release, e.g. ``'2.2.0'`` or ``'NT'``. An empty string is
    returned if the value cannot be determined.
 
+   On iOS and Android, this is the user-facing OS release. To obtain the
+   Darwin or Linux kernel release, use :func:`os.uname`.
 
 .. function:: system()
 
@@ -163,9 +165,6 @@ Cross platform
    Returns the system's release version, e.g. ``'#3 on degas'``. An empty string is
    returned if the value cannot be determined.
 
-   On iOS and Android, this is the user-facing OS version. To obtain the
-   Darwin or Linux kernel version, use :func:`os.uname`.
-
 .. function:: uname()
 
    Fairly portable uname interface. Returns a :func:`~collections.namedtuple`

Doc/tools/.nitignore

@@ -2,9 +2,6 @@
 # as tested on the CI via check-warnings.py in reusable-docs.yml.
 # Keep lines sorted lexicographically to help avoid merge conflicts.
 
-Doc/c-api/init_config.rst
-Doc/c-api/intro.rst
-Doc/c-api/stable.rst
 Doc/library/ast.rst
 Doc/library/asyncio-extending.rst
 Doc/library/email.charset.rst

Doc/whatsnew/3.16.rst

@@ -376,6 +376,22 @@ math
   (Contributed by Jeff Epler in :gh:`150534`.)
 
 
+multiprocessing
+---------------
+
+* Add the optional ``buffersize`` parameter to
+  :meth:`multiprocessing.pool.Pool.imap` and
+  :meth:`multiprocessing.pool.Pool.imap_unordered` to limit the number of
+  submitted tasks whose results have not yet been yielded. If the buffer is
+  full, iteration over the *iterables* pauses until a result is yielded from
+  the buffer. To fully utilize pool's capacity when using this feature, set
+  *buffersize* at least to the number of processes in pool (to consume
+  *iterable* as you go), or even higher (to prefetch the next
+  ``N=buffersize-processes`` arguments).
+
+  (Contributed by Oleksandr Baltian in :gh:`136871`.)
+
+
 os
 --
 
@@ -606,7 +622,7 @@ module_name
 
 
 Removed
-=======
+========
 
 annotationlib
 -------------