ClientSession.timeout has an incorrect typing

[DevilXD]

Describe the bug

The aiohttp.ClientSession.timeout attribute has a type of Union[object, aiohttp.ClientTimeout], however the code logic will never actually assign a bare object type to the self._timeout attribute, making this typing quite over-inclusive. Trying to use this attribute in typed code results in having to use cast(aiohttp.ClientTimeout, session.timeout), which is far from ideal considering one can just fix the typing in the library.

I ran into this while using Python 3.8.10, but the exact same explanation above applies to the current master branch (and the version I'm using of course), as shown by the snippets below.

3.8 branch __init__ parameter:

aiohttp/aiohttp/client.py

Line 217 in 6243204

timeout: Union[object, ClientTimeout] = sentinel,

3.8 branch self._timeout assignment:

aiohttp/aiohttp/client.py

Lines 261 to 290 in 6243204

	if timeout is sentinel:
	self._timeout = DEFAULT_TIMEOUT
	if read_timeout is not sentinel:
	warnings.warn(
	"read_timeout is deprecated, " "use timeout argument instead",
	DeprecationWarning,
	stacklevel=2,
	)
	self._timeout = attr.evolve(self._timeout, total=read_timeout)
	if conn_timeout is not None:
	self._timeout = attr.evolve(self._timeout, connect=conn_timeout)
	warnings.warn(
	"conn_timeout is deprecated, " "use timeout argument instead",
	DeprecationWarning,
	stacklevel=2,
	)
	else:
	self._timeout = timeout # type: ignore[assignment]
	if read_timeout is not sentinel:
	raise ValueError(
	"read_timeout and timeout parameters "
	"conflict, please setup "
	"timeout.read"
	)
	if conn_timeout is not None:
	raise ValueError(
	"conn_timeout and timeout parameters "
	"conflict, please setup "
	"timeout.connect"
	)

Note the # type: ignore comment on L278 there - it's because the timeout is sentinel check does not narrow down the timeout type. The correct way to go about this would be to use a cast there instead of ignoring the issue like that.

3.8 branch timeout attribute declaration:

aiohttp/aiohttp/client.py

Lines 1029 to 1032 in 6243204

	@property
	def timeout(self) -> Union[object, ClientTimeout]:
	"""Timeout for the session."""
	return self._timeout

Master branch __init__ parameter:

aiohttp/aiohttp/client.py

Line 215 in 52fa599

timeout: Union[_SENTINEL, ClientTimeout, None] = sentinel,

Master branch self._timeout assignment:

aiohttp/aiohttp/client.py

Lines 260 to 263 in 52fa599

	if timeout is sentinel or timeout is None:
	self._timeout = DEFAULT_TIMEOUT
	else:
	self._timeout = timeout

Due to a different handling of the sentinel value via an Enum member, no cast is needed here.

Master branch timeout attribute declaration:

aiohttp/aiohttp/client.py

Lines 1008 to 1011 in 52fa599

	@property
	def timeout(self) -> Union[object, ClientTimeout]:
	"""Timeout for the session."""
	return self._timeout

The attribute type is still over-inclusive here though.

The solution would be quite simple:

    @property
    def timeout(self) -> ClientTimeout:
        """Timeout for the session."""
        return self._timeout

Please let me know if you'd welcome a PR for this. I'd like to get this backported back to 3.8 (that I'm using) if possible, but if not, just fixing it in the master branch so that it's correct going forward would be good enough for me.

To Reproduce

Utilize some kind of a type checker like MyPy.

import asyncio
import aiohttp

async def main:
    session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=10))
    # read back the total time attribute
    total_time = session.timeout.total  # "object" type of "Union[object, ClientTimeout]" has no attribute "total"
    print(total_time)

asyncio.run(main())

Expected behavior

The attribute having only the aiohttp.ClientTimeout type and not requiring cast usage when accessing the attribute during library usage in user code.

Logs/tracebacks

Not applicable

Python Version

Python 3.8.10

aiohttp Version

Version: 3.8.1

multidict Version

Version: 6.0.2

yarl Version

Version: 1.7.2

OS

Windows

Related component

Client

Additional context

Related issues and PRs:

#4191
#4193

Code of Conduct

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

[Dreamsorcerer]

I'll certainly take a look over it, if you create a PR.

The correct way to go about this would be to use a cast there instead of ignoring the issue like that.

A cast() is ignoring the issue. We try to avoid both casts and ignores where possible. In many cases, if you are working around a bug/limitation of mypy, the ignore option is safer (if fixed later, you are more likely to get an unused ignore error than a redundant cast error, plus it's easier to pick out these discrepancies when looking at the code base).

[DevilXD]

A cast() is ignoring the issue.

A cast is just a "manual" way of performing type narrowing. Yes, it kinda is ignoring the issue, but it can be made more specific than an ignore comment. Whatever type you cast the variable to, has to be a subtype of the type the variable already has, otherwise MyPy returns an error (as far as I can remember). I think this is better than a type: ignore[assignment] comment, because a cast wouldn't let you assign an int by accident there for example, while a comment like that leaves no complaints. That's just my take on it though.

I'll try to prepare a PR later today then, or later this week if I won't be able to do so today.

[Dreamsorcerer]

A cast is just a "manual" way of performing type narrowing. Whatever type you cast the variable to, has to be a subtype of the type the variable already has.

No, it literally just replaces the type, thus throwing away type safety:

from typing import cast
foo = "apple"
reveal_type(cast(int, foo))

> mypy --strict test.py
test.py:3: note: Revealed type is "builtins.int"
Success: no issues found in 1 source file

There are certainly times where casting makes more sense, but both are inherently unsafe and are ignoring the actual issue.

[DevilXD]

That's weird, I remember getting an error before when trying to straight up "replace" a type like you just shown. Strange.

[DevilXD]

I have created #6923 to address this issue.