asyncio.getaddrinfo manifests in misleading DNS timeouts when thread pool executor is saturated

[alex-kowalczyk]

Bug report

Bug description:

There is no mention in https://docs.python.org/3/library/asyncio-eventloop.html#dns that asyncio.getaddrinfo is just a ThreadPoolExecutor-based wrapper around sync getaddrinfo (base_events.py:860 - BaseEventLoop.getaddrinfo)
This can lead to mysterious "DNS timeouts" or CancelledErrors during DNS resolution if the executor pool is saturated by other, often totally unrelated code, which is especially not uncommon for any app using asgiref's @sync_to_async decorator.

At the minimum, until this function is converted to real async (if feasible), it would be nice if documentation warned about using shared thread pool executor.

Sample stack trace from httpcore => anyio, which uses asyncio.getaddrinfo under the hood, when the thread pool is saturated:

Traceback (most recent call last):
  File "/app/.venv/lib/python3.11/site-packages/httpcore/_backends/anyio.py", line 114, in connect_tcp
    stream: anyio.abc.ByteStream = await anyio.connect_tcp(
                                   ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/.venv/lib/python3.11/site-packages/anyio/_core/_sockets.py", line 192, in connect_tcp
    gai_res = await getaddrinfo(
              ^^^^^^^^^^^^^^^^^^
asyncio.exceptions.CancelledError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/app/.venv/lib/python3.11/site-packages/httpcore/_exceptions.py", line 10, in map_exceptions
    yield
  File "/app/.venv/lib/python3.11/site-packages/httpcore/_backends/anyio.py", line 113, in connect_tcp
    with anyio.fail_after(timeout):
  File "/app/.venv/lib/python3.11/site-packages/anyio/_core/_tasks.py", line 119, in __exit__
    raise TimeoutError
TimeoutError

CPython versions tested on:

3.11

Operating systems tested on:

Linux

Linked PRs

• gh-112169: Documented getaddrinfo/getnameinfo default loop executor usage and implications. #112191
• [3.13] gh-112169: Documented getaddrinfo/getnameinfo default loop executor usage and implications. (GH-112191) #120935
• [3.12] gh-112169: Documented getaddrinfo/getnameinfo default loop executor usage and implications. (GH-112191) #120936

[gvanrossum]

Thanks for the report!

I believe the reasons why we do it this way are as valid as they were in 2015 — Python has no async DNS API, only a synchronous one. I agree that the executor thing ought to be documented. We could also possibly use a separate executor. Can you submit a PR for a doc update?

The other thing needs a little more thought as e.g. how do we control the capacity of that executor.

Your app could also use its own custom executor, of course — it’s worth mentioning that in the docs update.