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
Table of Contents
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
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.
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('https://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('https://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
# Setting Different Timeouts for Connecting and Reading Requests import requests resp = requests.get('https://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('https://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('https://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:
- Imported the error from the exceptions module of the
- We created a
try-exceptblock to handle the
Frequently Asked Questions
None. There is no default timeout for Python requests, unless explicitly set using the
You set a timeout (in seconds) using the
timeout= parameter when making HTTP requests in the Python requests library.
While there is no best set value for timeouts for HTTP requests made in Python, a good practice is to set them under 500ms. This allows your application to provide a better user experience and to process more requests.
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
To learn more about related topics, check out the tutorials below: