Docs: split builtins to their own page from library by nedbat · Pull Request #156682 · python/cpython

nedbat · 2026-08-30T20:07:36Z

We've talked about separating the built-ins from the stdlib modules, since "dict" (for example) isn't part of the stdlib.

I think I took care of all the places the pages are referenced, but the non-HTML builds are new to me, so I might have missed something.

I tried to make the intro paragraphs and pages useful, and avoided over-editing them.

nedbat · 2026-08-30T20:11:51Z

Also: is this NEWS-worthy?

StanFromIreland · 2026-08-30T20:12:50Z

Also: is this NEWS-worthy?

I don't see a need for one here, I think the docs speak for themselves.

read-the-docs-community · 2026-08-30T20:14:40Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #34527956 | 📁 Comparing 7caff5c against main (852381e)

🔍 Preview build

74 files changed · + 7 added · ± 67 modified

+ Added

± Modified

hugovk

Shall we name the new Doc/library/builtin-index.rst as Doc/builtins/index.rst instead?

Then instead of:

https://docs.python.org/3/library/builtins-index.html

We get a neater:

This PR can still reference the builtin stuff in their current location, and a followup could move the relevant files and deal with redirects:

Doc/library/functions.rst -> Doc/builtins/functions.rst
Doc/library/stdtypes.rst -> Doc/builtins/stdtypes.rst
Doc/library/constants.rst -> Doc/builtins/constants.rst
Doc/library/exceptions.rst -> Doc/builtins/exceptions.rst
Doc/library/threadsafety.rst -> Doc/builtins/threadsafety.rst
Doc/library/time-complexity.rst -> Doc/builtins/time-complexity.rst

StanFromIreland

Also, you need to update the What Now? page in the tutorial.

I concur with Hugo, splitting this into a separate directory would be nicer. We can do redirects at client side (using one of the various Sphinx extensions) or sever side (by configuring them in python/psf-salt).

nedbat · 2026-08-31T17:55:49Z

I can do the renames and redirects.

We can do redirects at client side (using one of the various Sphinx extensions) or sever side (by configuring them in python/psf-salt).

What Sphinx extension have we used for redirects before? I see https://github.com/python/psf-salt/blob/main/salt/docs/config/nginx.docs-redirects.conf for the psf-salt approach.

StanFromIreland · 2026-08-31T18:17:41Z

What Sphinx extension have we used for redirects before?

We use sphinxext-rediraffe in the Devguide, it generates stubs with some JS to redirect to the new page.

nedbat · 2026-08-31T18:26:52Z

What Sphinx extension have we used for redirects before?

We use sphinxext-rediraffe in the Devguide, it generates stubs with some JS to redirect to the new page.

I knew rediraffe was somewhere! Is there a reason we don't want to introduce it for the main docs?

StanFromIreland · 2026-08-31T18:30:35Z

Is there a reason we don't want to introduce it for the main docs?

I presume it's simply because there hasn't really been a need so far. We're less keen to move pages here than in the Devguide. IIRC rediraffe requires JS, but that ship has sailed anyway.

hugovk · 2026-09-01T11:16:14Z

Server-side psf-salt redirects would be better than client-side sphinxext-rediraffe: they work with JavaScript disabled (better for all the scrapers and bots), are faster on server-side (HTTP layer before any HTML fetched), and get cached in the CDN, and better for SEO.

We don't have such server-side control for the devguide, which is hosted on GitHub Pages. (Also I'd say client-side JS redirects are fine for the less-important devguide.)

nedbat · 2026-09-01T12:50:23Z

That all makes sense. Do we have a way to coordinate the updates to psf-salt with updates to the docs, especially with backports involved?

StanFromIreland · 2026-09-01T15:10:08Z

(There's no documented process I'm afraid) You can open a PR there and limit the redirect to specific Python versions. I can review and merge when we land this.

nedbat · 2026-09-02T12:29:49Z

Moving pages causes the "removed HTML IDs" check to fail. The IDs aren't gone, they are in a different page. Do I still add them to removed-ids.txt?

StanFromIreland · 2026-09-02T12:40:20Z

Do I still add them to removed-ids.txt?

Yes, see the line with an asyncio file for the required format.

nedbat · 2026-09-10T23:19:13Z

I think this is done.

StanFromIreland · 2026-09-11T06:47:06Z

@nedbat can you please avoid force pushing, it makes it a little harder to review. See also the section in the Devguide.

nedbat · 2026-09-11T10:22:20Z

sorry, a habit from other repos.

merwok · 2026-09-11T11:13:23Z

+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


Is the second link required, if the first one already brings the reader to the right page?

(This reads to me like «Read Section A in Chapter 1», which is needed in books but not hypertext)

merwok · 2026-09-11T11:14:39Z

+
+.. seealso::

-Let the show begin!


Wasn’t this was harmless and a bit of flair?

The idea of starting a show was lost once all of the Availability sections were added. It's not clear to me at all that a reader at this point will be feeling like a show is starting. The sentence was a bit of flair, but isn't in the same tone as the rest of the section.

merwok · 2026-09-11T11:17:05Z

 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


Why not keep the random module link as an example of a random page? (and/or maybe a hint about a way to make random decision!)

Not fully sure what the original intent was here, but as we are in Library Reference and not Tutorial I don’t think the link was bad. Can you say why you removed it?

For two reasons: first, there are no page numbers the way most people read the docs (on the web). Second, for someone just becoming familiar with the stdlib, dropping them into the random module won't help them select a random page number.

merwok · 2026-09-11T11:18:04Z

-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


Should we say that some modules are written in C and compiled to importable modules, or is it confusing at this point?

I see what you mean, there are two dimensions of description here, but only two of the combinations are described. "Compiled into the interpreter" is the less interesting aspect. I've changed it to:

Most modules are written in Python,
but some are written in C. All can be imported into your program to add
functionality.

StanFromIreland

Overall looks good to me, although this will break quite a lot of translations, so please post an announcement in the Translations category of Discourse so that translators can recover them.

hugovk · 2026-09-11T18:14:59Z

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


Noting this (and similar */3/builtins/* links) will be 404 until the backports are done.

Would it be better to leave the old URLs and let the redirects handle it?

Since these are InternalDocs, I think that it's fine for them to be slightly broken for a day or two, and it saves us updating them in the future..

willingc

Overall, I like this @nedbat. I flagged a couple of places that rewriting the prose to be more direct may help the reader.

Thanks for doing this.

willingc · 2026-09-11T22:42:00Z

+semantics of the Python language, and :ref:`builtins-index` describes
+the built-ins, this library reference manual


With this addition of built-ins, it makes sense to rewrite this paragraph. I think it would be preferable to order the paragraph more directly:

State that "This library reference manual describes the standard library that is ...distributions."

Simplify the "While..." clause to state directly that the reference index and builtins index.

willingc · 2026-09-11T22:45:04Z

 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


Maybe "standard library modules"

I've rewritten and split these paragraphs, though tbh, we're repeating ourselves by having each section also mention what the other sections are.

nedbat requested review from AA-Turner, StanFromIreland, hugovk and willingc as code owners August 30, 2026 20:07

bedevere-app Bot added the awaiting core review label Aug 30, 2026

nedbat force-pushed the nedbat/split-builtin-stdlib branch from 37b2ad3 to 10c84e6 Compare August 30, 2026 20:10

nedbat added the skip issue label Aug 30, 2026

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/tools/templates/indexcontent.html Outdated

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/builtin-index.rst Outdated

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/index.rst

StanFromIreland reviewed Aug 30, 2026

View reviewed changes

Comment thread Doc/library/builtin-index.rst Outdated

nedbat added the skip news label Aug 30, 2026

hugovk reviewed Aug 31, 2026

View reviewed changes

StanFromIreland reviewed Aug 31, 2026

View reviewed changes

Comment thread Doc/reference/index.rst Outdated

nedbat added the docs Documentation in the Doc dir label Sep 1, 2026

github-project-automation Bot added this to Docs PRs Sep 1, 2026

github-project-automation Bot moved this to Todo in Docs PRs Sep 1, 2026

nedbat force-pushed the nedbat/split-builtin-stdlib branch from c6de373 to ea9966e Compare September 1, 2026 17:43

nedbat added 13 commits September 10, 2026 18:42

addressed Hugo's feedback

92babb2

update the What's Next page

c2dbc6e

one more wording tweak

cb15b64

move builtins to their own directory. fix the reference name

03f29d1

moved pages need to be noted in tools/removed-ids.txt

c28b536

add Python to the builtins reference title

58fa084

add sphinxext-rediraffe for the library->builtins split

45d2eeb

update check-html-ids to handle rediraffe redirects

2be0ba5

now we don't need (page missing) for the redirected pages

5f8e102

update other references to moved pages

d871e32

A seealso from builtins to library

485770d

make a nice section for rediraffe settings

b16e35b

move the builtins note to the end, as a seealso

016ce6b

nedbat force-pushed the nedbat/split-builtin-stdlib branch from 65aaf8b to 016ce6b Compare September 10, 2026 22:42

merwok reviewed Sep 11, 2026

View reviewed changes

encukou approved these changes Sep 11, 2026

View reviewed changes

Comment thread Doc/tools/check-html-ids.py

bedevere-app Bot added awaiting merge and removed awaiting core review labels Sep 11, 2026

StanFromIreland approved these changes Sep 11, 2026

View reviewed changes

hugovk approved these changes Sep 11, 2026

View reviewed changes

hugovk added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Sep 11, 2026

willingc approved these changes Sep 11, 2026

View reviewed changes

nedbat added 3 commits September 12, 2026 14:45

address merwok's comments

0ef2bd8

cache looking for ids in files

7caff5c

simplify the intro paragraphs

b3130e7

		semantics of the Python language, and :ref:`builtins-index` describes
		the built-ins, this library reference manual

Uh oh!

Uh oh!

Conversation

nedbat commented Aug 30, 2026

Uh oh!

nedbat commented Aug 30, 2026

Uh oh!

StanFromIreland commented Aug 30, 2026

Uh oh!

read-the-docs-community Bot commented Aug 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nedbat commented Aug 31, 2026

Uh oh!

StanFromIreland commented Aug 31, 2026

Uh oh!

nedbat commented Aug 31, 2026

Uh oh!

StanFromIreland commented Aug 31, 2026

Uh oh!

hugovk commented Sep 1, 2026

Uh oh!

nedbat commented Sep 1, 2026

Uh oh!

StanFromIreland commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nedbat commented Sep 2, 2026

Uh oh!

StanFromIreland commented Sep 2, 2026

Uh oh!

nedbat commented Sep 10, 2026

Uh oh!

StanFromIreland commented Sep 11, 2026

Uh oh!

nedbat commented Sep 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nedbat Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

read-the-docs-community Bot commented Aug 30, 2026 •

edited

Loading

StanFromIreland commented Sep 1, 2026 •

edited

Loading

nedbat Sep 12, 2026 •

edited

Loading