Skip to content

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

Open
gaborbernat wants to merge 1 commit into
python:mainfrom
gaborbernat:gh-89554-socket-class-roles
Open

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

Conversation

@gaborbernat
Copy link
Copy Markdown
Contributor

@gaborbernat gaborbernat commented May 31, 2026

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

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

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

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

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

Comment thread Doc/library/socket.rst Outdated


.. data:: SocketType
.. class:: SocketType
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

@gaborbernat gaborbernat force-pushed the gh-89554-socket-class-roles branch from 0ad690a to d89fe9f Compare June 1, 2026 15:05
Comment thread Doc/library/socket.rst Outdated
``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
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

@gaborbernat gaborbernat marked this pull request as draft June 1, 2026 16:26
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
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

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

Choose a reason for hiding this comment

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

Suggested change
:c:func:`close` call is made.
:c:meth:`close` call is made.

Comment thread Doc/library/socket.rst

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

Choose a reason for hiding this comment

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

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

Comment thread Doc/library/socket.rst
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
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread Doc/library/socket.rst

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`. ::
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread Doc/library/socket.rst
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
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

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

Comment thread Doc/library/socket.rst

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

Choose a reason for hiding this comment

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

2 participants