Proposal: Add a Global Timeout Setting in httpx

[andybbruno]

Current Workaround:

Currently, the only way to set a global timeout in httpx across all clients and requests is by directly modifying the internal _config object. In my case, I added the following code to the main __init__.py file:

import httpx
httpx._config.DEFAULT_TIMEOUT_CONFIG = httpx.Timeout(timeout=12.3)

While this workaround achieves the goal of setting a default timeout, it raises several concerns about whether this is good practice, as it modifies internal variables, which is not ideal for production use (it might break the code).

Proposal for Improvement:

1. Expose a Public API for Global Configuration

httpx.DEFAULT_TIMEOUT_CONFIG = httpx.Timeout(timeout=12.3)

2. Introduce a Method to Set Global Defaults

httpx.set_global_timeout(timeout=12.3)

Looking forward to hearing everyone’s thoughts! 😊

[zanieb]

This is being actively discussed for v1.0 (e.g. #3344 (comment))

[zanieb]

Oh sorry, I actually misread your issue. I thought this was a total request timeout but you're asking for configuration for all clients. I don't believe this is being discussed for v1.0. I do think there are some previous discussion... (I can't find them though)

[andrea-bruno-moov]

I couldn't find anything in this repo, so I asked. Nevertheless, you're right, I want a global ‘setter’ that replaces the current global default timeout (at the moment it is 5 seconds)

[andrea-bruno-moov]

FYI: this need arose after I was asked to modify all timeouts within a project. As you can imagine, it's a very tedious task for a rather easy problem, isn't it?

[zanieb]

Mutating global state always feels easier than it ends up being.

[andrea-bruno-moov]

It is, but does it really work? At first sight, I do see it working, but does the import order matter in httpx? What happens if I set this value, for example, in a subdirectory (not in the main __init__.py file)? Also, is there a more elegant way to achieve this?

[andybbruno]

#3357

I opened a PR to quickly solve this 😊

[tomchristie]

Looking forward to hearing everyone’s thoughts!

Well now. You've hit on an interesting point.

Here's how I'd ideally like the API to be...

client = httpx.Client(timeout=httpx.Timeout(complete=60.0))

I'd also ideally like to drop constants from inside the codebase such as DEFAULT_TIMEOUT_CONFIG, in favour of specifying a default explicitly in the signature. This removes the temptation to import private implementation details, is more direct, and likely gives better code hints in some editors.

It's interesting that we're getting "global xyz" requests. I'm curious why the pattern of "single client instance" isn't used instead. Perhaps we're not being clear enough about this in the docs? Perhaps the "quickstart" API is leading our users away from client configuration and reuse?

[andybbruno]

The problem is that I have a lot of httpx calls like these:

import httpx
httpx.get(...) # no client here
httpx.post(...) # no client here

So, the quickest way to modify all of them in one shot, was to set this timeout globally (using the DEFAULT_TIMEOUT_CONFIG constant). At the same time, however, I agree that modifying a constant is a bit ugly

[andybbruno]

Another approach would be to set this timeout as a context variable like in the Decimal library (in this case we set the precision)

[karpetrosyan]

I think you should always prefer to configure a single client and make your requests using that client, as it has several advantages:

• You are reusing already opened connections (connection pooling).
• It's easier to control your application's requests when you have a single gateway for all of them, making configurations like timeouts, proxies, or middlewares much simpler.
• Creating a new client for each request (as happens when you call httpx.get) is slow and resource-intensive.

Right now, it's about timeouts, but when you need to configure proxies or add logging or some custom logic for all of your requests, you will encounter many problems with your current implementation. Therefore, I suggest using httpx.Client/httpx.AsyncClient and making all your requests using those clients.

So I think we don't need to support general timeout configuration, at least to keep the API simpler and to force developers to use httpx the 'right way.'

[andybbruno]

You’re absolutely right about the benefits of using a single client. But, let’s be real here: rewriting the whole codebase just because there’s no global timeout setting is overkill. It’s a tiny change that can be handled quickly without refactoring everything.

I totally get where you’re coming from, but I just can’t justify dedicating a whole week to this!

[zanieb]

Your change would affect any dependencies using httpx though, and similarly, any of your dependencies could change the global timeout. This could lead to pretty confusing behavior.