gh-89554: Document socket.SocketType as a class#150683
Conversation
|
For context, I am aware of gh-88427 (the |
Documentation build overview
18 files changed ·
|
gaborbernat
force-pushed
the
gh-89554-socket-class-roles
branch
from
79787b0 to
0ad690a
Compare
|
Backward-compatibility check. No independent |
|
|
||
|
|
||
| .. data:: SocketType | ||
| .. class:: SocketType |
There was a problem hiding this comment.
You should move the declaration at https://docs.python.org/dev/library/socket.html#socket-objects and convert methods documentation to .. method: format.
gaborbernat
force-pushed
the
gh-89554-socket-class-roles
branch
from
0ad690a to
d89fe9f
Compare
| ``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 |
There was a problem hiding this comment.
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.
gaborbernat
force-pushed
the
gh-89554-socket-class-roles
branch
from
d89fe9f to
f1bb611
Compare
vstinner
left a comment
vstinner
left a comment
There was a problem hiding this comment.
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.
2 participants
socket.SocketTypeis 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:SocketTypeis re-exported from_socketas an alias of_socket.socket, the base class ofsocket.socket, soisinstance(socket(...), SocketType)is true whiletype(socket(...))issocket.socketitself. The current wording, "the same astype(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/NEWSentry (skip news).This file is not covered by CODEOWNERS, so cc @vstinner, who reviews most socket changes.