Timeouts in Python requests

In this tutorial, you’ll learn how to use timeouts in the Python requests library, when working with any type of HTTP request being made. By default, the requests library will not time out any request you make, which can result in your programming running indefinitely if a server doesn’t respond.

By the end of this tutorial, you’ll have learned:

• How to set timeouts in requests
• How to set unique timeouts for connecting and reading in Python requests
• How to catch and handle timeout errors in Python requests

How Does Python requests Handle Timeouts?

By default, the Python requests library does not set a timeout for any request it sends. This is true for GET, POST, and PUT requests. While this can prevent unexpected errors, it can result in your request running indefinitely.

Because of this, it’s important to set a timeout to prevent unexpected behavior. Remember, the Python requests library will not timeout by default, unless explicitly instructed.

How to Set a Timeout for Python requests

In order to set a timeout in an HTTP request made via the requests library, you can use the timeout parameter. The parameter accepts either an integer or a floating point value, which describes the time in seconds.

It’s important to note that this behavior is different from many other HTTP request libraries, such as those in JavaScript. In other libraries or languages, this behavior tends to be expressed in milliseconds.

Let’s take a look at an example of how we can send a GET request with a timeout:

# Setting a Timeout on a GET Request with an Integer
import requests
resp = requests.get('http://datagy.io', timeout=3)

In the example above, we set a timeout of 3 seconds. We used an integer to represent the time of our timeout. If we wanted to be more precise, we could also pass in a floating point value:

# Setting a Timeout on a GET Request with a Floating Point Value
import requests
resp = requests.get('http://datagy.io', timeout=3.5)

By passing in a single value, we set a timeout for the request. If we wanted to set different timeouts for connecting and reading a request, we can pass in a tuple of values.

How to Set Timeouts for Connecting and Reading in Python requests

In some cases, you’ll want to set different timeouts for making a connection and for reading results. This can easily be done using the timeout parameter in the requests library. Similar to the example above, this can be applied to any type of request being made.

Let’s see how we can pass in different timeout limits for connecting and reading requests in the Python requests library:

# Setting Different Timeouts for Connecting and Reading Requests
import requests
resp = requests.get('http://datagy.io', timeout=(1, 2))

In the example above, we set the request to timeout after 1 second for connecting and 2 seconds for reading the request.

In the following section, you’ll learn how to catch and handle errors that arise due to requests timing out.

How to Catch and Handle Timeout Errors in Python requests

When applying a timeout, it’s important to note that this is not a time limit on the entire response. Instead, it raises an exception if no bytes have been received on the underlying socket.

If the request does not receive any bytes within the specified timeout limit, a Timeout error is raised. Let’s see what this looks like:

# Raising a Timeout Error in a Python requests GET Request
import requests
resp = requests.get('http://datagy.io', timeout=0.0001)

# Raises:
# ConnectTimeoutError(<urllib3.connection.HTTPSConnection object at 0x7fbc988f59a0>, 'Connection to datagy.io timed out. (connect timeout=0.0001)')

In order to prevent your program from crashing, you need to handle the exception using a try-except block. Let’s see how this can be done:

# Handling a Timeout Error
import requests
from requests.exceptions import ConnectTimeout

try:
    requests.get('http://datagy.io', timeout=0.0001)
except ConnectTimeout:
    print('Request has timed out')

# Returns:
# Request has timed out

We can see in the code above that the error was handled safely. In order to do this, we:

1. Imported the error from the exceptions module of the requests library
2. We created a try-except block to handle the ConnectTimeout error.

Frequently Asked Questions

Conclusion

In this tutorial, you learned how to handle timeouts in the Python requests library. You first learned how the Python requests library handles timeouts. Then, you learned how to set timeouts when making HTTP requests, both using integers and floating point values. Then, you learned how to specify specific timeouts for connecting and reading requests. Finally, you learned how to handle timeout exceptions in the Python requests library.

Additional Resources

To learn more about related topics, check out the tutorials below:

• Python Requests Response Object Explained
• Python Requests Headers Explained
• Python Requests Sessions Explained
• Official Documentation: Python requests Timeout