python / python/cpython

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

Open
#132,819 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs topic-socket
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the socket.connect() documentation entry and read the surrounding discussion of interrupted connections, signal handlers, blocking sockets, timeouts, and TimeoutError. Confirm the sentence's meaning before proposing two simpler sentences that preserve all of those conditions. Done means the explanation is accurate, clearer for non-native English speakers, and reflected in the linked documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.