Replace custom exceptions for timeouts with TimeoutError

[tiran]

BPO	42413
Nosy	@brianquinlan, @pitrou, @vstinner, @tiran, @alex, @asvetlov, @serhiy-storchaka, @1st1, @dstufft, @applio, @corona10, @miss-islington, @kumaraditya303
PRs	bpo-42413: socket.timeout is now an alias of TimeoutError #23413 bpo-42413: Replace concurrent.futures.TimeoutError and asyncio.TimeoutError with builtin TimeoutError #23520 bpo-42413: Replace concurrent.futures.TimeoutError and asyncio.TimeoutError with builtin TimeoutError #30197

^{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 = 'https://github.com/asvetlov'
closed_at = <Date 2021-12-19.11:38:06.321>
created_at = <Date 2020-11-19.19:10:42.609>
labels = ['extension-modules', '3.11', 'type-feature', 'library', 'expert-asyncio']
title = 'Replace custom exceptions for timeouts with TimeoutError'
updated_at = <Date 2021-12-19.11:38:06.320>
user = 'https://github.com/tiran'

bugs.python.org fields:

activity = <Date 2021-12-19.11:38:06.320>
actor = 'asvetlov'
assignee = 'asvetlov'
closed = True
closed_date = <Date 2021-12-19.11:38:06.321>
closer = 'asvetlov'
components = ['Extension Modules', 'Library (Lib)', 'asyncio']
creation = <Date 2020-11-19.19:10:42.609>
creator = 'christian.heimes'
dependencies = []
files = []
hgrepos = []
issue_num = 42413
keywords = ['patch']
message_count = 20.0
messages = ['381454', '381466', '381539', '381552', '381553', '381554', '381555', '381556', '381557', '381558', '381559', '381560', '381562', '381568', '381663', '381664', '381886', '404693', '408893', '408894']
nosy_count = 14.0
nosy_names = ['bquinlan', 'janssen', 'pitrou', 'vstinner', 'christian.heimes', 'alex', 'asvetlov', 'serhiy.storchaka', 'yselivanov', 'dstufft', 'davin', 'corona10', 'miss-islington', 'kumaraditya']
pr_nums = ['23413', '23520', '30197']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue42413'
versions = ['Python 3.11']

[tiran]

The socket module has a custom timeout exception "socket.timeout". The exception is documented https://docs.python.org/3/library/socket.html#socket.timeout as :

A subclass of OSError, this exception is raised when a timeout occurs on a socket which has had timeouts enabled via a prior call to settimeout() (or implicitly through setdefaulttimeout()).

It's a distinct exception type and not the same as the global TimeoutError.

>>> import socket
>>> socket.timeout == TimeoutError
False

I like to follow the example of the deprecated "socket.error", replace the custom exception and make it an alias of TimeoutError. The risk is minimal. Both exceptions are subclasses of OSError.

The change would not only make exception handling more consistent. It would also allow me to simplify some code in ssl and socket C code. I might even be able to remove the socket CAPI import from _ssl.c completely.

[miss-islington]

New changeset 03c8ddd by Christian Heimes in branch 'master':
bpo-42413: socket.timeout is now an alias of TimeoutError (GH-23413)
03c8ddd

[serhiy-storchaka]

There are also other distinct exceptions:

multiprocessing.TimeoutError
concurrent.futures.TimeoutError
asyncio.TimeoutError

[tiran]

Thanks Serhiy!

Andrew, Antoine, Yury, do you want to replace the custom Timeout exceptions in asyncio, multiprocessing, and concurrent with global TimeoutError, too?

[asvetlov]

In futures and asyncio TimeoutError has no errno.

I'm not sure should we care but I consider it as a show stopper.

On another hand, two distinct timeout classes confuse people. I had many conversions about this during the aiohttp support. asyncio can raise both TimeoutError and asyncio.TimeoutError which is... unexpected at least.

[tiran]

PyErr_SetString(PyErr_TimeoutError, "msg") and raise TimeoutError("msg") do not set any additional exception attributes. errno, strerror, filename, and filename2 are None:

>>> try:
...     raise TimeoutError("msg")
... except Exception as e:
...     err = e
... 
>>> err
TimeoutError('msg')
>>> (err.errno, err.filename, err.filename2, err.strerror)
(None, None, None, None)

Is that a problem?

[asvetlov]

Perhaps it is a good compromise.
OSError-derived class without errno looks getter to me that different incompatible TimeoutError classes.

How many exceptions inherited from OSError have no errno set? Do we have a precedent in stdlib at all already?

[serhiy-storchaka]

Yes, I think this is a problem. It is expected that an instance of OSError has valid errno. OSError is a merge of several old exception types, some of them did have errno, and others did not.

Maybe add BaseTimeoutError and make TimeoutError a subclass of BaseTimeoutError and OSError?

There as also several CancelledError, and exceptions with similar names and purpose, like asyncio.IncompleteReadError and http.client.IncompleteRead.

[tiran]

They have an errno attribute, it's just to None by default. You have to call OSError with multiple arguments to set errno to a non-None value.