Can the explanation of socket.connect() connection failures be rephrased? I don't think anybody understands what's written.

[jeffstearns]

Documentation

The documentation for the socket.connect() method has a tortured sentence that is very hard to understand. It's especially intractable for non-native English speakers. Can it be simplified?

The sentence is this:
If the connection is interrupted by a signal, the method waits until the connection completes, or raise a [TimeoutError](https://docs.python.org/3/library/exceptions.html#TimeoutError) on timeout, if the signal handler doesn’t raise an exception and the socket is blocking or has a timeout.

Can this be rephrased as two simpler sentences? I'm happy to propose that rewrite if somebody could add a comment here explaining what this sentence actually means. thx

Linked PRs

• gh-132819: Clarify socket.connect() signal interruption behavior #155022

[vadmium]

That sentence is trying to describe the how Python will retry operating system calls that return EINTR. See commit 81c41db, Git Hub issue #67806, and PEP 475 for the background.

It sounds like the behaviour is:

• In general, the socket.connect method waits for the connection to succeed, and then returns with no error nor exception
• The method stops waiting and raises TimeoutError if the Python socket object has a timeout set which is exceeded
• If the thread is interrupted by an OS signal, Python will eventually run the associated Python signal handler. A Python signal handler can also cause the method to stop waiting and raise an exception.
• If the thread was interrupted, but the Python handler (if any) did not raise an exception, the behaviour depends on the blocking or timeout mode of the Python socket object:
  • In non-blocking mode, with the timeout set to zero, InterruptedError is raised
  • In blocking or timeout mode (with an indefinite or non-zero timeout set), the method continues and waits for the connection to succeed, without raising an exception