SocketType documentation misleading

[srittau]

BPO	44261
Nosy	@srittau, @JelleZijlstra

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-05-28.15:21:42.596>
labels = ['docs']
title = 'SocketType documentation misleading'
updated_at = <Date 2021-05-29.23:00:46.252>
user = 'https://github.com/srittau'

bugs.python.org fields:

activity = <Date 2021-05-29.23:00:46.252>
actor = 'JelleZijlstra'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-05-28.15:21:42.596>
creator = 'srittau'
dependencies = []
files = []
hgrepos = []
issue_num = 44261
keywords = []
message_count = 2.0
messages = ['394665', '394743']
nosy_count = 3.0
nosy_names = ['srittau', 'docs@python', 'JelleZijlstra']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue44261'
versions = []

Linked PRs

• gh-88427: Deprecate socket.SocketType #126272

[srittau]

The documentation of socket.SocketType (https://docs.python.org/3/library/socket.html?highlight=sockettype#socket.SocketType) is misleading. It states:

This is a Python type object that represents the socket object type. It is the same as type(socket(...)).

This is untrue. socket.SocketType is in reality re-exported from _socket, where it is an alias for class _socket.socket, a super type of class socket.socket. I think that either the documentation should be fixed, or SocketType should be moved to socket and made an alias of socket.socket.

[JelleZijlstra]

I propose to deprecate socket.SocketType. There's no reason to publicly expose _socket.socket separately from socket.socket, the only type that moat users should care about.

SocketType isn't needed for type checking; socket.socket is itself a class and can be used in type annotations.