From 09c858028266969ffa7f71b8312a219d01406972 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sun, 13 Sep 2026 11:55:44 -0400 Subject: [PATCH 1/2] [3.13] Docs: split builtins to their own page from library (GH-156682) * Docs: split builtins to their own page from library * review feedback * addressed Hugo's feedback * update the What's Next page * one more wording tweak * move builtins to their own directory. fix the reference name * moved pages need to be noted in tools/removed-ids.txt * add Python to the builtins reference title * add sphinxext-rediraffe for the library->builtins split * update check-html-ids to handle rediraffe redirects * now we don't need (page missing) for the redirected pages * update other references to moved pages * A seealso from builtins to library * make a nice section for rediraffe settings * move the builtins note to the end, as a seealso * address merwok's comments * cache looking for ids in files * simplify the intro paragraphs (cherry picked from commit 59c4bddb1762b4706c942d6403fb8df470f37e05) Co-authored-by: Ned Batchelder --- Doc/{library => builtins}/constants.rst | 0 Doc/{library => builtins}/exceptions.rst | 0 Doc/{library => builtins}/functions.rst | 0 Doc/builtins/index.rst | 35 +++++++++++++++++++ Doc/{library => builtins}/stdtypes.rst | 0 Doc/conf.py | 30 +++++++++++++++- Doc/contents.rst | 1 + Doc/extending/index.rst | 11 +++--- Doc/library/index.rst | 21 +++++------ Doc/library/intro.rst | 44 ++++++++---------------- Doc/reference/index.rst | 11 +++--- Doc/requirements.txt | 1 + Doc/tools/templates/indexcontent.html | 8 +++-- Doc/tutorial/index.rst | 6 ++-- Doc/tutorial/whatnow.rst | 5 +-- Lib/test/test_traceback.py | 4 +-- Tools/unicode/makeunicodedata.py | 2 +- 17 files changed, 117 insertions(+), 62 deletions(-) rename Doc/{library => builtins}/constants.rst (100%) rename Doc/{library => builtins}/exceptions.rst (100%) rename Doc/{library => builtins}/functions.rst (100%) create mode 100644 Doc/builtins/index.rst rename Doc/{library => builtins}/stdtypes.rst (100%) 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 000000000000000..17aab32200d976e --- /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/conf.py b/Doc/conf.py index 2beef8d5b6f7c43..26067d964968e7c 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -42,6 +42,8 @@ 'sphinx_linklint.ext', 'notfound.extension', 'sphinxext.opengraph', + 'sphinxext.rediraffe', + 'sphinxcontrib.rsvgconverter', ) for optional_ext in _OPTIONAL_EXTENSIONS: try: @@ -356,7 +358,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', @@ -371,6 +379,13 @@ _doc_authors, 'manual', ), + ( + 'builtins/index', + 'builtins.tex', + 'Python Built-ins Reference', + _doc_authors, + 'manual', + ), ( 'library/index', 'library.tex', @@ -597,3 +612,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 b57f4b09a5dcb6a..852be4a6d5b6ba7 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 4cc2c96d8d5b47e..3880f4d0b49c492 100644 --- a/Doc/extending/index.rst +++ b/Doc/extending/index.rst @@ -12,11 +12,12 @@ language. Finally, it shows how to compile and link extension modules so that they can be loaded dynamically (at run time) into the interpreter, if the underlying operating system supports this feature. -This document assumes basic knowledge about Python. For an informal -introduction to the language, 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. +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:`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 index 163e1679c65ef83..078adf4c261d553 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,11 +41,6 @@ the `Python Package Index `_. :maxdepth: 2 intro.rst - functions.rst - constants.rst - stdtypes.rst - exceptions.rst - text.rst binary.rst datatypes.rst diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst index 8f76044be488cda..fcd2175dbccc01b 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/reference/index.rst b/Doc/reference/index.rst index a66673b17246d7b..9a5b2e631204a55 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 fc3424bb61dbb23..8d6c07ec283caa5 100644 --- a/Doc/requirements.txt +++ b/Doc/requirements.txt @@ -14,6 +14,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/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html index 4366da69d1b2d09..59a693c00003c45 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 %}
      • +
    • {% trans %}Python HOWTOs{% endtrans %}
      + {% trans %}In-depth topic manuals{% endtrans %}
    • {% trans %}Installing Python modules{% endtrans %}
      {% trans %}Third-party modules and PyPI.org{% endtrans %}
    • {% trans %}Extending and embedding{% endtrans %}
      diff --git a/Doc/tutorial/index.rst b/Doc/tutorial/index.rst index 20fe161be4acc26..c3ae5eefdfb6693 100644 --- 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 index aae8f29b0077627..6f4d1329682be3f 100644 --- 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 diff --git a/Lib/test/test_traceback.py b/Lib/test/test_traceback.py index fec6750afa9d2f5..ca6925d3f3137b5 100644 --- a/Lib/test/test_traceback.py +++ b/Lib/test/test_traceback.py @@ -3796,7 +3796,7 @@ def f(): def test_dont_swallow_cause_or_context_of_falsey_exception(self): # see gh-132308: Ensure that __cause__ or __context__ attributes of exceptions # that evaluate as falsey are included in the output. For falsey term, - # see https://docs.python.org/3/library/stdtypes.html#truth-value-testing. + # see https://docs.python.org/3/builtins/stdtypes.html#truth-value-testing. try: raise FalseyException from KeyError @@ -4015,7 +4015,7 @@ def test_comparison(self): def test_dont_swallow_subexceptions_of_falsey_exceptiongroup(self): # see gh-132308: Ensure that subexceptions of exception groups # that evaluate as falsey are displayed in the output. For falsey term, - # see https://docs.python.org/3/library/stdtypes.html#truth-value-testing. + # see https://docs.python.org/3/builtins/stdtypes.html#truth-value-testing. try: raise FalseyExceptionGroup("Gih", (KeyError(), NameError())) diff --git a/Tools/unicode/makeunicodedata.py b/Tools/unicode/makeunicodedata.py index 181d4d07b52ac23..fa499733d03c695 100644 --- a/Tools/unicode/makeunicodedata.py +++ b/Tools/unicode/makeunicodedata.py @@ -42,7 +42,7 @@ # The Unicode Database # -------------------- # When changing UCD version please update -# * Doc/library/stdtypes.rst, and +# * Doc/builtins/stdtypes.rst (four occurrences) # * Doc/library/unicodedata.rst # * Doc/reference/lexical_analysis.rst (two occurrences) UNIDATA_VERSION = "15.1.0" From 2a097f88557f1f16e9ef385e1888df6c2764f8dd Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sun, 13 Sep 2026 12:29:19 -0400 Subject: [PATCH 2/2] remove references to non-existent pages --- Doc/builtins/index.rst | 2 -- Doc/conf.py | 2 -- 2 files changed, 4 deletions(-) diff --git a/Doc/builtins/index.rst b/Doc/builtins/index.rst index 17aab32200d976e..0b9c0389e6e59c8 100644 --- a/Doc/builtins/index.rst +++ b/Doc/builtins/index.rst @@ -31,5 +31,3 @@ the core semantics and are only described here. constants.rst functions.rst exceptions.rst - threadsafety.rst - time-complexity.rst diff --git a/Doc/conf.py b/Doc/conf.py index 26067d964968e7c..8a2dd8a8e17af04 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -622,6 +622,4 @@ "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", }