gh-89554: Document socket.SocketType as a class by gaborbernat · Pull Request #150683 · python/cpython

gaborbernat · 2026-05-31T17:25:19Z

socket.SocketType is a class, but the documentation marks it with the .. data:: directive, so :class: cross-references to it cannot resolve against a py:class target.

This switches the entry to .. class::. It also corrects the description: SocketType is re-exported from _socket as an alias of _socket.socket, the base class of socket.socket, so isinstance(socket(...), SocketType) is true while type(socket(...)) is socket.socket itself. The current wording, "the same as type(socket(...))", is the misleading text reported in gh-88427.

This overlaps with #93288, which corrects the same sentence but keeps .. data::. This PR combines that wording fix with the role fix.

Refs: gh-89554, gh-88427. Documentation-only change, so no Misc/NEWS entry (skip news).

This file is not covered by CODEOWNERS, so cc @vstinner, who reviews most socket changes.

gaborbernat · 2026-05-31T17:29:55Z

For context, I am aware of gh-88427 (the SocketType documentation being called misleading) and the open deprecation proposal in #126272. This change is limited to the directive role: it switches .. data:: to .. class:: so existing :class: cross-references resolve, and leaves the deprecation question untouched. While SocketType remains public it should carry the correct role; if it is deprecated later, this can be revisited.

read-the-docs-community · 2026-05-31T17:34:06Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33011804 | 📁 Comparing 9039fd2 against main (2f8f569)

🔍 Preview build

83 files changed · + 1 added · ± 82 modified

+ Added

howto/abi3t-migration.html

± Modified

gaborbernat · 2026-05-31T17:35:03Z

Amended: this now also corrects the misleading description (SocketType is the base class of socket.socket, not type(socket(...))), addressing gh-88427. That overlaps with #93288, which fixes the wording alone; this combines it with the role change.

gaborbernat · 2026-06-01T03:55:17Z

Backward-compatibility check. No independent :data: references were found, and SocketType is already proposed for deprecation (gh-88427). Minimal breakage.

socket.SocketType is a class (re-exported from _socket as an alias of _socket.socket, the base class of socket.socket), but was documented with the ".. data::" directive, so ":class:" cross-references to it cannot resolve against a py:class target. Switch the entry to ".. class::", correct the misleading description (SocketType is the base class of the socket type, not "type(socket(...))" which is socket.socket; addresses pythongh-88427), move it into the Socket Objects section, and document the socket object methods and attributes nested under the socket class, dropping the redundant "socket." prefix.

vstinner

Ah thank you! The rendered documentation is much better like that!

There is now a bunch of warnings on the documentation, such as: "c:func reference target not found: connect [ref.func]". I suggested fixes.

Suppress C-domain cross-references that have no target by using the non-link form (``:c:func:`!connect```, ``!setsockopt``, ``!SCM_RIGHTS``) and mark the absent ``read``/``write`` methods as non-links, as suggested in review. The underlying ``close`` call refers to the C library function, so use ``:c:func:`!close``` rather than a Python method role.

Drop the Socket Objects restructure and the second `.. class:: socket` that required `:noindex:`. Keep only the change of `SocketType` from `.. data::` to `.. class::`, in its original place after the `socket` class, with a corrected description: SocketType is the base class of socket re-exported from _socket, not `type(socket(...))`.

…et methods" This reverts commit c08bf8c.

Per review, document SocketType after the socket class rather than before it.

Drop :noindex: from the socket class in Socket Objects so socket.socket is indexed where its methods are documented, and add :noindex: to the constructor entry to avoid a duplicate object description.

socket() appeared both as a function in the Functions section and as a class in Socket Objects, which is confusing. Move the constructor signature and description onto the socket.socket class in Socket Objects, and leave a cross-reference under Creating sockets so socket() stays listed among the socket-creating helpers.

vstinner

LGTM.

miss-islington-app · 2026-06-10T13:01:24Z

Thanks @gaborbernat for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

bedevere-app · 2026-06-10T13:01:45Z

GH-151244 is a backport of this pull request to the 3.15 branch.

miss-islington-app · 2026-06-10T13:02:13Z

Thanks @gaborbernat for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

miss-islington-app · 2026-06-10T13:02:14Z

Thanks @gaborbernat for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

miss-islington-app · 2026-06-10T13:02:17Z

Sorry, @gaborbernat and @vstinner, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker a621e8ad811e7d51d69b0969a2bd07888a02db1e 3.13

miss-islington-app · 2026-06-10T13:02:22Z

Sorry, @gaborbernat and @vstinner, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker a621e8ad811e7d51d69b0969a2bd07888a02db1e 3.14

bedevere-app · 2026-06-10T13:07:02Z

GH-151245 is a backport of this pull request to the 3.14 branch.

vstinner · 2026-06-10T13:07:22Z

Merged. Thanks for your contribution.

…151244) gh-89554: Document socket.SocketType as a class (GH-150683) socket.SocketType is a class (re-exported from _socket as an alias of _socket.socket, the base class of socket.socket), but was documented with the ".. data::" directive, so ":class:" cross-references to it cannot resolve against a py:class target. Switch the entry to ".. class::", correct the misleading description (SocketType is the base class of the socket type, not "type(socket(...))" which is socket.socket; addresses gh-88427), move it into the Socket Objects section, and document the socket object methods and attributes nested under the socket class, dropping the redundant "socket." prefix. (cherry picked from commit a621e8a) Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

…1245) gh-89554: Document socket.SocketType as a class (#150683) socket.SocketType is a class (re-exported from _socket as an alias of _socket.socket, the base class of socket.socket), but was documented with the ".. data::" directive, so ":class:" cross-references to it cannot resolve against a py:class target. Switch the entry to ".. class::", correct the misleading description (SocketType is the base class of the socket type, not "type(socket(...))" which is socket.socket; addresses gh-88427), move it into the Socket Objects section, and document the socket object methods and attributes nested under the socket class, dropping the redundant "socket." prefix. (cherry picked from commit a621e8a) Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

#151245) (#151254) [3.14] gh-89554: Document socket.SocketType as a class (#150683) (#151245) gh-89554: Document socket.SocketType as a class (#150683) socket.SocketType is a class (re-exported from _socket as an alias of _socket.socket, the base class of socket.socket), but was documented with the ".. data::" directive, so ":class:" cross-references to it cannot resolve against a py:class target. Switch the entry to ".. class::", correct the misleading description (SocketType is the base class of the socket type, not "type(socket(...))" which is socket.socket; addresses gh-88427), move it into the Socket Objects section, and document the socket object methods and attributes nested under the socket class, dropping the redundant "socket." prefix. Backport to 3.13: Replace ":platform: Windows" with ".. availability:: Windows" in ioctl() method. (cherry picked from commit a621e8a) (cherry picked from commit 4ef6a37) Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

bedevere-app Bot added docs Documentation in the Doc dir skip news labels May 31, 2026

github-project-automation Bot added this to Docs PRs May 31, 2026

github-project-automation Bot moved this to Todo in Docs PRs May 31, 2026

bedevere-app Bot mentioned this pull request May 31, 2026

Intersphinx inventory classifies some type-like objects as data #89554

Open

bedevere-app Bot added the awaiting review label May 31, 2026

gaborbernat mentioned this pull request May 31, 2026

gh-89554: Document socket, thread and expat type objects as classes #150681

Closed

gaborbernat force-pushed the gh-89554-socket-class-roles branch from 79787b0 to 0ad690a Compare May 31, 2026 17:34

vstinner reviewed Jun 1, 2026

View reviewed changes

Comment thread Doc/library/socket.rst Outdated

gaborbernat force-pushed the gh-89554-socket-class-roles branch from 0ad690a to d89fe9f Compare June 1, 2026 15:05

vstinner reviewed Jun 1, 2026

View reviewed changes

Comment thread Doc/library/socket.rst Outdated

gaborbernat marked this pull request as draft June 1, 2026 16:26

bedevere-app Bot removed the awaiting review label Jun 1, 2026

gaborbernat force-pushed the gh-89554-socket-class-roles branch from d89fe9f to f1bb611 Compare June 1, 2026 16:35

gaborbernat marked this pull request as ready for review June 1, 2026 16:46

bedevere-app Bot added the awaiting review label Jun 1, 2026

gaborbernat requested a review from vstinner June 2, 2026 04:39

vstinner reviewed Jun 2, 2026

View reviewed changes

Comment thread Doc/library/socket.rst Outdated

Comment thread Doc/library/socket.rst Outdated

Comment thread Doc/library/socket.rst Outdated

Comment thread Doc/library/socket.rst Outdated

Comment thread Doc/library/socket.rst Outdated

Comment thread Doc/library/socket.rst Outdated

gaborbernat requested a review from vstinner June 3, 2026 13:50

vstinner reviewed Jun 4, 2026

View reviewed changes

Comment thread Doc/library/socket.rst Outdated

Comment thread Doc/library/socket.rst Outdated

gaborbernat requested a review from vstinner June 4, 2026 13:38

gaborbernat added 2 commits June 4, 2026 06:43

Revert "Document SocketType as a class without restructuring the sock…

a6103c4

…et methods" This reverts commit c08bf8c.

Move SocketType after the socket class

9e719a9

Per review, document SocketType after the socket class rather than before it.

Index socket.socket on the methods entry, not the constructor

cbac027

Drop :noindex: from the socket class in Socket Objects so socket.socket is indexed where its methods are documented, and add :noindex: to the constructor entry to avoid a duplicate object description.

vstinner reviewed Jun 5, 2026

View reviewed changes

Comment thread Doc/library/socket.rst Outdated

gaborbernat requested a review from vstinner June 5, 2026 17:44

vstinner approved these changes Jun 8, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels Jun 8, 2026

vstinner merged commit a621e8a into python:main Jun 10, 2026
34 checks passed

bedevere-app Bot removed the awaiting merge label Jun 10, 2026

github-project-automation Bot moved this from Todo to Done in Docs PRs Jun 10, 2026

vstinner added the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jun 10, 2026

bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jun 10, 2026

vstinner added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jun 10, 2026

miss-islington-app Bot assigned vstinner Jun 10, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jun 10, 2026

vstinner removed the needs backport to 3.13 bugs and security fixes label Jun 10, 2026

vstinner mentioned this pull request Jun 10, 2026

[3.13][3.14] gh-89554: Document socket.SocketType as a class (#150683) (#151245) #151254

Merged

Uh oh!

Conversation

gaborbernat commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gaborbernat commented May 31, 2026

Uh oh!

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

Uh oh!

Documentation build overview

Uh oh!

gaborbernat commented May 31, 2026

Uh oh!

gaborbernat commented Jun 1, 2026

Uh oh!

Uh oh!

Uh oh!

vstinner 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!

Uh oh!

vstinner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Jun 10, 2026

Uh oh!

bedevere-app Bot commented Jun 10, 2026

Uh oh!

miss-islington-app Bot commented Jun 10, 2026

Uh oh!

miss-islington-app Bot commented Jun 10, 2026

Uh oh!

miss-islington-app Bot commented Jun 10, 2026

Uh oh!

miss-islington-app Bot commented Jun 10, 2026

Uh oh!

bedevere-app Bot commented Jun 10, 2026

Uh oh!

vstinner commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gaborbernat commented May 31, 2026 •

edited

Loading

read-the-docs-community Bot commented May 31, 2026 •

edited

Loading