ty issue with float vs int | float for _iLocIndexerSeries

[loicdiridollou]

Describe the bug

The way that ty treats int and float can cause more issues in the future, we can annotate as float and ty will see it as int | float.
See https://docs.astral.sh/ty/reference/typing-faq/#why-does-ty-show-int-float-when-i-annotate-something-as-float

Just wanted to open the discussion, haven't thought about the issue yet but worth keeping in the back of our mind.

To Reproduce

1. Provide a minimal runnable pandas example that is not properly checked by the stubs.
2. Indicate which type checker you are using (mypy or pyright).
3. Show the error message received from that type checker while checking your example.

from dataclasses import dataclass

import pandas as pd
from typing_extensions import reveal_type


@dataclass
class A:
    a: float


some_a = A(2.0)
reveal_type(some_a.a)

df = pd.Series([1.0, 3.0, 4.0], index=["a", "b", "c"], dtype=float)
reveal_type(A.a)
df.iloc[0] = A.a

info[revealed-type]: Revealed type
  --> test_ty.py:13:13
   |
12 | some_a = A(2.0)
13 | reveal_type(some_a.a)
   |             ^^^^^^^^ `int | float`
14 |
15 | df = pd.Series([1.0, 3.0, 4.0], index=["a", "b", "c"], dtype=float)
   |

info[revealed-type]: Revealed type
  --> test_ty.py:16:13
   |
15 | df = pd.Series([1.0, 3.0, 4.0], index=["a", "b", "c"], dtype=float)
16 | reveal_type(A.a)
   |             ^^^ `int | float`
17 | df.iloc[0] = A.a
   |

error[invalid-assignment]: Invalid subscript assignment with key of type `Literal[0]` and value of type `int | float` on object of type `_iLocIndexerSeries[float]`
  --> test_ty.py:17:1
   |
15 | df = pd.Series([1.0, 3.0, 4.0], index=["a", "b", "c"], dtype=float)
16 | reveal_type(A.a)
17 | df.iloc[0] = A.a
   | ^^^^^^^^^^^^^^^^
   |
info: rule `invalid-assignment` is enabled by default

Please complete the following information:

• OS: [e.g. Windows, Linux, MacOS] MacOS
• OS Version [e.g. 22] 26.0.1
• python version 3.14
• version of type checker ty 0.0.4
• version of installed pandas-stubs main

Additional context
Add any other context about the problem here.

[Dr-Irv]

We made this change over 3 years ago in #169 .

See error code Y041 in https://pypi.org/project/flake8-pyi/22.7.0/

And see https://peps.python.org/pep-0484/#the-numeric-tower

So I think ty is wrong to do this - it violates the PEP!

[cmp0xff]

Reported in astral-sh/ty#2184

[cmp0xff]

According to the replies in astral-sh/ty#2184, I think ty has a consistent alternative approach, that takes annotated float as Just[float] | Just[int] and so on.

[Dr-Irv]

The problem here is how do you then do assert_type() in a consistent way across type checkers?

Sounds like we may have to replace all of our float declarations with int | float as argument types??

[cmp0xff]

My understanding is that whenever we annotate float, ty translates it into Just[float] | Just[int] and prints as float | int.

When we type assert(..., float), ty understands it as assert(..., Just[float] | Just[int]).

When we write foo(x: float), ty understands it as foo(x: Just[float] | Just[int]).

They seem consistent to me and we do not need to change our annotations.

[Dr-Irv]

My understanding is that whenever we annotate float, ty translates it into Just[float] | Just[int] and prints as float | int.

When we type assert(..., float), ty understands it as assert(..., Just[float] | Just[int]).

When we write foo(x: float), ty understands it as foo(x: Just[float] | Just[int]).

They seem consistent to me and we do not need to change our annotations.

OK, that's fine. I still find their interpretation a bit counter-intuitive especially considering the behavior of other type checkers.

[jorenham]

So I think ty is wrong to do this - it violates the PEP!

That PEP has been superseded by the typing spec (https://typing.python.org/en/latest/spec/special-types.html#special-cases-for-float-and-complex). The spec is currently a bit vague, but python/typing#1748 proposes an explicit change stating that _: float should be considered equivalent to _: float | int (as opposed to pretending that int is a subtype of float). See https://discuss.python.org/t/clarifying-the-float-int-complex-special-case/54018
for the (rather contentious) discussion. But even without this change, the typing spec already dictates that int should be assignable to float, and the only conclusion to be drawn from that is that type-checkers should treat float | int and int in the same way, i.e. they're statically (and only statically) equivalent.

In scipy-stubs, I ran an experiment (scipy/scipy-stubs#492) where I replaced every float annotation with the (supposedly) equivalent float | int | bool annotation, and did the same for complex and int. However, despite being specified as equivalent, this led to a significant increase in analysis time in both mypy and pyright. Mypy also behaved differently in several situations, and as far as I am aware, that bug has not yet been fixed. Pyright additionally has an issue where it distinguishes between assert_type(..., float) and assert_type(..., float | int). I describe the findings of this experiment in more detail in data-apis/array-api-compat#291 (comment) .

Also note that the typing spec stub style guide (https://typing.python.org/en/latest/guides/writing_stubs.html#functions-and-methods) says the following:

Avoid union return types. See python/mypy#1693

Use float instead of int | float for parameter annotations. See PEP 484 for more details.

TL;DR: I recommend replacing every complex | float with complex, and every float | int with float. This is what the typing spec recommends, will improve type-checker performance, and lowers the risk of running into bugs in mypy and pyright. It will also make type-checker error reports a bit less unreadable in certain situations.

[Dr-Irv]

TL;DR: I recommend replacing every complex | float with complex, and every float | int with float. This is what the typing spec recommends, will improve type-checker performance, and lowers the risk of running into bugs in mypy and pyright. It will also make type-checker error reports a bit less unreadable in certain situations.

So we might be OK in pandas-stubs because a quick search indicates we are not doing that.

[loicdiridollou]

I don't think there is anything we should action on this one at the moment, please reopen in case.