trace_request_ctx typing annotation is incompatible with instances of user-specific class to be used as request context

[vitaly-krugl]

Describe the bug

We can pass the trace_request_ctx arg to varios ClientSession verbs (get, put, request, etc.) . However, the typing annotation for this request context is trace_request_ctx: Union[Mapping[str, Any], None], which is incompatible with passing an instance of a custom class.

For example, I would like to be able to pass a request context of an arbitrary class instead of a Mapping, perhaps something like this example :

@dataclass
class MyRequestCrumbs:
    num_attempts: int
    unique_id: UUID
...
crumbs = MyRequestCrumbs(num_attempts=0, unique_id=uuid.uuid1())

await session.request(..., trace_request_ctx=crumbs)

To Reproduce

See description

Expected behavior

I expected the typing annotation of trace_request_ctx to support request context instances of any class, including user-defined classes

Logs/tracebacks

N/A

Python Version

$ python --version

Python 3.10.14

aiohttp Version

$ python -m pip show aiohttp

Name: aiohttp
Version: 3.11.12
Summary: Async http client/server framework (asyncio)
Home-page: https://github.com/aio-libs/aiohttp
Author: 
Author-email: 
License: Apache-2.0
Location: /Users/vkruglik/git/bcps-engine-project/venv/lib/python3.10/site-packages
Requires: aiohappyeyeballs, aiosignal, async-timeout, attrs, frozenlist, multidict, propcache, yarl
Required-by:

multidict Version

$ python -m pip show multidict

N/A

propcache Version

$ python -m pip show propcache

N/A

yarl Version

$ python -m pip show yarl

N/A

OS

N/A

Related component

Client

Additional context

No response

Code of Conduct

• I agree to follow the aio-libs Code of Conduct

[Dreamsorcerer]

Yeah, I guess technically the annotation could allow object. Though we'd then have no way to know a more precise type when accessing the trace_request_ctx (although I think it's currently Any...).

[Dreamsorcerer]

I think it's fine to change the parameter to object. Can you open a PR and resolve any typing errors that occur?

[vitaly-krugl]

Hi Sam thank you for following up. I ended up switching to context var instead. Do you see any issue with context var for this use case,

…

On Sun, Apr 20, 2025 at 8:30 AM Sam Bull ***@***.***> wrote: Yeah, I guess technically the annotation could allow object. Though we'd then have no way to know a more precise type when accessing the trace_request_ctx (although I think it's currently Any...). — Reply to this email directly, view it on GitHub <#10753 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK72KQ7HQ2GCBM5PMAVZZ322OHO5AVCNFSM6AAAAAB3OZ3QTGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMJXGE2DQOJWGE> . You are receiving this because you authored the thread.Message ID: ***@***.***> *Dreamsorcerer* left a comment (aio-libs/aiohttp#10753) <#10753 (comment)> Yeah, I guess technically the annotation could allow object. Though we'd then have no way to know a more precise type when accessing the trace_request_ctx (although I think it's currently Any...). — Reply to this email directly, view it on GitHub <#10753 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK72KQ7HQ2GCBM5PMAVZZ322OHO5AVCNFSM6AAAAAB3OZ3QTGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMJXGE2DQOJWGE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[Dreamsorcerer]

If you mean https://docs.python.org/3/library/contextvars.html, then I tend to avoid them. They seem like magic globals (like Flask uses), in a previous job we had a major issue caused by such a global in a Flask app. I prefer the explicit approach of variables being passed through functions, like aiohttp demos do. But, I'm not familiar with your specific use case.

[vitaly-krugl]

Thank you for sharing your experience… yes, I was referring to the python 3x ContextVar, which is to asyncio tasks flows what thread local store is to threads. What you said about passing the context by function parameters makes perfect sense. I just didn’t know whether the dict typing annotation had some sort of serialization implications.

…

On Tue, Apr 22, 2025 at 7:12 PM Sam Bull ***@***.***> wrote: If you mean https://docs.python.org/3/library/contextvars.html, then I tend to avoid them. They seem like magic globals (like Flask uses), in a previous job we had a major issue caused by such a global in a Flask app. I prefer the explicit approach of variables being passed through functions, like aiohttp demos do. But, I'm not familiar with your specific use case. — Reply to this email directly, view it on GitHub <#10753 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK72KV5CT3LFSHLSR7VOZT223EETAVCNFSM6AAAAAB3OZ3QTGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMRSGY3TIMBSHA> . You are receiving this because you authored the thread.Message ID: ***@***.***> *Dreamsorcerer* left a comment (aio-libs/aiohttp#10753) <#10753 (comment)> If you mean https://docs.python.org/3/library/contextvars.html, then I tend to avoid them. They seem like magic globals (like Flask uses), in a previous job we had a major issue caused by such a global in a Flask app. I prefer the explicit approach of variables being passed through functions, like aiohttp demos do. But, I'm not familiar with your specific use case. — Reply to this email directly, view it on GitHub <#10753 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK72KV5CT3LFSHLSR7VOZT223EETAVCNFSM6AAAAAB3OZ3QTGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMRSGY3TIMBSHA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[Dreamsorcerer]

I just didn’t know whether the dict typing annotation had some sort of serialization implications.

The object appears to just get passed through to the handlers, so aiohttp doesn't seem to do anything with it. So, any type should be safe.