diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4d9e73db48ae57..d12eaee2adb396 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -630,7 +630,7 @@ Lib/test/test_unittest/testmock/ @cjw296 Doc/library/zlib.rst @StanFromIreland Lib/compression/zlib.py @StanFromIreland Lib/test/test_zlib.py @StanFromIreland -Modules/_zlibmodule.c @StanFromIreland +Modules/zlibmodule.c @StanFromIreland # Zipfile.Path Lib/test/test_zipfile/_path/ @jaraco diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 199e0fd8d181f0..c7f7663e3162ba 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -86,6 +86,9 @@ jobs: --fail-if-regression \ --fail-if-improved \ --fail-if-new-news-nit + - name: 'Build list of changes' + run: | + make -C Doc/ PYTHON=../python changes - name: 'Collect HTML IDs' if: github.event_name == 'pull_request' run: python Doc/tools/check-html-ids.py collect Doc/build/html -o Doc/build/html-ids-head.json.gz diff --git a/Doc/library/constants.rst b/Doc/builtins/constants.rst similarity index 100% rename from Doc/library/constants.rst rename to Doc/builtins/constants.rst diff --git a/Doc/library/exceptions.rst b/Doc/builtins/exceptions.rst similarity index 100% rename from Doc/library/exceptions.rst rename to Doc/builtins/exceptions.rst diff --git a/Doc/library/functions.rst b/Doc/builtins/functions.rst similarity index 100% rename from Doc/library/functions.rst rename to Doc/builtins/functions.rst diff --git a/Doc/builtins/index.rst b/Doc/builtins/index.rst new file mode 100644 index 00000000000000..17aab32200d976 --- /dev/null +++ b/Doc/builtins/index.rst @@ -0,0 +1,35 @@ +.. _builtins-index: + +############################## + Python built-ins reference +############################## + +Python comes with a number of built-in functions and classes. + +The built-in classes include data types that would normally be considered part +of the "core" of a language, such as numbers and lists. For these types, the +Python language core defines the form of literals and places some constraints +on their semantics, but does not fully define the semantics. + +The built-ins also include functions and exceptions --- objects that can +be used by all Python code without the need of an :keyword:`import` statement. +Some of these are defined by the core language, but many are not essential for +the core semantics and are only described here. + +.. seealso:: + + In addition to the built-ins, Python provides an extensive importable + standard library, see :ref:`library-index`. + +.. We don't use :numbered: option for the TOC below as it enforces + numbered sections for the entire builtin docs. If desired, + :numbered: can be enabled on a per-page basis. +.. toctree:: + :maxdepth: 2 + + stdtypes.rst + constants.rst + functions.rst + exceptions.rst + threadsafety.rst + time-complexity.rst diff --git a/Doc/library/stdtypes.rst b/Doc/builtins/stdtypes.rst similarity index 100% rename from Doc/library/stdtypes.rst rename to Doc/builtins/stdtypes.rst diff --git a/Doc/library/threadsafety.rst b/Doc/builtins/threadsafety.rst similarity index 100% rename from Doc/library/threadsafety.rst rename to Doc/builtins/threadsafety.rst diff --git a/Doc/library/time-complexity.rst b/Doc/builtins/time-complexity.rst similarity index 100% rename from Doc/library/time-complexity.rst rename to Doc/builtins/time-complexity.rst diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst index ff68ecafcda4d0..60a90b3f096912 100644 --- a/Doc/c-api/bytes.rst +++ b/Doc/c-api/bytes.rst @@ -231,6 +231,7 @@ called with a non-bytes parameter. Resize a bytes object. *newsize* will be the new length of the bytes object. You can think of it as creating a new bytes object and destroying the old one, only more efficiently. + Pass the address of an existing bytes object as an lvalue (it may be written into), and the new size desired. On success, *\*bytes* holds the resized bytes object and ``0`` is @@ -239,6 +240,11 @@ called with a non-bytes parameter. *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is returned. + While bytes objects are usually immutable in Python, this special C API + allows mutating a bytes object in-place. The returned bytes object can still + be mutated using :c:func:`PyBytesWriter_GetData`; except if *newsize* is + zero in which case it returns the immutable empty bytes string. + .. soft-deprecated:: 3.15 Use the :c:type:`PyBytesWriter` API instead. @@ -290,10 +296,10 @@ object. .. c:type:: PyBytesWriter - A bytes writer instance. + A bytes writer object. - The API is **not thread safe**: a writer should only be used by a single - thread at the same time. + The API is **not thread safe**. A :c:type:`PyBytesWriter` object must only + be used by a single thread, it must not be shared between threads. The instance must be destroyed by :c:func:`PyBytesWriter_Finish` on success, or :c:func:`PyBytesWriter_Discard` on error. @@ -429,7 +435,7 @@ Low-level API On success, return ``0``. On error, set an exception and return ``-1``. - *size* can be negative to shrink the writer. + *grow* can be negative to shrink the writer. .. c:function:: void* PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf) diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst index 10f96c7cb75e88..7a11e6c8a7a13b 100644 --- a/Doc/c-api/complex.rst +++ b/Doc/c-api/complex.rst @@ -197,3 +197,6 @@ the :ref:`Number Protocol ` API or use native complex types, like Set :c:data:`errno` to :c:macro:`!ERANGE` on overflows. .. deprecated:: 3.15 + + .. versionchanged:: next + This function leaves :c:data:`errno` unchanged on success. diff --git a/Doc/conf.py b/Doc/conf.py index c768e6fd676a5a..f803fb1ff44bef 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -44,6 +44,7 @@ 'sphinx_linklint.ext', 'notfound.extension', 'sphinxext.opengraph', + 'sphinxext.rediraffe', 'sphinxcontrib.rsvgconverter', ) for optional_ext in _OPTIONAL_EXTENSIONS: @@ -359,7 +360,13 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ - ('c-api/index', 'c-api.tex', 'The Python/C API', _doc_authors, 'manual'), + ( + 'c-api/index', + 'c-api.tex', + 'The Python/C API', + _doc_authors, + 'manual', + ), ( 'extending/index', 'extending.tex', @@ -374,6 +381,13 @@ _doc_authors, 'manual', ), + ( + 'builtins/index', + 'builtins.tex', + 'Python Built-ins Reference', + _doc_authors, + 'manual', + ), ( 'library/index', 'library.tex', @@ -606,3 +620,16 @@ '', '', ) + +# Options for sphinxext-rediraffe +# ------------------------------- + +rediraffe_redirects = { + # Splitting builtins from library + "library/functions.rst": "builtins/functions.rst", + "library/stdtypes.rst": "builtins/stdtypes.rst", + "library/constants.rst": "builtins/constants.rst", + "library/exceptions.rst": "builtins/exceptions.rst", + "library/threadsafety.rst": "builtins/threadsafety.rst", + "library/time-complexity.rst": "builtins/time-complexity.rst", +} diff --git a/Doc/contents.rst b/Doc/contents.rst index b57f4b09a5dcb6..852be4a6d5b6ba 100644 --- a/Doc/contents.rst +++ b/Doc/contents.rst @@ -8,6 +8,7 @@ tutorial/index.rst using/index.rst reference/index.rst + builtins/index.rst library/index.rst extending/index.rst c-api/index.rst diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst index c0c494c3059d99..0f0686ea40e75b 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -16,9 +16,10 @@ underlying operating system supports this feature. This document assumes basic knowledge about C and Python. For an informal introduction to Python, see :ref:`tutorial-index`. :ref:`reference-index` -gives a more formal definition of the language. :ref:`library-index` documents -the existing object types, functions and modules (both built-in and written in -Python) that give the language its wide application range. +gives a more formal definition of the language. :ref:`builtins-index` documents +the built-in functions and object types, and :ref:`library-index` documents the +modules (both built-in and written in Python) that give the language its wide +application range. For a detailed description of the whole Python/C API, see the separate :ref:`c-api-index`. diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst index 6c20e9c94a3eae..d5f367d2d19e90 100644 --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -307,6 +307,36 @@ One-shot (de)compression .. versionchanged:: 3.3 Support for multi-stream inputs was added. + +Miscellaneous +------------- + +Information about the version of the bzip2 compression library +actually loaded by the interpreter is available through the following +constants. +The version used for building the module is not available, +because the bzip2 library does not provide it. + + +.. data:: bzlib_version + + The version string of the bzip2 compression library + actually loaded by the interpreter. + + .. versionadded:: next + + +.. data:: bzlib_version_info + + A named tuple containing the three components of the bzip2 compression + library version actually loaded by the interpreter: + *major*, *minor*, and *patch*. All values are integers. + The components can also be accessed by name, so ``bz2.bzlib_version_info[0]`` + is equivalent to ``bz2.bzlib_version_info.major`` and so on. + + .. versionadded:: next + + .. _bz2-usage-examples: Examples of usage diff --git a/Doc/library/colorsys.rst b/Doc/library/colorsys.rst index dffc16ae8b7d47..35873c9de619de 100644 --- a/Doc/library/colorsys.rst +++ b/Doc/library/colorsys.rst @@ -19,7 +19,7 @@ spaces, the coordinates are all between 0 and 1. .. seealso:: More information about color spaces can be found at - https://poynton.ca/ColorFAQ.html and + https://www.poynton.ca/pdf/ColourFAQ.pdf and https://www.cambridgeincolour.com/tutorials/color-spaces.htm. The :mod:`!colorsys` module defines the following functions: diff --git a/Doc/library/compression.zstd.rst b/Doc/library/compression.zstd.rst index a9fc4fa4b8cc36..33db45fb7c3b46 100644 --- a/Doc/library/compression.zstd.rst +++ b/Doc/library/compression.zstd.rst @@ -827,10 +827,45 @@ Miscellaneous The default compression level for Zstandard: ``3``. -.. attribute:: zstd_version_info +Information about the version of the zstd library in use is available through +the following constants: - Version number of the runtime zstd library as a tuple of integers - (major, minor, release). + +.. data:: ZSTD_VERSION + + The version string of the zstd library that was used for building the module. + This may be different from the zstd library actually used at runtime, which + is available as :const:`zstd_version`. + + .. versionadded:: next + + +.. data:: zstd_version + + The version string of the zstd library actually loaded by the interpreter. + + +.. data:: ZSTD_VERSION_INFO + + A named tuple containing the three components of the zstd library + version that was used for building the module: + *major*, *minor*, and *patch*. All values are integers. + The components can also be accessed by name, so ``zstd.ZSTD_VERSION_INFO[0]`` + is equivalent to ``zstd.ZSTD_VERSION_INFO.major`` and so on. + This may be different from the zstd library actually used at runtime, which + is available as :const:`zstd_version_info`. + + .. versionadded:: next + + +.. data:: zstd_version_info + + A named tuple containing the version of the zstd library + actually loaded by the interpreter, + with the same fields as :const:`ZSTD_VERSION_INFO`. + + .. versionchanged:: next + It is now a named tuple. Examples diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index d76c449626fab4..169459881328ab 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -708,7 +708,7 @@ Specifying function pointers using type annotations @wrap_dll_function(dll_to_wrap) def function_ptr_name(arg_name: ctypes_type, ...) -> ctypes_type: - """Optional docstring. There should be no function body.""" + """Optional docstring. There should be no function body.""" The body of the decorated function is ignored, and any parameters that are missing type annotations are skipped. The names of the parameters are ignored @@ -728,7 +728,7 @@ Specifying function pointers using type annotations @wrap_dll_function(ctypes.pythonapi) def PyObject_GetAttrString(op: ctypes.py_object, attr: ctypes.c_char_p) -> ctypes.py_object: - pass + pass PyObject_GetAttrString(42, b"real") @@ -3207,7 +3207,7 @@ fields, or any other data types containing pointer type fields. that should be merged into a containing structure or union. -.. decorator:: struct(*, align=None, layout, endian='native', pack=None) +.. decorator:: struct(*, align=None, layout=None, endian='native', pack=None) :module: ctypes.util A :term:`decorator` that allows generating structure types using an @@ -3244,14 +3244,18 @@ fields, or any other data types containing pointer type fields. .. code-block:: python + from typing import Annotated + from ctypes import c_ssize_t, c_void_p + from ctypes.util import struct, CFieldInfo + @struct class PyObject: - ob_refcnt: c_ssize_t - ob_type: c_void_p + ob_refcnt: c_ssize_t + ob_type: c_void_p @struct class PyHovercraftObject: - ob_base: Annotated[PyObject, CFieldInfo(anonymous=True)] + ob_base: Annotated[PyObject, CFieldInfo(anonymous=True)] .. versionadded:: next diff --git a/Doc/library/importlib.metadata.rst b/Doc/library/importlib.metadata.rst index e11db37b9fad50..1378a131f0ce65 100644 --- a/Doc/library/importlib.metadata.rst +++ b/Doc/library/importlib.metadata.rst @@ -90,6 +90,7 @@ collection of :ref:`EntryPoint ` objects. You can get the :ref:`metadata for a distribution `:: + >>> from importlib.metadata import metadata # doctest: +SKIP >>> list(metadata('wheel')) # doctest: +SKIP ['Metadata-Version', 'Name', 'Version', 'Summary', 'Home-page', 'Author', 'Author-email', 'Maintainer', 'Maintainer-email', 'License', 'Project-URL', 'Project-URL', 'Project-URL', 'Keywords', 'Platform', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Classifier', 'Requires-Python', 'Provides-Extra', 'Requires-Dist', 'Requires-Dist'] diff --git a/Doc/library/index.rst b/Doc/library/index.rst index f28c03e2fae092..79437d533512b1 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -1,16 +1,18 @@ .. _library-index: ############################### - The Python Standard Library + The Python standard library ############################### -While :ref:`reference-index` describes the exact syntax and -semantics of the Python language, this library reference manual -describes the standard library that is distributed with Python. It also -describes some of the optional components that are commonly included -in Python distributions. +This library reference manual describes the standard library +distributed with Python. It also describes some of the optional +components that are commonly included in Python distributions. -Python's standard library is very extensive, offering a wide range of +Elsewhere, :ref:`reference-index` describes the exact syntax and +semantics of the Python language, and :ref:`builtins-index` describes +the built-in functions. + +Python's standard library is extensive, offering a wide range of facilities as indicated by the long table of contents listed below. The library contains built-in modules (written in C) that provide access to system functionality such as file I/O that would otherwise be @@ -39,12 +41,6 @@ the `Python Package Index `_. :maxdepth: 2 intro.rst - functions.rst - constants.rst - stdtypes.rst - exceptions.rst - threadsafety.rst - time-complexity.rst text.rst binary.rst diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst index 8f76044be488cd..fcd2175dbccc01 100644 --- a/Doc/library/intro.rst +++ b/Doc/library/intro.rst @@ -4,48 +4,34 @@ Introduction ************ -The "Python library" contains several different kinds of components. - -It contains data types that would normally be considered part of the "core" of a -language, such as numbers and lists. For these types, the Python language core -defines the form of literals and places some constraints on their semantics, but -does not fully define the semantics. (On the other hand, the language core does -define syntactic properties like the spelling and priorities of operators.) - -The library also contains built-in functions and exceptions --- objects that can -be used by all Python code without the need of an :keyword:`import` statement. -Some of these are defined by the core language, but many are not essential for -the core semantics and are only described here. - -The bulk of the library, however, consists of a collection of modules. There are -many ways to dissect this collection. Some modules are written in C and built -in to the Python interpreter; others are written in Python and imported in -source form. Some modules provide interfaces that are highly specific to +The Python standard library consists of a collection of modules. There are +many ways to dissect this collection. Most modules are written in Python, +but some are written in C. All can be imported into your program to add +functionality. Some modules provide interfaces that are highly specific to Python, like printing a stack trace; some provide interfaces that are specific to particular operating systems, such as access to specific hardware; others provide interfaces that are specific to a particular application domain, like -the World Wide Web. Some modules are available in all versions and ports of +web development. Some modules are available in all versions and ports of Python; others are only available when the underlying system supports or requires them; yet others are available only when a particular configuration option was chosen at the time when Python was compiled and installed. -This manual is organized "from the inside out:" it first describes the built-in -functions, data types and exceptions, and finally the modules, grouped in -chapters of related modules. - -This means that if you start reading this manual from the start, and skip to the +If you start reading this manual from the start, and skip to the next chapter when you get bored, you will get a reasonable overview of the available modules and application areas that are supported by the Python library. Of course, you don't *have* to read it like a novel --- you can also browse the table of contents (in front of the manual), or look for a specific function, module or term in the index (in the back). And finally, if you enjoy -learning about random subjects, you choose a random page number (see module -:mod:`random`) and read a section or two. Regardless of the order in which you -read the sections of this manual, it helps to start with chapter -:ref:`built-in-funcs`, as the remainder of the manual assumes familiarity with -this material. +learning about random subjects, you choose a random page +and read a section or two. Regardless of the order in which you +read the sections of this manual, it helps to first read +:ref:`built-in-funcs`, as the remainder of this section +assumes familiarity with this material. + +.. seealso:: -Let the show begin! + The built-in functions and classes (which can be used without an + :keyword:`import` statement) are described in :ref:`builtins-index`. .. _availability: diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 5e8c452a5ab9a1..ddd12a002f7416 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -261,6 +261,8 @@ Basic Usage into JSON and then back into a dictionary, the dictionary may not equal the original one. That is, ``loads(dumps(x)) != x`` if x has non-string keys. + *sort_keys* sorts the keys before they are coerced to strings, + so numeric keys are sorted by value, not by their string representation. .. function:: load(fp, *, cls=None, object_hook=None, parse_float=None, \ parse_int=None, parse_constant=None, \ diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst index 580829cfbb46e0..49ba6d9b7ed4f2 100644 --- a/Doc/library/lzma.rst +++ b/Doc/library/lzma.rst @@ -314,6 +314,50 @@ Miscellaneous feature set. +Information about the version of the lzma library in use is available through +the following constants: + + +.. data:: LZMA_VERSION + + The version string of the lzma library that was used for building the module. + This may be different from the lzma library actually used at runtime, which + is available as :const:`lzma_version`. + + .. versionadded:: next + + +.. data:: lzma_version + + The version string of the lzma library actually loaded by the interpreter. + + .. versionadded:: next + + +.. data:: LZMA_VERSION_INFO + + A named tuple containing the four components of the lzma library + version that was used for building the module: + *major*, *minor*, *patch*, and *stability*. + All values except *stability* are integers; *stability* is ``'alpha'``, + ``'beta'``, or ``'stable'``. + The components can also be accessed by name, so ``lzma.LZMA_VERSION_INFO[0]`` + is equivalent to ``lzma.LZMA_VERSION_INFO.major`` and so on. + This may be different from the lzma library actually used at runtime, which + is available as :const:`lzma_version_info`. + + .. versionadded:: next + + +.. data:: lzma_version_info + + A named tuple containing the version of the lzma library + actually loaded by the interpreter, + with the same fields as :const:`LZMA_VERSION_INFO`. + + .. versionadded:: next + + .. _filter-chain-specs: Specifying custom filter chains diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index bedea46cb16d60..43fad57139057c 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -2538,7 +2538,7 @@ with the :class:`Pool` class. .. method:: imap(func, iterable, chunksize=1, *, buffersize=None) - A lazier version of :meth:`.map`. + An iterator-based version of :meth:`.map`. The *chunksize* argument is the same as the one used by the :meth:`.map` method. For very long iterables using a large value for *chunksize* can diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index fb9249df4be33e..054ccc556740c2 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -1497,7 +1497,7 @@ Socket Objects of :meth:`socket.getpeername` but not the actual OS resource. Unlike :func:`socket.fromfd`, *fileno* will return the same socket and not a duplicate. This may help close a detached socket using - :meth:`socket.close`. + :meth:`~socket.socket.close`. The newly created socket is :ref:`non-inheritable `. @@ -1544,7 +1544,7 @@ Socket Objects .. versionchanged:: 3.2 Support for the :term:`context manager` protocol was added. Exiting the - context manager is equivalent to calling :meth:`~socket.close`. + context manager is equivalent to calling :meth:`~socket.socket.close`. .. method:: accept() @@ -1769,7 +1769,7 @@ Socket Objects Closing the file object returned by :meth:`makefile` won't close the original socket unless all other file objects have been closed and - :meth:`socket.close` has been called on the socket object. + :meth:`~socket.socket.close` has been called on the socket object. .. note:: diff --git a/Doc/library/sys.monitoring.rst b/Doc/library/sys.monitoring.rst index 7cca6f2bcdae91..0a653506b3d495 100644 --- a/Doc/library/sys.monitoring.rst +++ b/Doc/library/sys.monitoring.rst @@ -54,11 +54,18 @@ Registering and using tools Unregister all events and callback functions associated with *tool_id*. + .. versionadded:: 3.14 + .. function:: free_tool_id(tool_id: int, /) -> None Should be called once a tool no longer requires *tool_id*. Will call :func:`clear_tool_id` before releasing *tool_id*. + .. versionchanged:: 3.14 + Now calls :func:`clear_tool_id` before releasing *tool_id*. + Previously, it would not disable global or local events associated + with *tool_id*, nor unregister any callback functions. + .. function:: get_tool(tool_id: int, /) -> str | None Returns the name of the tool if *tool_id* is in use, diff --git a/Doc/library/tk.rst b/Doc/library/tk.rst index e27af48ba7ac48..9ca26a5dfa7659 100644 --- a/Doc/library/tk.rst +++ b/Doc/library/tk.rst @@ -34,7 +34,7 @@ alternative `GUI frameworks and tools " character of a @@ -658,6 +707,9 @@ Functions A :exc:`ResourceWarning` is now emitted if the iterator opened a file and is not explicitly closed. + .. versionchanged:: next + Added the *target* parameter. + .. function:: parse(source, parser=None) @@ -1491,7 +1543,7 @@ XMLParser Objects XMLPullParser Objects ^^^^^^^^^^^^^^^^^^^^^ -.. class:: XMLPullParser(events=None) +.. class:: XMLPullParser(events=None, *, target=None) A pull parser suitable for non-blocking applications. Its input-side API is similar to that of :class:`XMLParser`, but instead of pushing calls to a @@ -1502,6 +1554,20 @@ XMLPullParser Objects are used to get detailed namespace information). If *events* is omitted, only ``"end"`` events are reported. + *target* is the target object of the underlying :class:`XMLParser`. + If omitted, the standard :class:`TreeBuilder` is used, + and the reported objects are :class:`Element` instances. + With other targets the reported object is the value returned + by the corresponding method of the target, + so no tree is built if the target does not build one. + The target must implement the methods for all requested events, + except :meth:`!start_ns` and :meth:`!end_ns`: + if they are not implemented, a ``(prefix, uri)`` tuple and ``None`` + are reported for the ``"start-ns"`` and ``"end-ns"`` events. + + .. versionchanged:: next + Added the *target* parameter. + .. method:: feed(data) Feed the given data to the parser. *data* is a string @@ -1534,9 +1600,10 @@ XMLPullParser Objects Return an iterator over the events which have been encountered in the data fed to the - parser. The iterator yields ``(event, elem)`` pairs, where *event* is a - string representing the type of event (e.g. ``"end"``) and *elem* is the - encountered :class:`Element` object, or other context value as follows. + parser. The iterator yields ``(event, obj)`` pairs, where *event* is a + string representing the type of event (e.g. ``"end"``) and *obj* is the + object returned by the corresponding method of the target. + With the standard :class:`TreeBuilder` it is as follows. * ``start``, ``end``: the current Element. * ``comment``, ``pi``: the current comment / processing instruction diff --git a/Doc/library/zlib.rst b/Doc/library/zlib.rst index 266bf968e329b4..5035fa27fb6c1b 100644 --- a/Doc/library/zlib.rst +++ b/Doc/library/zlib.rst @@ -479,27 +479,65 @@ the following constants: The version string of the zlib library that was used for building the module. This may be different from the zlib library actually used at runtime, which - is available as :const:`ZLIB_RUNTIME_VERSION`. + is available as :const:`zlib_version`. .. data:: ZLIB_RUNTIME_VERSION + zlib_version The version string of the zlib library actually loaded by the interpreter. .. versionadded:: 3.3 + The :const:`!ZLIB_RUNTIME_VERSION` constant. + + .. versionadded:: next + The :const:`!zlib_version` alias. + + +.. data:: ZLIB_VERSION_INFO + + A named tuple containing the four components of the zlib library + version that was used for building the module: + *major*, *minor*, *revision*, and *subversion*. + All values are integers. + The components can also be accessed by name, so ``zlib.ZLIB_VERSION_INFO[0]`` + is equivalent to ``zlib.ZLIB_VERSION_INFO.major`` and so on. + This may be different from the zlib library actually used at runtime, which + is available as :const:`zlib_version_info`. + + .. versionadded:: next + + +.. data:: zlib_version_info + + A named tuple containing the version of the zlib library + actually loaded by the interpreter, + with the same fields as :const:`ZLIB_VERSION_INFO`. + + .. versionadded:: next + + +The following constants are only present if zlib-ng was used to build +the module: .. data:: ZLIBNG_VERSION The version string of the zlib-ng library that was used for building the - module if zlib-ng was used. When present, the :data:`ZLIB_VERSION` and - :data:`ZLIB_RUNTIME_VERSION` constants reflect the version of the zlib API + module if zlib-ng was used. When present, the :const:`ZLIB_VERSION` and + :const:`zlib_version` constants reflect the version of the zlib API provided by zlib-ng. - If zlib-ng was not used to build the module, this constant will be absent. - .. versionadded:: 3.14 +.. data:: ZLIBNG_VERSION_INFO + + A named tuple containing the three components of the zlib-ng library + version that was used for building the module: + *major*, *minor*, and *revision*. All values are integers. + + .. versionadded:: next + .. seealso:: diff --git a/Doc/pylock.toml b/Doc/pylock.toml index 94b7d9d48d646e..3ad79b3cc6a873 100644 --- a/Doc/pylock.toml +++ b/Doc/pylock.toml @@ -238,6 +238,12 @@ version = "0.13.0" sdist = { url = "https://files.pythonhosted.org/packages/f6/c0/eb6838e3bae624ce6c8b90b245d17e84252863150e95efdb88f92c8aa3fb/sphinxext_opengraph-0.13.0.tar.gz", upload-time = 2025-08-29T12:20:31Z, size = 1026875, hashes = { sha256 = "103335d08567ad8468faf1425f575e3b698e9621f9323949a6c8b96d9793e80b" } } wheels = [{ url = "https://files.pythonhosted.org/packages/bf/a4/66c1fd4f8fab88faf71cee04a945f9806ba0fef753f2cfc8be6353f64508/sphinxext_opengraph-0.13.0-py3-none-any.whl", upload-time = 2025-08-29T12:20:29Z, size = 1004152, hashes = { sha256 = "936c07828edc9ad9a7b07908b29596dc84ed0b3ceaa77acdf51282d232d4d80e" } }] +[[packages]] +name = "sphinxext-rediraffe" +version = "0.3.0" +sdist = { url = "https://files.pythonhosted.org/packages/e3/a9/ab13d156049eea633f992424f3e92cb40e3f1b606bb6d01d40a27457d38a/sphinxext_rediraffe-0.3.0.tar.gz", upload-time = 2025-09-28T15:31:53Z, size = 22114, hashes = { sha256 = "f319b3ccb7c3c3b6f63ffa6fd3eeb171b6d272df55075a9e84364394f391f507" } } +wheels = [{ url = "https://files.pythonhosted.org/packages/87/55/ab40a0d1378ee5c859590a633052cf1d0a1f8435af87558a9f7cd576601a/sphinxext_rediraffe-0.3.0-py3-none-any.whl", upload-time = 2025-09-28T15:31:52Z, size = 7194, hashes = { sha256 = "f4220beafa99c99177488276b8e4fcf61fbeeec4253c1e4aae841a18c475330c" } }] + [[packages]] name = "urllib3" version = "2.7.0" diff --git a/Doc/reference/index.rst b/Doc/reference/index.rst index a66673b17246d7..9a5b2e631204a5 100644 --- a/Doc/reference/index.rst +++ b/Doc/reference/index.rst @@ -4,10 +4,13 @@ The Python Language Reference ################################# -This reference manual describes the syntax and "core semantics" of the -language. It is terse, but attempts to be exact and complete. The semantics of -non-essential built-in object types and of the built-in functions and modules -are described in :ref:`library-index`. For an informal introduction to the +This reference manual describes the syntax and core semantics of the +language. It is terse, but attempts to be exact and complete. + +Elsewhere, the built-in object types and functions are described in +:ref:`builtins-index`. Standard library modules are described in :ref:`library-index`. + +For an informal introduction to the language, see :ref:`tutorial-index`. For C or C++ programmers, two additional manuals exist: :ref:`extending-index` describes the high-level picture of how to write a Python extension module, and the :ref:`c-api-index` describes the diff --git a/Doc/requirements.txt b/Doc/requirements.txt index b9072b4af54222..2fa952aa291f1f 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -16,6 +16,7 @@ blurb sphinx-linklint sphinx-notfound-page~=1.0.0 sphinxext-opengraph~=0.13.0 +sphinxext-rediraffe # The theme used by the documentation is stored separately, so we need # to install that as well. diff --git a/Doc/tools/check-html-ids.py b/Doc/tools/check-html-ids.py index 3ea0a99d1dd4f6..12bda7666073d4 100644 --- a/Doc/tools/check-html-ids.py +++ b/Doc/tools/check-html-ids.py @@ -19,18 +19,33 @@ ) +class Redirect(Exception): # noqa: N818 Exception should be named with an Error suffix + def __init__(self, redirect_to): + self.redirect_to = redirect_to + + class IDGatherer(html.parser.HTMLParser): def __init__(self, ids): super().__init__() self.__ids = ids def handle_starttag(self, tag, attrs): + if tag == "meta": + # Redirects are done with a meta tag: + # + dattr = dict(attrs) + if dattr.get("http-equiv") == "refresh": + content = dattr.get("content", "") + if content.startswith("0; url="): + redirect_to = content[7:] + raise Redirect(redirect_to) for name, value in attrs: if name == 'id': if not IGNORED_ID_RE.fullmatch(value): self.__ids.add(value) +@functools.cache def get_ids_from_file(path): ids = set() gatherer = IDGatherer(ids) @@ -40,6 +55,18 @@ def get_ids_from_file(path): return ids +def get_ids_including_redirects(path): + # Only try 6 redirects, to avoid accidental endless loops + for _ in range(6): + try: + return get_ids_from_file(path) + except Redirect as r: + path = (path.parent / r.redirect_to).resolve() + continue + else: + raise RuntimeError("Apparent infinite redirects") + + def gather_ids(htmldir, *, verbose_print): if not htmldir.joinpath('objects.inv').exists(): raise ValueError(f'{htmldir!r} is not a Sphinx HTML output directory') @@ -55,7 +82,9 @@ def gather_ids(htmldir, *, verbose_print): continue if 'whatsnew' in relative_path.parts: continue - tasks[relative_path] = pool.submit(get_ids_from_file, path=path) + tasks[relative_path] = pool.submit( + get_ids_including_redirects, path=path + ) ids_by_page = {} for relative_path, future in tasks.items(): diff --git a/Doc/tools/extensions/changes.py b/Doc/tools/extensions/changes.py index 02dc51b3a76943..e6a912cef8810e 100644 --- a/Doc/tools/extensions/changes.py +++ b/Doc/tools/extensions/changes.py @@ -6,6 +6,7 @@ from docutils import nodes from sphinx import addnodes +from sphinx.builders.changes import ChangesBuilder from sphinx.domains.changeset import ( VersionChange, versionlabel_classes, @@ -17,6 +18,7 @@ if TYPE_CHECKING: from docutils.nodes import Node from sphinx.application import Sphinx + from sphinx.environment import BuildEnvironment from sphinx.util.typing import ExtensionMetadata @@ -146,6 +148,32 @@ def _add_glossary_link(cls, inline: nodes.inline) -> None: break +def _fixup_changesets(app: Sphinx, env: BuildEnvironment) -> None: + changesets = env.get_domain("changeset").changesets + + # The changeset domain records each entry's plain text before SoftDeprecated + # replaces the :term:, so strip the markup before the changes builder renders it. + for entries in changesets.values(): + for i, entry in enumerate(entries): + if entry.type == "soft-deprecated": + entries[i] = entry._replace( + content=SoftDeprecated._TERM_RE.sub(r"\1", entry.content) + ) + + # DeprecatedRemoved entries are recorded under their (deprecated, + # removed) version tuple, which the changes builder ignores. + # Re-file them under both versions. + for versions in [v for v in changesets if isinstance(v, tuple)]: + deprecated, removed = versions + for entry in changesets.pop(versions): + changesets.setdefault(deprecated, []).append( + entry._replace(type="deprecated") + ) + changesets.setdefault(removed, []).append( + entry._replace(type="versionremoved") + ) + + def setup(app: Sphinx) -> ExtensionMetadata: # Override Sphinx's directives with support for 'next' app.add_directive("versionadded", PyVersionChange, override=True) @@ -155,9 +183,15 @@ def setup(app: Sphinx) -> ExtensionMetadata: # Register the ``.. deprecated-removed::`` directive app.add_directive("deprecated-removed", DeprecatedRemoved) + # _fixup_changesets() changes these entries to 'deprecated'/'versionremoved' + ChangesBuilder.typemap["deprecated-removed"] = "deprecated-removed" # Register the ``.. soft-deprecated::`` directive app.add_directive("soft-deprecated", SoftDeprecated) + ChangesBuilder.typemap["soft-deprecated"] = "soft deprecated" + + # Repair the recorded changesets for the couple of custom directives above + app.connect("env-updated", _fixup_changesets) return { "version": "1.0", diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt index 20bef00eb891cb..ae116da1456641 100644 --- a/Doc/tools/removed-ids.txt +++ b/Doc/tools/removed-ids.txt @@ -82,3 +82,6 @@ reference/expressions.html: generator.__next__ reference/expressions.html: generator.close reference/expressions.html: generator.send reference/expressions.html: generator.throw + +# Renamed to library/tkinter.dialogs.html +library/dialog.html: (page missing) diff --git a/Doc/tools/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html index 4366da69d1b2d0..59a693c00003c4 100644 --- a/Doc/tools/templates/indexcontent.html +++ b/Doc/tools/templates/indexcontent.html @@ -56,16 +56,18 @@

{{ docstitle|e }}

{% trans whatsnew_index=pathto("whatsnew/index") %}Or all "What's new" documents since Python 2.0{% endtrans %}
  • {% trans %}Tutorial{% endtrans %}
    {% trans %}Start here: a tour of Python's syntax and features{% endtrans %}
    • +
  • {% trans %}Built-ins reference{% endtrans %}
    + {% trans %}Built-in functions and classes{% endtrans %}
  • {% trans %}Library reference{% endtrans %}
    - {% trans %}Standard library and builtins{% endtrans %}
    • + {% trans %}Standard library modules{% endtrans %}
  • {% trans %}Language reference{% endtrans %}
    {% trans %}Syntax and language elements{% endtrans %}
  • {% trans %}Python setup and usage{% endtrans %}
    {% trans %}How to install, configure, and use Python{% endtrans %}
    • -
  • {% trans %}Python HOWTOs{% endtrans %}
    - {% trans %}In-depth topic manuals{% endtrans %}