[Docs] Clarify behavior of timeout parameter in requests.get

[MA-Hamodi]

Description

The current documentation for the timeout parameter in requests.get() does not clearly explain that it applies to both connection and read timeouts unless specified otherwise.

This can be confusing for users who expect it to behave as a total request timeout.

Suggested Improvement

Add clarification in the docs that:

• A single float applies to both connect and read timeouts
• A tuple can be used to specify them separately

Example:

requests.get(url, timeout=(connect_timeout, read_timeout))

[nateprewitt]

Hi @HamodiGit,

Could you clarify where you're seeing information that's unclear?

requests.get() documents:

requests/src/requests/api.py

Line 68 in ef439eb

:param \*\*kwargs: Optional arguments that ``request`` takes.

and requests.request() documents:

:param timeout: (optional) How many seconds to wait for the server to send data
before giving up, as a float, or a :ref:(connect timeout, read timeout) <timeouts> tuple.
:type timeout: float or tuple

The timeout docs themselves cover this quite extensively as well.

[scalebuds]

Confirming the confusion here — the current docs say "timeout" without distinguishing connect vs read, which trips up users expecting a total timeout similar to curl --max-time.

Tested this locally:

import requests

# This applies 3s to BOTH connect and read separately (not total)
r = requests.get(url, timeout=3)

# This gives 2s connect, 5s read
r = requests.get(url, timeout=(2, 5))

Suggested doc addition under the timeout param:

Note: timeout is not a time limit on the entire response download. It applies separately to the connection phase and the read phase. Use a tuple (connect, read) to set them independently. There is no built-in total timeout — wrap in a thread or use a library like httpx if you need one.

This would save a lot of debugging time for newcomers.