Skip to content

gh-89554: Document socket.SocketType as a class#150683

Open
gaborbernat wants to merge 6 commits into
python:mainfrom
gaborbernat:gh-89554-socket-class-roles
Open

gh-89554: Document socket.SocketType as a class#150683
gaborbernat wants to merge 6 commits into
python:mainfrom
gaborbernat:gh-89554-socket-class-roles

Conversation

@gaborbernat
Copy link
Copy Markdown
Contributor

@gaborbernat gaborbernat commented May 31, 2026 •
edited
Loading

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.

@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels May 31, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs May 31, 2026
@bedevere-app bedevere-app Bot mentioned this pull request May 31, 2026
Open
@gaborbernat gaborbernat mentioned this pull request May 31, 2026
Closed
@gaborbernat
Copy link
Copy Markdown
Contributor Author

gaborbernat commented May 31, 2026

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
Copy link
Copy Markdown

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

Documentation build overview

📚 cpython-previews | 🛠️ Build #32992166 | 📁 Comparing cbac027 against main (2f8f569)

  🔍 Preview build  

81 files changed · + 1 added · ± 80 modified

+ Added

± Modified

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

gaborbernat commented May 31, 2026

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
Copy link
Copy Markdown
Contributor Author

gaborbernat commented Jun 1, 2026

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

vstinner
vstinner reviewed Jun 1, 2026
View reviewed changes
Comment thread Doc/library/socket.rst Outdated
@gaborbernat gaborbernat force-pushed the gh-89554-socket-class-roles branch from 0ad690a to d89fe9f Compare June 1, 2026 15:05
vstinner
vstinner reviewed Jun 1, 2026
View reviewed changes
Comment thread Doc/library/socket.rst Outdated
@gaborbernat gaborbernat marked this pull request as draft June 1, 2026 16:26
@gaborbernat
pythongh-89554: Document socket.SocketType as a class
f1bb611 
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.
@gaborbernat gaborbernat force-pushed the gh-89554-socket-class-roles branch from d89fe9f to f1bb611 Compare June 1, 2026 16:35
@gaborbernat gaborbernat marked this pull request as ready for review June 1, 2026 16:46
@gaborbernat gaborbernat requested a review from vstinner June 2, 2026 04:39
vstinner
vstinner reviewed Jun 2, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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
pythongh-89554: Apply review suggestions for socket roles
d6e298f 
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.
@gaborbernat gaborbernat requested a review from vstinner June 3, 2026 13:50
vstinner
vstinner reviewed Jun 4, 2026
View reviewed changes
Comment thread Doc/library/socket.rst Outdated
Comment thread Doc/library/socket.rst Outdated
@gaborbernat
Document SocketType as a class without restructuring the socket methods
c08bf8c 
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(...))`.
@gaborbernat gaborbernat requested a review from vstinner June 4, 2026 13:38
@gaborbernat
Revert "Document SocketType as a class without restructuring the sock…
a6103c4 
…et methods"

This reverts commit c08bf8c.
@gaborbernat
Move SocketType after the socket class
9e719a9 
Per review, document SocketType after the socket class rather than before it.
@gaborbernat
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vstinner vstinner Awaiting requested review from vstinner

Assignees

No one assigned

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@gaborbernat @vstinner