Deploying to gh-pages from @ a8c0d8e 🚀

Author: mattwang44

_sources/howto/free-threading-extensions.rst.txt

@@ -159,6 +159,8 @@ that return :term:`strong references <strong reference>`.
 +===================================+===================================+
 | :c:func:`PyList_GetItem`          | :c:func:`PyList_GetItemRef`       |
 +-----------------------------------+-----------------------------------+
+| :c:func:`PyList_GET_ITEM`         | :c:func:`PyList_GetItemRef`       |
++-----------------------------------+-----------------------------------+
 | :c:func:`PyDict_GetItem`          | :c:func:`PyDict_GetItemRef`       |
 +-----------------------------------+-----------------------------------+
 | :c:func:`PyDict_GetItemWithError` | :c:func:`PyDict_GetItemRef`       |

_sources/library/asyncio-eventloop.rst.txt

@@ -595,6 +595,12 @@ Opening network connections
      to bind the socket locally.  The *local_host* and *local_port*
      are looked up using :meth:`getaddrinfo`.
 
+     .. note::
+
+        On Windows, when using the proactor event loop with ``local_addr=None``,
+        an :exc:`OSError` with :attr:`!errno.WSAEINVAL` will be raised
+        when running it.
+
    * *remote_addr*, if given, is a ``(remote_host, remote_port)`` tuple used
      to connect the socket to a remote address.  The *remote_host* and
      *remote_port* are looked up using :meth:`getaddrinfo`.

_sources/library/asyncio-queue.rst.txt

@@ -102,17 +102,34 @@ Queue
 
    .. method:: shutdown(immediate=False)
 
-      Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put`
+      Put a :class:`Queue` instance into a shutdown mode.
+
+      The queue can no longer grow.
+      Future calls to :meth:`~Queue.put` raise :exc:`QueueShutDown`.
+      Currently blocked callers of :meth:`~Queue.put` will be unblocked
+      and will raise :exc:`QueueShutDown` in the formerly blocked thread.
+
+      If *immediate* is false (the default), the queue can be wound
+      down normally with :meth:`~Queue.get` calls to extract tasks
+      that have already been loaded.
+
+      And if :meth:`~Queue.task_done` is called for each remaining task, a
+      pending :meth:`~Queue.join` will be unblocked normally.
+
+      Once the queue is empty, future calls to :meth:`~Queue.get` will
       raise :exc:`QueueShutDown`.
 
-      By default, :meth:`~Queue.get` on a shut down queue will only
-      raise once the queue is empty. Set *immediate* to true to make
-      :meth:`~Queue.get` raise immediately instead.
+      If *immediate* is true, the queue is terminated immediately.
+      The queue is drained to be completely empty and the count
+      of unfinished tasks is reduced by the number of tasks drained.
+      If unfinished tasks is zero, callers of :meth:`~Queue.join`
+      are unblocked.  Also, blocked callers of :meth:`~Queue.get`
+      are unblocked and will raise :exc:`QueueShutDown` because the
+      queue is empty.
 
-      All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get`
-      will be unblocked. If *immediate* is true, a task will be marked
-      as done for each remaining item in the queue, which may unblock
-      callers of :meth:`~Queue.join`.
+      Use caution when using :meth:`~Queue.join` with *immediate* set
+      to true. This unblocks the join even when no work has been done
+      on the tasks, violating the usual invariant for joining a queue.
 
       .. versionadded:: 3.13
 
@@ -129,9 +146,6 @@ Queue
       call was received for every item that had been :meth:`~Queue.put`
       into the queue).
 
-      ``shutdown(immediate=True)`` calls :meth:`task_done` for each
-      remaining item in the queue.
-
       Raises :exc:`ValueError` if called more times than there were
       items placed in the queue.
 

_sources/library/codecs.rst.txt

@@ -1472,6 +1472,36 @@ to :class:`bytes` mappings. They are not supported by :meth:`bytes.decode`
    Restoration of the aliases for the binary transforms.
 
 
+.. _standalone-codec-functions:
+
+Standalone Codec Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following functions provide encoding and decoding functionality similar to codecs,
+but are not available as named codecs through :func:`codecs.encode` or :func:`codecs.decode`.
+They are used internally (for example, by :mod:`pickle`) and behave similarly to the
+``string_escape`` codec that was removed in Python 3.
+
+.. function:: codecs.escape_encode(input, errors=None)
+
+   Encode *input* using escape sequences. Similar to how :func:`repr` on bytes
+   produces escaped byte values.
+
+   *input* must be a :class:`bytes` object.
+
+   Returns a tuple ``(output, length)`` where *output* is a :class:`bytes`
+   object and *length* is the number of bytes consumed.
+
+.. function:: codecs.escape_decode(input, errors=None)
+
+   Decode *input* from escape sequences back to the original bytes.
+
+   *input* must be a :term:`bytes-like object`.
+
+   Returns a tuple ``(output, length)`` where *output* is a :class:`bytes`
+   object and *length* is the number of bytes consumed.
+
+
 .. _text-transforms:
 
 Text Transforms

_sources/library/concurrent.futures.rst.txt

@@ -243,6 +243,11 @@ that :class:`ProcessPoolExecutor` will not work in the interactive interpreter.
 Calling :class:`Executor` or :class:`Future` methods from a callable submitted
 to a :class:`ProcessPoolExecutor` will result in deadlock.
 
+Note that the restrictions on functions and arguments needing to picklable as
+per :class:`multiprocessing.Process` apply when using :meth:`~Executor.submit`
+and :meth:`~Executor.map` on a :class:`ProcessPoolExecutor`. A function defined
+in a REPL or a lambda should not be expected to work.
+
 .. class:: ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)
 
    An :class:`Executor` subclass that executes calls asynchronously using a pool

_sources/library/enum.rst.txt

@@ -504,16 +504,31 @@ Data Types
 
 .. class:: StrEnum
 
-   ``StrEnum`` is the same as :class:`Enum`, but its members are also strings and can be used
-   in most of the same places that a string can be used.  The result of any string
-   operation performed on or with a *StrEnum* member is not part of the enumeration.
+   *StrEnum* is the same as :class:`Enum`, but its members are also strings and
+   can be used in most of the same places that a string can be used. The result
+   of any string operation performed on or with a *StrEnum* member is not part
+   of the enumeration.
+
+   >>> from enum import StrEnum, auto
+   >>> class Color(StrEnum):
+   ...     RED = 'r'
+   ...     GREEN = 'g'
+   ...     BLUE = 'b'
+   ...     UNKNOWN = auto()
+   ...
+   >>> Color.RED
+   <Color.RED: 'r'>
+   >>> Color.UNKNOWN
+   <Color.UNKNOWN: 'unknown'>
+   >>> str(Color.UNKNOWN)
+   'unknown'
 
    .. note::
 
       There are places in the stdlib that check for an exact :class:`str`
       instead of a :class:`str` subclass (i.e. ``type(unknown) == str``
       instead of ``isinstance(unknown, str)``), and in those locations you
-      will need to use ``str(StrEnum.member)``.
+      will need to use ``str(MyStrEnum.MY_MEMBER)``.
 
    .. note::
 

_sources/library/http.cookies.rst.txt

@@ -147,9 +147,12 @@ Morsel Objects
    in HTTP requests, and is not accessible through JavaScript. This is intended
    to mitigate some forms of cross-site scripting.
 
-   The attribute :attr:`samesite` specifies that the browser is not allowed to
-   send the cookie along with cross-site requests. This helps to mitigate CSRF
-   attacks. Valid values for this attribute are "Strict" and "Lax".
+   The attribute :attr:`samesite` controls when the browser sends the cookie with
+   cross-site requests. This helps to mitigate CSRF attacks. Valid values are
+   "Strict" (only sent with same-site requests), "Lax" (sent with same-site
+   requests and top-level navigations), and "None" (sent with same-site and
+   cross-site requests). When using "None", the "secure" attribute must also
+   be set, as required by modern browsers.
 
    The keys are case-insensitive and their default value is ``''``.
 

_sources/library/importlib.resources.rst.txt

@@ -16,11 +16,12 @@ within *packages*.
 "Resources" are file-like resources associated with a module or package in
 Python. The resources may be contained directly in a package, within a
 subdirectory contained in that package, or adjacent to modules outside a
-package. Resources may be text or binary. As a result, Python module sources
-(.py) of a package and compilation artifacts (pycache) are technically
-de-facto resources of that package. In practice, however, resources are
-primarily those non-Python artifacts exposed specifically by the package
-author.
+package. Resources may be text or binary. As a result, a package's Python
+module sources (.py), compilation artifacts (pycache), and installation
+artifacts (like :func:`reserved filenames <os.path.isreserved>`
+in directories) are technically de-facto resources of that package.
+In practice, however, resources are primarily those non-Python artifacts
+exposed specifically by the package author.
 
 Resources can be opened or read in either binary or text mode.
 

_sources/library/multiprocessing.rst.txt

@@ -97,6 +97,10 @@ To show the individual process IDs involved, here is an expanded example::
 For an explanation of why the ``if __name__ == '__main__'`` part is
 necessary, see :ref:`multiprocessing-programming`.
 
+The arguments to :class:`Process` usually need to be unpickleable from within
+the child process. If you tried typing the above example directly into a REPL it
+could lead to an :exc:`AttributeError` in the child process trying to locate the
+*f* function in the ``__main__`` module.
 
 
 .. _multiprocessing-start-methods:
@@ -107,6 +111,8 @@ Contexts and start methods
 Depending on the platform, :mod:`multiprocessing` supports three ways
 to start a process.  These *start methods* are
 
+  .. _multiprocessing-start-method-spawn:
+
   *spawn*
     The parent process starts a fresh Python interpreter process.  The
     child process will only inherit those resources necessary to run
@@ -117,6 +123,8 @@ to start a process.  These *start methods* are
 
     Available on POSIX and Windows platforms.  The default on Windows and macOS.
 
+  .. _multiprocessing-start-method-fork:
+
   *fork*
     The parent process uses :func:`os.fork` to fork the Python
     interpreter.  The child process, when it begins, is effectively
@@ -137,6 +145,8 @@ to start a process.  These *start methods* are
        raise a :exc:`DeprecationWarning`. Use a different start method.
        See the :func:`os.fork` documentation for further explanation.
 
+  .. _multiprocessing-start-method-forkserver:
+
   *forkserver*
     When the program starts and selects the *forkserver* start method,
     a server process is spawned.  From then on, whenever a new process
@@ -218,9 +228,12 @@ processes for a different context.  In particular, locks created using
 the *fork* context cannot be passed to processes started using the
 *spawn* or *forkserver* start methods.
 
-A library which wants to use a particular start method should probably
-use :func:`get_context` to avoid interfering with the choice of the
-library user.
+Libraries using :mod:`multiprocessing` or
+:class:`~concurrent.futures.ProcessPoolExecutor` should be designed to allow
+their users to provide their own multiprocessing context.  Using a specific
+context of your own within a library can lead to incompatibilities with the
+rest of the library user's application.  Always document if your library
+requires a specific start method.
 
 .. warning::
 
@@ -518,9 +531,42 @@ The :mod:`multiprocessing` package mostly replicates the API of the
    to pass to *target*.
 
    If a subclass overrides the constructor, it must make sure it invokes the
-   base class constructor (:meth:`Process.__init__`) before doing anything else
+   base class constructor (``super().__init__()``) before doing anything else
    to the process.
 
+   .. note::
+
+      In general, all arguments to :class:`Process` must be picklable.  This is
+      frequently observed when trying to create a :class:`Process` or use a
+      :class:`concurrent.futures.ProcessPoolExecutor` from a REPL with a
+      locally defined *target* function.
+
+      Passing a callable object defined in the current REPL session causes the
+      child process to die via an uncaught :exc:`AttributeError` exception when
+      starting as *target* must have been defined within an importable module
+      in order to be loaded during unpickling.
+
+      Example of this uncatchable error from the child::
+
+         >>> import multiprocessing as mp
+         >>> def knigit():
+         ...     print("Ni!")
+         ...
+         >>> process = mp.Process(target=knigit)
+         >>> process.start()
+         >>> Traceback (most recent call last):
+           File ".../multiprocessing/spawn.py", line ..., in spawn_main
+           File ".../multiprocessing/spawn.py", line ..., in _main
+         AttributeError: module '__main__' has no attribute 'knigit'
+         >>> process
+         <SpawnProcess name='SpawnProcess-1' pid=379473 parent=378707 stopped exitcode=1>
+
+      See :ref:`multiprocessing-programming-spawn`.  While this restriction is
+      not true if using the ``"fork"`` start method, as of Python ``3.14`` that
+      is no longer the default on any platform.  See
+      :ref:`multiprocessing-start-methods`.
+      See also :gh:`132898`.
+
    .. versionchanged:: 3.3
       Added the *daemon* parameter.
 
@@ -2985,6 +3031,9 @@ Beware of replacing :data:`sys.stdin` with a "file like object"
 
     For more information, see :issue:`5155`, :issue:`5313` and :issue:`5331`
 
+.. _multiprocessing-programming-spawn:
+.. _multiprocessing-programming-forkserver:
+
 The *spawn* and *forkserver* start methods
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -2993,10 +3042,10 @@ start method.
 
 More picklability
 
-    Ensure that all arguments to :meth:`Process.__init__` are picklable.
-    Also, if you subclass :class:`~multiprocessing.Process` then make sure that
-    instances will be picklable when the :meth:`Process.start
-    <multiprocessing.Process.start>` method is called.
+    Ensure that all arguments to :class:`~multiprocessing.Process` are
+    picklable.  Also, if you subclass ``Process.__init__``, you must make sure
+    that instances will be picklable when the
+    :meth:`Process.start <multiprocessing.Process.start>` method is called.
 
 Global variables
 

_sources/library/os.path.rst.txt

@@ -94,7 +94,7 @@ the :mod:`glob` module.)
       Any iterable can now be passed, rather than just sequences.
 
 
-.. function:: commonprefix(list)
+.. function:: commonprefix(list, /)
 
    Return the longest path prefix (taken character-by-character) that is a
    prefix of all paths in  *list*.  If *list* is empty, return the empty string
@@ -199,14 +199,14 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: getatime(path)
+.. function:: getatime(path, /)
 
    Return the time of last access of *path*.  The return value is a floating-point number giving
    the number of seconds since the epoch (see the  :mod:`time` module).  Raise
    :exc:`OSError` if the file does not exist or is inaccessible.
 
 
-.. function:: getmtime(path)
+.. function:: getmtime(path, /)
 
    Return the time of last modification of *path*.  The return value is a floating-point number
    giving the number of seconds since the epoch (see the  :mod:`time` module).
@@ -216,7 +216,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: getctime(path)
+.. function:: getctime(path, /)
 
    Return the system's ctime which, on some systems (like Unix) is the time of the
    last metadata change, and, on others (like Windows), is the creation time for *path*.
@@ -228,7 +228,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: getsize(path)
+.. function:: getsize(path, /)
 
    Return the size, in bytes, of *path*.  Raise :exc:`OSError` if the file does
    not exist or is inaccessible.
@@ -351,7 +351,7 @@ the :mod:`glob` module.)
    .. versionadded:: 3.13
 
 
-.. function:: join(path, *paths)
+.. function:: join(path, /, *paths)
 
    Join one or more path segments intelligently.  The return value is the
    concatenation of *path* and all members of *\*paths*, with exactly one
@@ -402,7 +402,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: realpath(path, *, strict=False)
+.. function:: realpath(path, /, *, strict=False)
 
    Return the canonical path of the specified filename, eliminating any symbolic
    links encountered in the path (if they are supported by the operating
@@ -471,7 +471,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: samefile(path1, path2)
+.. function:: samefile(path1, path2, /)
 
    Return ``True`` if both pathname arguments refer to the same file or directory.
    This is determined by the device number and i-node number and raises an
@@ -498,7 +498,7 @@ the :mod:`glob` module.)
       Accepts a :term:`path-like object`.
 
 
-.. function:: samestat(stat1, stat2)
+.. function:: samestat(stat1, stat2, /)
 
    Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file.
    These structures may have been returned by :func:`os.fstat`,