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 #32939334 | 📁 Comparing f1bb611 against main (2f8f569)

🔍 Preview build

4 files changed

± library/array.html
± library/socket.html
± whatsnew/3.16.html
± whatsnew/changelog.html

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.

vstinner · 2026-06-01T11:06:10Z



-.. data:: SocketType
+.. class:: SocketType


You should move the declaration at https://docs.python.org/dev/library/socket.html#socket-objects and convert methods documentation to .. method: format.

vstinner · 2026-06-01T15:31:10Z

+   ``isinstance(socket(...), SocketType)`` is true, but ``SocketType`` is not
+   the same as ``type(socket(...))``, which is :class:`~socket.socket` itself.
+
 Socket objects have the following methods.  Except for


For the methods below, you should add an indentation of 3 spaces, and replace .. method:: socket.xxx(...) with .. method:: xxx(...) (remove socket. prefix).

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.

vstinner · 2026-06-02T09:48:34Z


+      .. versionchanged:: 3.6
+         :exc:`OSError` is now raised if an error occurs when the underlying
+         :c:func:`close` call is made.


Suggested change

:c:func:`close` call is made.

:c:meth:`close` call is made.

vstinner · 2026-06-02T09:49:05Z


-   .. availability:: not WASI.
+      Like ``connect(address)``, but return an error indicator instead of raising an
+      exception for errors returned by the C-level :c:func:`connect` call (other


Suggested change

exception for errors returned by the C-level :c:func:`connect` call (other

exception for errors returned by the C-level :c:func:`!connect` call (other

vstinner · 2026-06-02T09:50:27Z

+      inside the buffer provided it has not been truncated before the
+      start of its associated data.
+
+      On systems which support the :const:`SCM_RIGHTS` mechanism, the


Suggested change

On systems which support the :const:`SCM_RIGHTS` mechanism, the

On systems which support the :const:`!SCM_RIGHTS` mechanism, the

vstinner · 2026-06-02T09:51:25Z


+      The following function sends the list of file descriptors *fds*
+      over an :const:`AF_UNIX` socket, on systems which support the
+      :const:`SCM_RIGHTS` mechanism.  See also :meth:`recvmsg`. ::


Suggested change

:const:`SCM_RIGHTS` mechanism. See also :meth:`recvmsg`. ::

:const:`!SCM_RIGHTS` mechanism. See also :meth:`recvmsg`. ::

vstinner · 2026-06-02T09:51:49Z

+      case it is up to the caller to ensure that the bytestring contains the
+      proper bits (see the optional built-in module :mod:`struct` for a way to
+      encode C structures as bytestrings). When *value* is set to ``None``,
+      *optlen* argument is required. It's equivalent to calling :c:func:`setsockopt` C


Suggested change

*optlen* argument is required. It's equivalent to calling :c:func:`setsockopt` C

*optlen* argument is required. It's equivalent to calling :c:func:`!setsockopt` C

vstinner · 2026-06-02T09:52:12Z


-Note that there are no methods :meth:`read` or :meth:`write`; use
-:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
+   Note that there are no methods :meth:`read` or :meth:`write`; use


Suggested change

Note that there are no methods :meth:`read` or :meth:`write`; use

Note that there are no methods :meth:`!read` or :meth:`!write`; use

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

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

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

	exception for errors returned by the C-level :c:func:`connect` call (other
	exception for errors returned by the C-level :c:func:`!connect` call (other

	On systems which support the :const:`SCM_RIGHTS` mechanism, the
	On systems which support the :const:`!SCM_RIGHTS` mechanism, the

	:const:`SCM_RIGHTS` mechanism. See also :meth:`recvmsg`. ::
	:const:`!SCM_RIGHTS` mechanism. See also :meth:`recvmsg`. ::

	optlen argument is required. It's equivalent to calling :c:func:`setsockopt` C
	optlen argument is required. It's equivalent to calling :c:func:`!setsockopt` C

	Note that there are no methods :meth:`read` or :meth:`write`; use
	Note that there are no methods :meth:`!read` or :meth:`!write`; use

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vstinner left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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