python · nedbat · Aug 30, 2026 · Aug 30, 2026 · Aug 31, 2026 · Aug 31, 2026
diff --git a/Doc/library/constants.rst → Doc/builtins/constants.rst b/Doc/library/constants.rst → Doc/builtins/constants.rst
diff --git a/Doc/library/exceptions.rst → Doc/builtins/exceptions.rst b/Doc/library/exceptions.rst → Doc/builtins/exceptions.rst
diff --git a/Doc/library/functions.rst → Doc/builtins/functions.rst b/Doc/library/functions.rst → Doc/builtins/functions.rst
diff --git a/Doc/builtins/index.rst 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 → Doc/builtins/stdtypes.rst b/Doc/library/stdtypes.rst → Doc/builtins/stdtypes.rst
diff --git a/Doc/library/threadsafety.rst → Doc/builtins/threadsafety.rst b/Doc/library/threadsafety.rst → Doc/builtins/threadsafety.rst
diff --git a/Doc/library/time-complexity.rst → Doc/builtins/time-complexity.rst b/Doc/library/time-complexity.rst → Doc/builtins/time-complexity.rst
@@ -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 @@
         '<meta property="og:image:width" content="200">',
         '<meta property="og:image:height" content="200">',
     )
+
+# 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
@@ -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
@@ -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/index.rst b/Doc/library/index.rst
@@ -1,11 +1,12 @@
 .. _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
+semantics of the Python language, and :ref:`builtins-index` describes
+the built-ins, 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.
@@ -39,12 +40,6 @@ the `Python Package Index <https://pypi.org>`_.
    :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
@@ -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
+The Python standard library consists of a collection of modules. There are
+many ways to dissect this collection.  Some modules are written in C and compiled
+into the Python interpreter; others are written in Python and imported in
 source form.  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` in :ref:`builtins-index`, 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/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"

@@ -4,10 +4,11 @@
   The Python Language Reference
 #################################
 
-This reference manual describes the syntax and "core semantics" of the
+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
+built-in object types and of the built-in functions and modules
+are described in :ref:`builtins-index` and :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

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

@@ -19,12 +19,26 @@
 )
 
 
+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:
+            # <meta http-equiv="refresh" content="0; url=../builtins/stdtypes.html"/>
+            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):
@@ -40,6 +54,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 +81,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():

@@ -56,16 +56,18 @@ <h1>{{ docstitle|e }}</h1>
          <span class="linkdescr"> {% trans whatsnew_index=pathto("whatsnew/index") %}Or <a href="{{ whatsnew_index }}">all "What's new" documents since Python 2.0</a>{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{% trans %}Tutorial{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Start here: a tour of Python's syntax and features{% endtrans %}</span></li>
+      <li class="biglink"><a class="biglink" href="{{ pathto("builtins/index") }}">{% trans %}Built-ins reference{% endtrans %}</a><br>
+         <span class="linkdescr">{% trans %}Built-in functions and classes{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">{% trans %}Library reference{% endtrans %}</a><br>
-         <span class="linkdescr">{% trans %}Standard library and builtins{% endtrans %}</span></li>
+         <span class="linkdescr">{% trans %}Standard library modules{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">{% trans %}Language reference{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Syntax and language elements{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">{% trans %}Python setup and usage{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}How to install, configure, and use Python{% endtrans %}</span></li>
-      <li class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br>
-         <span class="linkdescr">{% trans %}In-depth topic manuals{% endtrans %}</span></li>
     </ul>
     <ul>
+      <li class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br>
+         <span class="linkdescr">{% trans %}In-depth topic manuals{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">{% trans %}Installing Python modules{% endtrans %}</a><br>
          <span class="linkdescr">{% trans %}Third-party modules and PyPI.org{% endtrans %}</span></li>
       <li class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and embedding{% endtrans %}</a><br>

diff --git a/Doc/tutorial/index.rst b/Doc/tutorial/index.rst
@@ -30,9 +30,9 @@ have a basic understanding of programming in general. It helps to have a Python
 interpreter handy for hands-on experience, but all examples are self-contained,
 so the tutorial can be read off-line as well.
 
-For a description of standard objects and modules, see :ref:`library-index`.
-:ref:`reference-index` gives a more formal definition of the language.  To write
-extensions in C or C++, read :ref:`extending-index` and
+For a description of standard objects and modules, see :ref:`builtins-index` and
+:ref:`library-index`.  :ref:`reference-index` gives a more formal definition of
+the language.  To write extensions in C or C++, read :ref:`extending-index` and
 :ref:`c-api-index`. There are also several books covering Python in depth.
 
 This tutorial does not attempt to be comprehensive and cover every single

diff --git a/Doc/tutorial/whatnow.rst b/Doc/tutorial/whatnow.rst
@@ -11,9 +11,10 @@ should you go to learn more?
 This tutorial is part of Python's documentation set.   Some other documents in
 the set are:
 
-* :ref:`library-index`:
+* :ref:`builtins-index`: gives details about Python's built-in types and
+  functions.
 
-  You should browse through this manual, which gives complete (though terse)
+* :ref:`library-index`: gives complete (though terse)
   reference material about types, functions, and the modules in the standard
   library.  The standard Python distribution includes a *lot* of additional code.
   There are modules to read Unix mailboxes, retrieve documents via HTTP, generate

@@ -10,7 +10,7 @@ the source code location, which is useful for debuggers and other tools.
 Since 3.11, the final field of the `PyCodeObject` C struct is an array
 of indeterminate length containing the bytecode, `code->co_code_adaptive`.
 (In older versions the code object was a
-[`bytes`](https://docs.python.org/dev/library/stdtypes.html#bytes)
+[`bytes`](https://docs.python.org/dev/builtins/stdtypes.html#bytes)
 object, `code->co_code`; this was changed to save an allocation and to
 allow it to be mutated.)
 

@@ -80,7 +80,7 @@ Key ideas
   using memoization.
 - If parsing fails completely (no rule succeeds in parsing all the input text), the
   PEG parser doesn't have a concept of "where the
-  [`SyntaxError`](https://docs.python.org/3/library/exceptions.html#SyntaxError) is".
+  [`SyntaxError`](https://docs.python.org/3/builtins/exceptions.html#SyntaxError) is".
 
 
 > [!IMPORTANT]
@@ -654,7 +654,7 @@ is, and it will unwind the stack and report the exception. This means that if a
 [rule action](#grammar-actions) raises an exception, all parsing will
 stop at that exact point. This is done to allow to correctly propagate any
 exception set by calling Python's C API functions. This also includes
-[`SyntaxError`](https://docs.python.org/3/library/exceptions.html#SyntaxError)
+[`SyntaxError`](https://docs.python.org/3/builtins/exceptions.html#SyntaxError)
 exceptions and it is the main mechanism the parser uses to report custom syntax
 error messages.
 
@@ -715,7 +715,7 @@ acts in two phases:
 > When defining invalid rules:
 >
 > - Make sure all custom invalid rules raise
->   [`SyntaxError`](https://docs.python.org/3/library/exceptions.html#SyntaxError)
+>   [`SyntaxError`](https://docs.python.org/3/builtins/exceptions.html#SyntaxError)
 >   exceptions (or a subclass of it).
 > - Make sure **all** invalid rules start with the `invalid_` prefix to not
 >   impact performance of parsing correct Python code.
@@ -823,7 +823,7 @@ $ python -m pegen python <PATH TO YOUR GRAMMAR FILE>
 > Python's grammar (the `Grammar/python.gram` file) is written for the
 > C backend. To experiment, you will need to write a grammar
 > without C-specific parts like actions and the trailer.
-> See [#133560](https://github.com/python/cpython/issues/133560) 
+> See [#133560](https://github.com/python/cpython/issues/133560)
 > and [#96424](https://github.com/python/cpython/issues/96424) for more information.
 
 This will generate a file called `parse.py` in the same directory that you