Deploying to gh-pages from @ d785c51 🚀

Author: mattwang44

_sources/c-api/exceptions.rst.txt

@@ -1235,6 +1235,16 @@ Glossary
       and ending with double underscores.  Special methods are documented in
       :ref:`specialnames`.
 
+   standard library
+      The collection of :term:`packages <package>`, :term:`modules <module>`
+      and :term:`extension modules <extension module>` distributed as a part
+      of the official Python interpreter package.  The exact membership of the
+      collection may vary based on platform, available system libraries, or
+      other criteria.  Documentation can be found at :ref:`library-index`.
+
+      See also :data:`sys.stdlib_module_names` for a list of all possible
+      standard library module names.
+
    statement
       A statement is part of a suite (a "block" of code).  A statement is either
       an :term:`expression` or one of several constructs with a keyword, such
@@ -1245,6 +1255,9 @@ Glossary
       issues such as incorrect types. See also :term:`type hints <type hint>`
       and the :mod:`typing` module.
 
+   stdlib
+      An abbreviation of :term:`standard library`.
+
    strong reference
       In Python's C API, a strong reference is a reference to an object
       which is owned by the code holding the reference.  The strong

_sources/glossary.rst.txt

@@ -4127,6 +4127,42 @@ The script, when run, prints something like:
     2025-07-02 13:54:47,234 DEBUG     fool me ...
     2025-07-02 13:54:47,234 DEBUG     can't get fooled again
 
+If, on the other hand, you are concerned about `log injection
+<https://owasp.org/www-community/attacks/Log_Injection>`_, you can use a
+formatter which escapes newlines, as per the following example:
+
+.. code-block:: python
+
+    import logging
+
+    logger = logging.getLogger(__name__)
+
+    class EscapingFormatter(logging.Formatter):
+        def format(self, record):
+            s = super().format(record)
+            return s.replace('\n', r'\n')
+
+    if __name__ == '__main__':
+        h = logging.StreamHandler()
+        h.setFormatter(EscapingFormatter('%(asctime)s %(levelname)-9s %(message)s'))
+        logging.basicConfig(level=logging.DEBUG, handlers = [h])
+        logger.debug('Single line')
+        logger.debug('Multiple lines:\nfool me once ...')
+        logger.debug('Another single line')
+        logger.debug('Multiple lines:\n%s', 'fool me ...\ncan\'t get fooled again')
+
+You can, of course, use whatever escaping scheme makes the most sense for you.
+The script, when run, should produce output like this:
+
+.. code-block:: text
+
+    2025-07-09 06:47:33,783 DEBUG     Single line
+    2025-07-09 06:47:33,783 DEBUG     Multiple lines:\nfool me once ...
+    2025-07-09 06:47:33,783 DEBUG     Another single line
+    2025-07-09 06:47:33,783 DEBUG     Multiple lines:\nfool me ...\ncan't get fooled again
+
+Escaping behaviour can't be the stdlib default , as it would break backwards
+compatibility.
 
 .. patterns-to-avoid:
 

_sources/howto/logging-cookbook.rst.txt

@@ -744,23 +744,11 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args(['--version'])
     PROG 2.0
 
-Only actions that consume command-line arguments (e.g. ``'store'``,
-``'append'`` or ``'extend'``) can be used with positional arguments.
-
-.. class:: BooleanOptionalAction
-
-   You may also specify an arbitrary action by passing an :class:`Action` subclass or
-   other object that implements the same interface. The :class:`!BooleanOptionalAction`
-   is available in :mod:`!argparse` and adds support for boolean actions such as
-   ``--foo`` and ``--no-foo``::
-
-       >>> import argparse
-       >>> parser = argparse.ArgumentParser()
-       >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
-       >>> parser.parse_args(['--no-foo'])
-       Namespace(foo=False)
-
-   .. versionadded:: 3.9
+You may also specify an arbitrary action by passing an :class:`Action` subclass
+(e.g. :class:`BooleanOptionalAction`) or other object that implements the same
+interface. Only actions that consume command-line arguments (e.g. ``'store'``,
+``'append'``, ``'extend'``, or custom actions with non-zero ``nargs``) can be used
+with positional arguments.
 
 The recommended way to create a custom action is to extend :class:`Action`,
 overriding the :meth:`!__call__` method and optionally the :meth:`!__init__` and
@@ -1337,6 +1325,21 @@ this API may be passed as the ``action`` parameter to
       and return a string which will be used when printing the usage of the program.
       If such method is not provided, a sensible default will be used.
 
+.. class:: BooleanOptionalAction
+
+   A subclass of :class:`Action` for handling boolean flags with positive
+   and negative options. Adding a single argument such as ``--foo`` automatically
+   creates both ``--foo`` and ``--no-foo`` options, storing ``True`` and ``False``
+   respectively::
+
+       >>> import argparse
+       >>> parser = argparse.ArgumentParser()
+       >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
+       >>> parser.parse_args(['--no-foo'])
+       Namespace(foo=False)
+
+   .. versionadded:: 3.9
+
 
 The parse_args() method
 -----------------------

_sources/library/argparse.rst.txt

@@ -239,8 +239,8 @@ wider range of codecs when working with binary files:
 .. function:: iterencode(iterator, encoding, errors='strict', **kwargs)
 
    Uses an incremental encoder to iteratively encode the input provided by
-   *iterator*. This function is a :term:`generator`.
-   The *errors* argument (as well as any
+   *iterator*. *iterator* must yield :class:`str` objects.
+   This function is a :term:`generator`. The *errors* argument (as well as any
    other keyword argument) is passed through to the incremental encoder.
 
    This function requires that the codec accept text :class:`str` objects
@@ -251,8 +251,8 @@ wider range of codecs when working with binary files:
 .. function:: iterdecode(iterator, encoding, errors='strict', **kwargs)
 
    Uses an incremental decoder to iteratively decode the input provided by
-   *iterator*. This function is a :term:`generator`.
-   The *errors* argument (as well as any
+   *iterator*. *iterator* must yield :class:`bytes` objects.
+   This function is a :term:`generator`. The *errors* argument (as well as any
    other keyword argument) is passed through to the incremental decoder.
 
    This function requires that the codec accept :class:`bytes` objects
@@ -261,6 +261,20 @@ wider range of codecs when working with binary files:
    :func:`iterencode`.
 
 
+.. function:: readbuffer_encode(buffer, errors=None, /)
+
+   Return a :class:`tuple` containing the raw bytes of *buffer*, a
+   :ref:`buffer-compatible object <bufferobjects>` or :class:`str`
+   (encoded to UTF-8 before processing), and their length in bytes.
+
+   The *errors* argument is ignored.
+
+   .. code-block:: pycon
+
+      >>> codecs.readbuffer_encode(b"Zito")
+      (b'Zito', 4)
+
+
 The module also provides the following constants which are useful for reading
 and writing to platform dependent files:
 
@@ -1473,6 +1487,54 @@ mapping. It is not supported by :meth:`str.encode` (which only produces
    Restoration of the ``rot13`` alias.
 
 
+:mod:`encodings` --- Encodings package
+--------------------------------------
+
+.. module:: encodings
+   :synopsis: Encodings package
+
+This module implements the following functions:
+
+.. function:: normalize_encoding(encoding)
+
+   Normalize encoding name *encoding*.
+
+   Normalization works as follows: all non-alphanumeric characters except the
+   dot used for Python package names are collapsed and replaced with a single
+   underscore, leading and trailing underscores are removed.
+   For example, ``'  -;#'`` becomes ``'_'``.
+
+   Note that *encoding* should be ASCII only.
+
+
+.. note::
+   The following function should not be used directly, except for testing
+   purposes; :func:`codecs.lookup` should be used instead.
+
+
+.. function:: search_function(encoding)
+
+   Search for the codec module corresponding to the given encoding name
+   *encoding*.
+
+   This function first normalizes the *encoding* using
+   :func:`normalize_encoding`, then looks for a corresponding alias.
+   It attempts to import a codec module from the encodings package using either
+   the alias or the normalized name. If the module is found and defines a valid
+   ``getregentry()`` function that returns a :class:`codecs.CodecInfo` object,
+   the codec is cached and returned.
+
+   If the codec module defines a ``getaliases()`` function any returned aliases
+   are registered for future use.
+
+
+This module implements the following exception:
+
+.. exception:: CodecRegistryError
+
+   Raised when a codec is invalid or incompatible.
+
+
 :mod:`encodings.idna` --- Internationalized Domain Names in Applications
 ------------------------------------------------------------------------
 

_sources/library/codecs.rst.txt

@@ -48,8 +48,8 @@ methods.
 FeedParser API
 ^^^^^^^^^^^^^^
 
-The :class:`BytesFeedParser`, imported from the :mod:`email.feedparser` module,
-provides an API that is conducive to incremental parsing of email messages,
+The :class:`BytesFeedParser`, imported from the :mod:`email.parser.FeedParser`
+module, provides an API that is conducive to incremental parsing of email messages,
 such as would be necessary when reading the text of an email message from a
 source that can block (such as a socket).  The :class:`BytesFeedParser` can of
 course be used to parse an email message fully contained in a :term:`bytes-like
@@ -116,7 +116,7 @@ Here is the API for the :class:`BytesFeedParser`:
    Works like :class:`BytesFeedParser` except that the input to the
    :meth:`~BytesFeedParser.feed` method must be a string.  This is of limited
    utility, since the only way for such a message to be valid is for it to
-   contain only ASCII text or, if :attr:`~email.policy.Policy.utf8` is
+   contain only ASCII text or, if :attr:`~email.policy.EmailPolicy.utf8` is
    ``True``, no binary attachments.
 
    .. versionchanged:: 3.3 Added the *policy* keyword.
@@ -155,11 +155,11 @@ message body, instead setting the payload to the raw body.
 
       Read all the data from the binary file-like object *fp*, parse the
       resulting bytes, and return the message object.  *fp* must support
-      both the :meth:`~io.IOBase.readline` and the :meth:`~io.IOBase.read`
+      both the :meth:`~io.IOBase.readline` and the :meth:`~io.TextIOBase.read`
       methods.
 
       The bytes contained in *fp* must be formatted as a block of :rfc:`5322`
-      (or, if :attr:`~email.policy.Policy.utf8` is ``True``, :rfc:`6532`)
+      (or, if :attr:`~email.policy.EmailPolicy.utf8` is ``True``, :rfc:`6532`)
       style headers and header continuation lines, optionally preceded by an
       envelope header.  The header block is terminated either by the end of the
       data or by a blank line.  Following the header block is the body of the

_sources/library/email.parser.rst.txt

@@ -204,18 +204,24 @@ The following exceptions are the exceptions that are usually raised.
    assignment fails.  (When an object does not support attribute references or
    attribute assignments at all, :exc:`TypeError` is raised.)
 
-   The :attr:`name` and :attr:`obj` attributes can be set using keyword-only
-   arguments to the constructor. When set they represent the name of the attribute
-   that was attempted to be accessed and the object that was accessed for said
-   attribute, respectively.
+   The optional *name* and *obj* keyword-only arguments
+   set the corresponding attributes:
+
+   .. attribute:: name
+
+      The name of the attribute that was attempted to be accessed.
+
+   .. attribute:: obj
+
+      The object that was accessed for the named attribute.
 
    .. versionchanged:: 3.10
       Added the :attr:`name` and :attr:`obj` attributes.
 
 .. exception:: EOFError
 
    Raised when the :func:`input` function hits an end-of-file condition (EOF)
-   without reading any data. (N.B.: the :meth:`io.IOBase.read` and
+   without reading any data. (Note: the :meth:`!io.IOBase.read` and
    :meth:`io.IOBase.readline` methods return an empty string when they hit EOF.)
 
 
@@ -312,9 +318,11 @@ The following exceptions are the exceptions that are usually raised.
    unqualified names.  The associated value is an error message that includes the
    name that could not be found.
 
-   The :attr:`name` attribute can be set using a keyword-only argument to the
-   constructor. When set it represent the name of the variable that was attempted
-   to be accessed.
+   The optional *name* keyword-only argument sets the attribute:
+
+   .. attribute:: name
+
+      The name of the variable that was attempted to be accessed.
 
    .. versionchanged:: 3.10
       Added the :attr:`name` attribute.
@@ -382,7 +390,7 @@ The following exceptions are the exceptions that are usually raised.
 
       The corresponding error message, as provided by
       the operating system.  It is formatted by the C
-      functions :c:func:`perror` under POSIX, and :c:func:`FormatMessage`
+      functions :c:func:`!perror` under POSIX, and :c:func:`!FormatMessage`
       under Windows.
 
    .. attribute:: filename
@@ -398,7 +406,7 @@ The following exceptions are the exceptions that are usually raised.
    .. versionchanged:: 3.3
       :exc:`EnvironmentError`, :exc:`IOError`, :exc:`WindowsError`,
       :exc:`socket.error`, :exc:`select.error` and
-      :exc:`mmap.error` have been merged into :exc:`OSError`, and the
+      :exc:`!mmap.error` have been merged into :exc:`OSError`, and the
       constructor may return a subclass.
 
    .. versionchanged:: 3.4
@@ -586,7 +594,7 @@ The following exceptions are the exceptions that are usually raised.
    handled, the Python interpreter exits; no stack traceback is printed.  The
    constructor accepts the same optional argument passed to :func:`sys.exit`.
    If the value is an integer, it specifies the system exit status (passed to
-   C's :c:func:`exit` function); if it is ``None``, the exit status is zero; if
+   C's :c:func:`!exit` function); if it is ``None``, the exit status is zero; if
    it has another type (such as a string), the object's value is printed and
    the exit status is one.
 

_sources/library/exceptions.rst.txt

@@ -298,9 +298,10 @@ the :mod:`glob` module.)
    device than *path*, or whether :file:`{path}/..` and *path* point to the same
    i-node on the same device --- this should detect mount points for all Unix
    and POSIX variants.  It is not able to reliably detect bind mounts on the
-   same filesystem.  On Windows, a drive letter root and a share UNC are
-   always mount points, and for any other path ``GetVolumePathName`` is called
-   to see if it is different from the input path.
+   same filesystem. On Linux systems, it will always return ``True`` for btrfs
+   subvolumes, even if they aren't mount points. On Windows, a drive letter root
+   and a share UNC are always mount points, and for any other path
+   ``GetVolumePathName`` is called to see if it is different from the input path.
 
    .. versionchanged:: 3.4
       Added support for detecting non-root mount points on Windows.

_sources/library/os.path.rst.txt

@@ -2307,7 +2307,7 @@ This section shows recipes for common adapters and converters.
 
    def adapt_datetime_iso(val):
        """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
-       return val.isoformat()
+       return val.replace(tzinfo=None).isoformat()
 
    def adapt_datetime_epoch(val):
        """Adapt datetime.datetime to Unix timestamp."""

_sources/library/sqlite3.rst.txt

@@ -306,10 +306,11 @@ Functions
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.5
-      The function is now always available and always system-wide.
+      The function is now always available and the clock is now the same for
+      all processes.
 
    .. versionchanged:: 3.10
-      On macOS, the function is now system-wide.
+      On macOS, the clock is now the same for all processes.
 
 
 .. function:: monotonic_ns() -> int
@@ -325,7 +326,8 @@ Functions
 
    Return the value (in fractional seconds) of a performance counter, i.e. a
    clock with the highest available resolution to measure a short duration.  It
-   does include time elapsed during sleep and is system-wide.  The reference
+   does include time elapsed during sleep. The clock is the same for all
+   processes. The reference
    point of the returned value is undefined, so that only the difference between
    the results of two calls is valid.
 
@@ -340,7 +342,7 @@ Functions
    .. versionadded:: 3.3
 
    .. versionchanged:: 3.10
-      On Windows, the function is now system-wide.
+      On Windows, the clock is now the same for all processes.
 
    .. versionchanged:: 3.13
       Use the same clock as :func:`time.monotonic`.
@@ -987,8 +989,8 @@ The following constant is the only parameter that can be sent to
 
 .. data:: CLOCK_REALTIME
 
-   System-wide real-time clock.  Setting this clock requires appropriate
-   privileges.
+   Real-time clock.  Setting this clock requires appropriate privileges.
+   The clock is the same for all processes.
 
    .. availability:: Unix.