Deploying to gh-pages from @ 7cf33e8 🚀

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: ed20a0ffdb2c79674424722536501fd3
+config: de39b7ffcd4cf530c39bb29a68f8fdc6
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/c-api/init.rst.txt

@@ -1218,7 +1218,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
 .. c:function:: void PyThreadState_DeleteCurrent(void)
 
    Destroy the current thread state and release the global interpreter lock.
-   Like :c:func:`PyThreadState_Delete`, the global interpreter lock need not
+   Like :c:func:`PyThreadState_Delete`, the global interpreter lock must
    be held. The thread state must have been reset with a previous call
    to :c:func:`PyThreadState_Clear`.
 

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

@@ -0,0 +1,154 @@
+.. _freethreading-python-howto:
+
+**********************************************
+Python experimental support for free threading
+**********************************************
+
+Starting with the 3.13 release, CPython has experimental support for a build of
+Python called :term:`free threading` where the :term:`global interpreter lock`
+(GIL) is disabled.  Free-threaded execution allows for full utilization of the
+available processing power by running threads in parallel on available CPU cores.
+While not all software will benefit from this automatically, programs
+designed with threading in mind will run faster on multi-core hardware.
+
+**The free-threaded mode is experimental** and work is ongoing to improve it:
+expect some bugs and a substantial single-threaded performance hit.
+
+This document describes the implications of free threading
+for Python code.  See :ref:`freethreading-extensions-howto` for information on
+how to write C extensions that support the free-threaded build.
+
+.. seealso::
+
+   :pep:`703` – Making the Global Interpreter Lock Optional in CPython for an
+   overall description of free-threaded Python.
+
+
+Installation
+============
+
+Starting with Python 3.13, the official macOS and Windows installers
+optionally support installing free-threaded Python binaries.  The installers
+are available at https://www.python.org/downloads/.
+
+For information on other platforms, see the `Installing a Free-Threaded Python
+<https://py-free-threading.github.io/installing_cpython/>`_, a
+community-maintained installation guide for installing free-threaded Python.
+
+When building CPython from source, the :option:`--disable-gil` configure option
+should be used to build a free-threaded Python interpreter.
+
+
+Identifying free-threaded Python
+================================
+
+To check if the current interpreter supports free-threading, :option:`python -VV <-V>`
+and :attr:`sys.version` contain "experimental free-threading build".
+The new :func:`sys._is_gil_enabled` function can be used to check whether
+the GIL is actually disabled in the running process.
+
+The ``sysconfig.get_config_var("Py_GIL_DISABLED")`` configuration variable can
+be used to determine whether the build supports free threading.  If the variable
+is set to ``1``, then the build supports free threading.  This is the recommended
+mechanism for decisions related to the build configuration.
+
+
+The global interpreter lock in free-threaded Python
+===================================================
+
+Free-threaded builds of CPython support optionally running with the GIL enabled
+at runtime using the environment variable :envvar:`PYTHON_GIL` or
+the command-line option :option:`-X gil`.
+
+The GIL may also automatically be enabled when importing a C-API extension
+module that is not explicitly marked as supporting free threading.  A warning
+will be printed in this case.
+
+In addition to individual package documentation, the following websites track
+the status of popular packages support for free threading:
+
+* https://py-free-threading.github.io/tracking/
+* https://hugovk.github.io/free-threaded-wheels/
+
+
+Thread safety
+=============
+
+The free-threaded build of CPython aims to provide similar thread-safety
+behavior at the Python level to the default GIL-enabled build.  Built-in
+types like :class:`dict`, :class:`list`, and :class:`set` use internal locks
+to protect against concurrent modifications in ways that behave similarly to
+the GIL.  However, Python has not historically guaranteed specific behavior for
+concurrent modifications to these built-in types, so this should be treated
+as a description of the current implementation, not a guarantee of current or
+future behavior.
+
+.. note::
+
+   It's recommended to use the :class:`threading.Lock` or other synchronization
+   primitives instead of relying on the internal locks of built-in types, when
+   possible.
+
+
+Known limitations
+=================
+
+This section describes known limitations of the free-threaded CPython build.
+
+Immortalization
+---------------
+
+The free-threaded build of the 3.13 release makes some objects :term:`immortal`.
+Immortal objects are not deallocated and have reference counts that are
+never modified.  This is done to avoid reference count contention that would
+prevent efficient multi-threaded scaling.
+
+An object will be made immortal when a new thread is started for the first time
+after the main thread is running.  The following objects are immortalized:
+
+* :ref:`function <user-defined-funcs>` objects declared at the module level
+* :ref:`method <instance-methods>` descriptors
+* :ref:`code <code-objects>` objects
+* :term:`module` objects and their dictionaries
+* :ref:`classes <classes>` (type objects)
+
+Because immortal objects are never deallocated, applications that create many
+objects of these types may see increased memory usage.  This is expected to be
+addressed in the 3.14 release.
+
+Additionally, numeric and string literals in the code as well as strings
+returned by :func:`sys.intern` are also immortalized.  This behavior is
+expected to remain in the 3.14 free-threaded build.
+
+
+Frame objects
+-------------
+
+It is not safe to access :ref:`frame <frame-objects>` objects from other
+threads and doing so may cause your program to crash .  This means that
+:func:`sys._current_frames` is generally not safe to use in a free-threaded
+build.  Functions like :func:`inspect.currentframe` and :func:`sys._getframe`
+are generally safe as long as the resulting frame object is not passed to
+another thread.
+
+Iterators
+---------
+
+Sharing the same iterator object between multiple threads is generally not
+safe and threads may see duplicate or missing elements when iterating or crash
+the interpreter.
+
+
+Single-threaded performance
+---------------------------
+
+The free-threaded build has additional overhead when executing Python code
+compared to the default GIL-enabled build.  In 3.13, this overhead is about
+40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite.
+Programs that spend most of their time in C extensions or I/O will see
+less of an impact.  The largest impact is because the specializing adaptive
+interpreter (:pep:`659`) is disabled in the free-threaded build.  We expect
+to re-enable it in a thread-safe way in the 3.14 release.  This overhead is
+expected to be reduced in upcoming Python release.   We are aiming for an
+overhead of 10% or less on the pyperformance suite compared to the default
+GIL-enabled build.

_sources/howto/index.rst.txt

@@ -32,6 +32,7 @@ Python Library Reference.
    isolating-extensions.rst
    timerfd.rst
    mro.rst
+   free-threading-python.rst
    free-threading-extensions.rst
 
 General:
@@ -52,6 +53,7 @@ General:
 Advanced development:
 
 * :ref:`curses-howto`
+* :ref:`freethreading-python-howto`
 * :ref:`freethreading-extensions-howto`
 * :ref:`isolating-extensions-howto`
 * :ref:`python_2.3_mro`

_sources/library/datetime.rst.txt

@@ -295,6 +295,20 @@ Instance attributes (read-only):
 
    Between 0 and 86,399 inclusive.
 
+   .. caution::
+
+      It is a somewhat common bug for code to unintentionally use this attribute
+      when it is actually intended to get a :meth:`~timedelta.total_seconds`
+      value instead:
+
+      .. doctest::
+
+         >>> from datetime import timedelta
+         >>> duration = timedelta(seconds=11235813)
+         >>> duration.days, duration.seconds
+         (130, 3813)
+         >>> duration.total_seconds()
+         11235813.0
 
 .. attribute:: timedelta.microseconds
 
@@ -351,7 +365,7 @@ Supported operations:
 |                                | same value. (2)                               |
 +--------------------------------+-----------------------------------------------+
 | ``-t1``                        | Equivalent to ``timedelta(-t1.days,           |
-|                                | -t1.seconds*, -t1.microseconds)``,            |
+|                                | -t1.seconds, -t1.microseconds)``,             |
 |                                | and to ``t1 * -1``. (1)(4)                    |
 +--------------------------------+-----------------------------------------------+
 | ``abs(t)``                     | Equivalent to ``+t`` when ``t.days >= 0``,    |

_sources/library/gc.rst.txt

@@ -40,18 +40,11 @@ The :mod:`gc` module provides the following functions:
 
 .. function:: collect(generation=2)
 
-   Perform a collection.  The optional argument *generation*
+   With no arguments, run a full collection.  The optional argument *generation*
    may be an integer specifying which generation to collect (from 0 to 2).  A
    :exc:`ValueError` is raised if the generation number is invalid. The sum of
    collected objects and uncollectable objects is returned.
 
-   Calling ``gc.collect(0)`` will perform a GC collection on the young generation.
-
-   Calling ``gc.collect(1)`` will perform a GC collection on the young generation
-   and an increment of the old generation.
-
-   Calling ``gc.collect(2)`` or ``gc.collect()`` performs a full collection
-
    The free lists maintained for a number of built-in types are cleared
    whenever a full collection or collection of the highest generation (2)
    is run.  Not all items in some free lists may be freed due to the
@@ -60,9 +53,6 @@ The :mod:`gc` module provides the following functions:
    The effect of calling ``gc.collect()`` while the interpreter is already
    performing a collection is undefined.
 
-   .. versionchanged:: 3.13
-      ``generation=1`` performs an increment of collection.
-
 
 .. function:: set_debug(flags)
 
@@ -78,20 +68,13 @@ The :mod:`gc` module provides the following functions:
 
 .. function:: get_objects(generation=None)
 
-
    Returns a list of all objects tracked by the collector, excluding the list
-   returned. If *generation* is not ``None``, return only the objects as follows:
-
-   * 0: All objects in the young generation
-   * 1: No objects, as there is no generation 1 (as of Python 3.13)
-   * 2: All objects in the old generation
+   returned. If *generation* is not ``None``, return only the objects tracked by
+   the collector that are in that generation.
 
    .. versionchanged:: 3.8
       New *generation* parameter.
 
-   .. versionchanged:: 3.13
-      Generation 1 is removed
-
    .. audit-event:: gc.get_objects generation gc.get_objects
 
 .. function:: get_stats()
@@ -118,27 +101,19 @@ The :mod:`gc` module provides the following functions:
    Set the garbage collection thresholds (the collection frequency). Setting
    *threshold0* to zero disables collection.
 
-   The GC classifies objects into two generations depending on whether they have
-   survived a collection. New objects are placed in the young generation. If an
-   object survives a collection it is moved into the old generation.
-
-   In order to decide when to run, the collector keeps track of the number of object
+   The GC classifies objects into three generations depending on how many
+   collection sweeps they have survived.  New objects are placed in the youngest
+   generation (generation ``0``).  If an object survives a collection it is moved
+   into the next older generation.  Since generation ``2`` is the oldest
+   generation, objects in that generation remain there after a collection.  In
+   order to decide when to run, the collector keeps track of the number object
    allocations and deallocations since the last collection.  When the number of
    allocations minus the number of deallocations exceeds *threshold0*, collection
-   starts. For each collection, all the objects in the young generation and some
-   fraction of the old generation is collected.
-
-   The fraction of the old generation that is collected is **inversely** proportional
-   to *threshold1*. The larger *threshold1* is, the slower objects in the old generation
-   are collected.
-   For the default value of 10, 1% of the old generation is scanned during each collection.
-
-   *threshold2* is ignored.
-
-   See `Garbage collector design <https://devguide.python.org/garbage_collector>`_ for more information.
-
-   .. versionchanged:: 3.13
-      *threshold2* is ignored
+   starts.  Initially only generation ``0`` is examined.  If generation ``0`` has
+   been examined more than *threshold1* times since generation ``1`` has been
+   examined, then generation ``1`` is examined as well.
+   With the third generation, things are a bit more complicated,
+   see `Collecting the oldest generation <https://devguide.python.org/garbage_collector/#collecting-the-oldest-generation>`_ for more information.
 
 
 .. function:: get_count()

_sources/reference/datamodel.rst.txt

@@ -831,6 +831,7 @@ this case, the special read-only attribute :attr:`!__self__` is set to the objec
 denoted by *alist*. (The attribute has the same semantics as it does with
 :attr:`other instance methods <method.__self__>`.)
 
+.. _classes:
 
 Classes
 ^^^^^^^