Deploying to gh-pages from @ 71ca89d 🚀

Author: mattwang44

_sources/c-api/hash.rst.txt

@@ -51,7 +51,7 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 
    Hash function definition used by :c:func:`PyHash_GetFuncDef`.
 
-   .. c::member:: Py_hash_t (*const hash)(const void *, Py_ssize_t)
+   .. c:member:: Py_hash_t (*const hash)(const void *, Py_ssize_t)
 
       Hash function.
 

_sources/c-api/init.rst.txt

@@ -1184,6 +1184,12 @@ code, or when embedding the Python interpreter:
    interpreter lock is also shared by all threads, regardless of to which
    interpreter they belong.
 
+   .. versionchanged:: 3.12
+
+      :pep:`684` introduced the possibility
+      of a :ref:`per-interpreter GIL <per-interpreter-gil>`.
+      See :c:func:`Py_NewInterpreterFromConfig`.
+
 
 .. c:type:: PyThreadState
 
@@ -1875,6 +1881,8 @@ function. You can create and destroy them using the following functions:
    haven't been explicitly destroyed at that point.
 
 
+.. _per-interpreter-gil:
+
 A Per-Interpreter GIL
 ---------------------
 
@@ -1886,7 +1894,7 @@ being blocked by other interpreters or blocking any others.  Thus a
 single Python process can truly take advantage of multiple CPU cores
 when running Python code.  The isolation also encourages a different
 approach to concurrency than that of just using threads.
-(See :pep:`554`.)
+(See :pep:`554` and :pep:`684`.)
 
 Using an isolated interpreter requires vigilance in preserving that
 isolation.  That especially means not sharing any objects or mutable

_sources/c-api/long.rst.txt

@@ -40,9 +40,11 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
 
    Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure.
 
-   The current implementation keeps an array of integer objects for all integers
-   between ``-5`` and ``256``. When you create an int in that range you actually
-   just get back a reference to the existing object.
+   .. impl-detail::
+
+      CPython keeps an array of integer objects for all integers
+      between ``-5`` and ``256``.  When you create an int in that range
+      you actually just get back a reference to the existing object.
 
 
 .. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
@@ -372,6 +374,10 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    Set *\*value* to a signed C :c:expr:`int32_t` or :c:expr:`int64_t`
    representation of *obj*.
 
+   If *obj* is not an instance of :c:type:`PyLongObject`, first call its
+   :meth:`~object.__index__` method (if present) to convert it to a
+   :c:type:`PyLongObject`.
+
    If the *obj* value is out of range, raise an :exc:`OverflowError`.
 
    Set *\*value* and return ``0`` on success.

_sources/deprecations/c-api-pending-removal-in-3.18.rst.txt

@@ -1,11 +1,12 @@
 Pending removal in Python 3.18
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* Deprecated private functions (:gh:`128863`):
+* The following private functions are deprecated
+  and planned for removal in Python 3.18:
 
   * :c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`.
   * :c:func:`!_PyDict_GetItemStringWithError`: use :c:func:`PyDict_GetItemStringRef`.
-  * :c:func:`!_PyDict_Pop()`: :c:func:`PyDict_Pop`.
+  * :c:func:`!_PyDict_Pop()`: use :c:func:`PyDict_Pop`.
   * :c:func:`!_PyLong_Sign()`: use :c:func:`PyLong_GetSign`.
   * :c:func:`!_PyLong_FromDigits` and :c:func:`!_PyLong_New`:
     use :c:func:`PyLongWriter_Create`.
@@ -31,7 +32,7 @@ Pending removal in Python 3.18
     :c:func:`PyUnicodeWriter_WriteSubstring(writer, str, start, end) <PyUnicodeWriter_WriteSubstring>`.
   * :c:func:`!_PyUnicodeWriter_WriteASCIIString`:
     replace ``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` with
-    :c:func:`PyUnicodeWriter_WriteUTF8(writer, str) <PyUnicodeWriter_WriteUTF8>`.
+    :c:func:`PyUnicodeWriter_WriteASCII(writer, str) <PyUnicodeWriter_WriteASCII>`.
   * :c:func:`!_PyUnicodeWriter_WriteLatin1String`:
     replace ``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` with
     :c:func:`PyUnicodeWriter_WriteUTF8(writer, str) <PyUnicodeWriter_WriteUTF8>`.
@@ -41,5 +42,6 @@ Pending removal in Python 3.18
   * :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.
 
   The `pythoncapi-compat project
-  <https://github.com/python/pythoncapi-compat/>`__ can be used to get these
-  new public functions on Python 3.13 and older.
+  <https://github.com/python/pythoncapi-compat/>`__ can be used to get
+  these new public functions on Python 3.13 and older.
+  (Contributed by Victor Stinner in :gh:`128863`.)

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

@@ -38,12 +38,6 @@ Pending removal in Python 3.14
     is no current event loop set and it decides to create one.
     (Contributed by Serhiy Storchaka and Guido van Rossum in :gh:`100160`.)
 
-* :mod:`collections.abc`: Deprecated :class:`!collections.abc.ByteString`.
-  Prefer :class:`!Sequence` or :class:`~collections.abc.Buffer`.
-  For use in typing, prefer a union, like ``bytes | bytearray``,
-  or :class:`collections.abc.Buffer`.
-  (Contributed by Shantanu Jain in :gh:`91896`.)
-
 * :mod:`email`: Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
   (Contributed by Alan Williams in :gh:`72346`.)
 
@@ -96,9 +90,6 @@ Pending removal in Python 3.14
     if :ref:`named placeholders <sqlite3-placeholders>` are used and
     *parameters* is a sequence instead of a :class:`dict`.
 
-* :mod:`typing`: :class:`!typing.ByteString`, deprecated since Python 3.9,
-  now causes a :exc:`DeprecationWarning` to be emitted when it is used.
-
 * :mod:`urllib`:
   :class:`!urllib.parse.Quoter` is deprecated: it was not intended to be a
   public API.

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

@@ -8,3 +8,15 @@ Pending removal in Python 3.17
     but it has been retained for backward compatibility, with removal scheduled for Python
     3.17. Users should use documented introspection helpers like :func:`typing.get_origin`
     and :func:`typing.get_args` instead of relying on private implementation details.
+  - :class:`typing.ByteString`, deprecated since Python 3.9, is scheduled for removal in
+    Python 3.17. Prefer :class:`~collections.abc.Sequence` or
+    :class:`~collections.abc.Buffer`. For use in type annotations, prefer a union, like
+    ``bytes | bytearray``, or :class:`collections.abc.Buffer`.
+    (Contributed by Shantanu Jain in :gh:`91896`.)
+
+* :mod:`collections.abc`:
+
+  - :class:`collections.abc.ByteString` is scheduled for removal in Python 3.17. Prefer
+    :class:`~collections.abc.Sequence` or :class:`~collections.abc.Buffer`. For use in
+    type annotations, prefer a union, like ``bytes | bytearray``, or
+    :class:`collections.abc.Buffer`. (Contributed by Shantanu Jain in :gh:`91896`.)

_sources/extending/extending.rst.txt

@@ -214,7 +214,7 @@ and initialize it by calling :c:func:`PyErr_NewException` in the module's
 
    SpamError = PyErr_NewException("spam.error", NULL, NULL);
 
-Since :c:data:`!SpamError` is a global variable, it will be overwitten every time
+Since :c:data:`!SpamError` is a global variable, it will be overwritten every time
 the module is reinitialized, when the :c:data:`Py_mod_exec` function is called.
 
 For now, let's avoid the issue: we will block repeated initialization by raising an

_sources/glossary.rst.txt

@@ -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

_sources/howto/enum.rst.txt

@@ -990,9 +990,9 @@ Supported ``_sunder_`` names
   from the final class
 - :meth:`~Enum._generate_next_value_` -- used to get an appropriate value for
   an enum member; may be overridden
-- :meth:`~EnumType._add_alias_` -- adds a new name as an alias to an existing
+- :meth:`~Enum._add_alias_` -- adds a new name as an alias to an existing
   member.
-- :meth:`~EnumType._add_value_alias_` -- adds a new value as an alias to an
+- :meth:`~Enum._add_value_alias_` -- adds a new value as an alias to an
   existing member.  See `MultiValueEnum`_ for an example.
 
   .. note::

_sources/howto/remote_debugging.rst.txt

@@ -3,6 +3,78 @@
 Remote debugging attachment protocol
 ====================================
 
+This protocol enables external tools to attach to a running CPython process and
+execute Python code remotely.
+
+Most platforms require elevated privileges to attach to another Python process.
+
+.. _permission-requirements:
+
+Permission requirements
+=======================
+
+Attaching to a running Python process for remote debugging requires elevated
+privileges on most platforms. The specific requirements and troubleshooting
+steps depend on your operating system:
+
+.. rubric:: Linux
+
+The tracer process must have the ``CAP_SYS_PTRACE`` capability or equivalent
+privileges. You can only trace processes you own and can signal. Tracing may
+fail if the process is already being traced, or if it is running with
+set-user-ID or set-group-ID. Security modules like Yama may further restrict
+tracing.
+
+To temporarily relax ptrace restrictions (until reboot), run:
+
+  ``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope``
+
+.. note::
+
+   Disabling ``ptrace_scope`` reduces system hardening and should only be done
+   in trusted environments.
+
+If running inside a container, use ``--cap-add=SYS_PTRACE`` or
+``--privileged``, and run as root if needed.
+
+Try re-running the command with elevated privileges:
+
+  ``sudo -E !!``
+
+
+.. rubric:: macOS
+
+To attach to another process, you typically need to run your debugging tool
+with elevated privileges. This can be done by using ``sudo`` or running as
+root.
+
+Even when attaching to processes you own, macOS may block debugging unless
+the debugger is run with root privileges due to system security restrictions.
+
+
+.. rubric:: Windows
+
+To attach to another process, you usually need to run your debugging tool
+with administrative privileges. Start the command prompt or terminal as
+Administrator.
+
+Some processes may still be inaccessible even with Administrator rights,
+unless you have the ``SeDebugPrivilege`` privilege enabled.
+
+To resolve file or folder access issues, adjust the security permissions:
+
+  1. Right-click the file or folder and select **Properties**.
+  2. Go to the **Security** tab to view users and groups with access.
+  3. Click **Edit** to modify permissions.
+  4. Select your user account.
+  5. In **Permissions**, check **Read** or **Full control** as needed.
+  6. Click **Apply**, then **OK** to confirm.
+
+
+.. note::
+
+   Ensure you've satisfied all :ref:`permission-requirements` before proceeding.
+
 This section describes the low-level protocol that enables external tools to
 inject and execute a Python script within a running CPython process.
 
@@ -374,13 +446,13 @@ To locate a thread:
    reliable thread to target.
 
 3. Optionally, use the offset ``interpreter_state.threads_head`` to iterate
-through the linked list of all thread states. Each ``PyThreadState`` structure
-contains a ``native_thread_id`` field, which may be compared to a target thread
-ID to find a specific thread.
+   through the linked list of all thread states. Each ``PyThreadState``
+   structure contains a ``native_thread_id`` field, which may be compared to
+   a target thread ID to find a specific thread.
 
-1. Once a valid ``PyThreadState`` has been found, its address can be used in
-later steps of the protocol, such as writing debugger control fields and
-scheduling execution.
+4. Once a valid ``PyThreadState`` has been found, its address can be used in
+   later steps of the protocol, such as writing debugger control fields and
+   scheduling execution.
 
 The following is an example implementation that locates the main thread state::
 
@@ -454,15 +526,15 @@ its fields are defined by the ``_Py_DebugOffsets`` structure and include the
 following:
 
 - ``debugger_script_path``: A fixed-size buffer that holds the full path to a
-   Python source file (``.py``).  This file must be accessible and readable by
-   the target process when execution is triggered.
+  Python source file (``.py``).  This file must be accessible and readable by
+  the target process when execution is triggered.
 
 - ``debugger_pending_call``: An integer flag. Setting this to ``1`` tells the
-   interpreter that a script is ready to be executed.
+  interpreter that a script is ready to be executed.
 
 - ``eval_breaker``: A field checked by the interpreter during execution.
-   Setting bit 5 (``_PY_EVAL_PLEASE_STOP_BIT``, value ``1U << 5``) in this
-   field causes the interpreter to pause and check for debugger activity.
+  Setting bit 5 (``_PY_EVAL_PLEASE_STOP_BIT``, value ``1U << 5``) in this
+  field causes the interpreter to pause and check for debugger activity.
 
 To complete the injection, the debugger must perform the following steps: