Deploying to gh-pages from @ ead1032 🚀

Author: mattwang44

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 7a01c5ca1c710ac068e940d7a4e237da
+config: dd2be1ec916c30cc094164266e8a5c26
 tags: b5e2c454ba7771976391ed0cecdde553

_sources/c-api/memory.rst.txt

@@ -81,7 +81,7 @@ memory footprint as a whole. Consequently, under certain circumstances, the
 Python memory manager may or may not trigger appropriate actions, like garbage
 collection, memory compaction or other preventive procedures. Note that by using
 the C library allocator as shown in the previous example, the allocated memory
-for the I/O buffer escapes completely the Python memory manager.
+for the I/O buffer completely escapes the Python memory manager.
 
 .. seealso::
 
@@ -161,7 +161,7 @@ zero bytes.
 
 .. c:function:: void* PyMem_RawCalloc(size_t nelem, size_t elsize)
 
-   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   Allocates *nelem* elements each of size *elsize* bytes and returns
    a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the
    request fails. The memory is initialized to zeros.
 
@@ -239,7 +239,7 @@ In the GIL-enabled build (default build) the
 
 .. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
 
-   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   Allocates *nelem* elements each of size *elsize* bytes and returns
    a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the
    request fails. The memory is initialized to zeros.
 
@@ -372,7 +372,7 @@ The :ref:`default object allocator <default-memory-allocators>` uses the
 
 .. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
 
-   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   Allocates *nelem* elements each of size *elsize* bytes and returns
    a pointer of type :c:expr:`void*` to the allocated memory, or ``NULL`` if the
    request fails. The memory is initialized to zeros.
 

_sources/c-api/typeobj.rst.txt

@@ -3045,13 +3045,13 @@ Buffer Object Structures
    steps:
 
    (1) Check if the request can be met. If not, raise :exc:`BufferError`,
-       set :c:expr:`view->obj` to ``NULL`` and return ``-1``.
+       set ``view->obj`` to ``NULL`` and return ``-1``.
 
    (2) Fill in the requested fields.
 
    (3) Increment an internal counter for the number of exports.
 
-   (4) Set :c:expr:`view->obj` to *exporter* and increment :c:expr:`view->obj`.
+   (4) Set ``view->obj`` to *exporter* and increment ``view->obj``.
 
    (5) Return ``0``.
 
@@ -3077,10 +3077,10 @@ Buffer Object Structures
    schemes can be used:
 
    * Re-export: Each member of the tree acts as the exporting object and
-     sets :c:expr:`view->obj` to a new reference to itself.
+     sets ``view->obj`` to a new reference to itself.
 
    * Redirect: The buffer request is redirected to the root object of the
-     tree. Here, :c:expr:`view->obj` will be a new reference to the root
+     tree. Here, ``view->obj`` will be a new reference to the root
      object.
 
    The individual fields of *view* are described in section
@@ -3134,7 +3134,7 @@ Buffer Object Structures
    *view* argument.
 
 
-   This function MUST NOT decrement :c:expr:`view->obj`, since that is
+   This function MUST NOT decrement ``view->obj``, since that is
    done automatically in :c:func:`PyBuffer_Release` (this scheme is
    useful for breaking reference cycles).
 

_sources/c-api/weakref.rst.txt

@@ -42,8 +42,8 @@ as much as it can.
    callable object that receives notification when *ob* is garbage collected; it
    should accept a single parameter, which will be the weak reference object
    itself. *callback* may also be ``None`` or ``NULL``.  If *ob* is not a
-   weakly referenceable object, or if *callback* is not callable, ``None``, or
-   ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
+   weakly referenceable object, this will raise :exc:`TypeError` and return
+   ``NULL``.
 
    .. seealso::
       :c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly
@@ -58,8 +58,8 @@ as much as it can.
    be a callable object that receives notification when *ob* is garbage
    collected; it should accept a single parameter, which will be the weak
    reference object itself. *callback* may also be ``None`` or ``NULL``.  If *ob*
-   is not a weakly referenceable object, or if *callback* is not callable,
-   ``None``, or ``NULL``, this will return ``NULL`` and raise :exc:`TypeError`.
+   weakly referenceable object, this will raise :exc:`TypeError` and return
+   ``NULL``.
 
    .. seealso::
       :c:func:`PyType_SUPPORTS_WEAKREFS` for checking if *ob* is weakly

_sources/deprecations/pending-removal-in-3.15.rst.txt

@@ -33,16 +33,6 @@ Pending removal in Python 3.15
 
   * ``load_module()`` method: use ``exec_module()`` instead.
 
-* :class:`locale`:
-
-  * The :func:`~locale.getdefaultlocale` function
-    has been deprecated since Python 3.11.
-    Its removal was originally planned for Python 3.13 (:gh:`90817`),
-    but has been postponed to Python 3.15.
-    Use :func:`~locale.getlocale`, :func:`~locale.setlocale`,
-    and :func:`~locale.getencoding` instead.
-    (Contributed by Hugo van Kemenade in :gh:`111187`.)
-
 * :mod:`pathlib`:
 
   * :meth:`.PurePath.is_reserved`

_sources/library/argparse.rst.txt

@@ -442,9 +442,8 @@ is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
 
 .. note::
 
-   Empty lines are treated as empty strings (``''``), which are allowed as values but
-   not as arguments. Empty lines that are read as arguments will result in an
-   "unrecognized arguments" error.
+   Each line is treated as a single argument, so an empty line is read as an
+   empty string (``''``).
 
 :class:`ArgumentParser` uses :term:`filesystem encoding and error handler`
 to read the file containing arguments.
@@ -1048,6 +1047,10 @@ is used when no command-line argument was present::
    >>> parser.parse_args([])
    Namespace(foo=42)
 
+Because ``nargs='*'`` gathers any supplied values into a list, an absent
+positional argument yields an empty list (``[]``). Only a non-``None``
+*default* overrides this (so ``default=None`` still gives ``[]``).
+
 For required_ arguments, the ``default`` value is ignored. For example, this
 applies to positional arguments with nargs_ values other than ``?`` or ``*``,
 or optional arguments marked as ``required=True``.
@@ -1360,6 +1363,10 @@ behavior::
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')
 
+Multiple arguments may share the same ``dest``.  By default, the value from the
+last such argument given on the command line wins.  Use ``action='append'`` to
+collect values from all of them into a list instead.  For conflicting *option
+strings* rather than ``dest`` names, see conflict_handler_.
 
 .. _deprecated:
 
@@ -1755,6 +1762,11 @@ Subcommands
    present, and when the ``b`` command is specified, only the ``foo`` and
    ``baz`` attributes are present.
 
+   If a subparser defines an argument with the same ``dest`` as the parent
+   parser, the two share a single namespace attribute, so the parent's value
+   won't be retained. Users should give them  distinct ``dest`` values to
+   keep both.
+
    Similarly, when a help message is requested from a subparser, only the help
    for that particular parser will be printed.  The help message will not
    include parent parser or sibling parser messages.  (A help message for each
@@ -2199,6 +2211,9 @@ Customizing file parsing
         def convert_arg_line_to_args(self, arg_line):
             return arg_line.split()
 
+   Note that with this override an argument can no longer contain spaces, since
+   each space-separated word becomes a separate argument.
+
 
 Exiting methods
 ^^^^^^^^^^^^^^^

_sources/library/asyncio-threading.rst.txt

@@ -0,0 +1,154 @@
+.. currentmodule:: asyncio
+
+.. _asyncio-threading:
+
+asyncio and free-threaded Python
+================================
+
+asyncio uses an event loop as a scheduler to enable highly efficient
+concurrency by switching between tasks to allow non-blocking I/O
+operations. This results in better performance for I/O-bound use
+cases. It also allows off-loading CPU-bound work to a thread or
+process pool, but that is still limited by the :term:`global
+interpreter lock` in CPython.
+
+However, in :ref:`free-threaded Python <freethreading-python-howto>`,
+the GIL is disabled and Python can run true multi-threaded code. This
+means that asyncio can now take advantage of multiple CPU cores without
+the limitations imposed by the GIL.
+
+Since Python 3.14, asyncio has first-class support for free-threaded
+Python, and the implementation of asyncio is safe to use in a
+multi-threaded environment.
+
+A single event loop on one core can handle many connections
+concurrently, but the Python code that runs to handle each one still
+executes serially. Once requests involve a non-trivial amount of
+per-request computation, that handling becomes the bottleneck, and a
+single core can no longer keep up. Combining asyncio with threads is
+most useful here: by running an event loop per thread, the handling of
+different requests can run in parallel across multiple CPU cores. It is
+also useful when you need to run blocking or CPU-bound code from an
+asyncio application.
+
+
+.. seealso::
+
+   `Scaling asyncio on Free-Threaded Python
+   <https://labs.quansight.org/blog/scaling-asyncio-on-free-threaded-python>`__,
+   a blog post by Kumar Aditya which explains the internal changes
+   that make asyncio safe and efficient under free-threaded Python,
+   together with benchmarks of the resulting improvements.
+
+
+Thread safety considerations
+----------------------------
+
+While asyncio is designed to be thread-safe in a free-threaded Python
+environment, there are still some considerations to keep in mind when
+using asyncio with threads:
+
+1. **Event loop**: Each thread should have its own event loop which
+   should not be shared across threads. This ensures that the event loop
+   can manage its own tasks and callbacks without interference from
+   other threads.
+
+2. **Task management**: Tasks and futures created in one thread should
+   not be awaited or manipulated from another thread.
+
+3. **Thread-safe APIs**: When interacting with asyncio from multiple
+   threads, it's important to use thread-safe APIs provided by asyncio,
+   such as :func:`asyncio.run_coroutine_threadsafe` for submitting
+   coroutines to an event loop from another thread. If you need to
+   call a callback from a different thread, you can use
+   :meth:`loop.call_soon_threadsafe` to schedule it safely.
+
+4. **Synchronization**: The synchronization primitives provided by
+   asyncio (like :class:`asyncio.Lock` and :class:`asyncio.Event`)
+   are not designed to be used across threads. If you need to
+   synchronize between threads, you should use the synchronization
+   primitives from the :mod:`threading` module instead.
+
+
+Using asyncio with threads
+--------------------------
+
+asyncio supports running one event loop per thread, which allows you to
+take advantage of multiple CPU cores in a free-threaded Python
+environment. Each thread can run its own event loop, and tasks can be
+scheduled on those loops independently.
+
+Here's an example of how to use asyncio with threads::
+
+    import asyncio
+    import threading
+
+    async def worker(name: str) -> None:
+        print(f"Worker {name} starting")
+        await asyncio.sleep(1)
+        print(f"Worker {name} done")
+
+    def run_loop(name: str) -> None:
+        asyncio.run(worker(name))
+
+    threads = [
+        threading.Thread(target=run_loop, args=(f"T{i}",))
+        for i in range(4)
+    ]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+In this example, each thread creates its own event loop with
+:func:`asyncio.run` and runs a coroutine on it. The threads execute
+concurrently, and in a free-threaded build they can run on separate
+CPU cores in parallel.
+
+
+Producer/consumer across threads
+--------------------------------
+
+When a regular (non-asyncio) thread needs to hand work to an asyncio
+event loop running in another thread, use a thread-safe primitive such
+as :class:`queue.Queue` rather than :class:`asyncio.Queue`, which is
+only safe within a single event loop.::
+
+    import asyncio
+    import queue
+    import threading
+
+    def producer(q: queue.Queue[int]) -> None:
+        for i in range(5):
+            print(f"Producing {i}")
+            q.put(i)
+        q.shutdown()
+
+    async def consumer(q: queue.Queue[int]) -> None:
+        while True:
+            try:
+                item = q.get_nowait()
+            except queue.Empty:
+                await asyncio.sleep(0.1)
+                continue
+            except queue.ShutDown:
+                break
+            print(f"Consumed {item}")
+            await asyncio.sleep(item)
+
+    q: queue.Queue[int] = queue.Queue()
+    consumer_thread = threading.Thread(
+        target=lambda: asyncio.run(consumer(q))
+    )
+    consumer_thread.start()
+    producer(q)
+    consumer_thread.join()
+
+The producer runs on the main thread while the consumer runs inside an
+event loop on its own thread, yet they communicate safely through
+``queue.Queue``. When the queue is empty the consumer sleeps briefly
+and tries again. When the producer is done it calls
+:meth:`~queue.Queue.shutdown`, which causes subsequent
+:meth:`~queue.Queue.get_nowait` calls to raise :exc:`queue.ShutDown`
+so the consumer can exit cleanly.
+

_sources/library/asyncio.rst.txt

@@ -128,6 +128,7 @@ for full functionality and the latest features.
    asyncio-api-index.rst
    asyncio-llapi-index.rst
    asyncio-dev.rst
+   asyncio-threading.rst
 
 .. note::
    The source code for asyncio can be found in :source:`Lib/asyncio/`.

_sources/library/bisect.rst.txt

@@ -203,7 +203,7 @@ example uses :py:func:`~bisect.bisect` to look up a letter grade for an exam sco
 based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
 a 'B', and so on::
 
-   >>> def grade(score)
+   >>> def grade(score):
    ...     i = bisect([60, 70, 80, 90], score)
    ...     return "FDCBA"[i]
    ...

_sources/library/collections.abc.rst.txt

@@ -459,7 +459,7 @@ Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
    The :class:`Set` mixin provides a :meth:`!_hash` method to compute a hash value
    for the set; however, :meth:`~object.__hash__` is not defined because not all sets
    are :term:`hashable` or immutable.  To add set hashability using mixins,
-   inherit from both :meth:`Set` and :meth:`Hashable`, then define
+   inherit from both :class:`Set` and :class:`Hashable`, then define
    ``__hash__ = Set._hash``.
 
 .. seealso::