Proposed clarification of spec for int/float/complex promotion

[JelleZijlstra]

Fixes #1746.

[erictraut]

Looks good to me. One minor suggested improvement in the test case, but it's fine without this change.

[hauntsaninja]

I think worth having an unguarded f.hex() as well

[carljm]

This one is interesting, because it's not totally clear to me what behavior we should specify for an unguarded .hex() call.

The proposed spec wording, as is, would mean that this should be an error, right? Because "member int of float | int has no method hex." builtins.int in typeshed doesn't have the hex method. So if you want to call hex you have to guard it with isinstance(float).

But this doesn't seem to be an error in either mypy or pyright. The latter is particularly interesting, since my understanding was that pyright already used the float | int interpretation of float annotations.

@erictraut What's the explanation of pyright's behavior here? Is this special-cased in some way?

I think if the conformance suite shows f.hex() here to not be an error, then that needs to be justified with some additional wording in the spec.

[erictraut]

In pyright's current implementation, I have a function called expandPromotionTypes that is responsible for taking the type float and expanding it to Float | int and complex into Complex | Float | int. (I use a capitalized name here to indicate the "real" type.)

There are three places where I initially added calls to this function:

1. isinstance type narrowing
2. Class pattern matching (which is the match statement equivalent of isinstance checks)
3. Attribute access ("dot") expression forms

I also 4) changed the inference logic for float literals to be inferred as Float rather than float.

I ended up backing out 3 and 4 because these two cases produced too much noise, including some false positive errors. See this issue, which shows some of the pain this caused pyright users.

I think it's reasonable to add 3 back, but doing so requires an additional change to avoid some of the noise. Namely, a call to float() or complex() constructors needs to evaluate to Float and Complex, respectively.

I think that adding 4 back would be problematic, especially in situations where float literals are used in list, set and dict expressions. These are problematic because the types are invariant. Consider the following code:

x = [3.1] # Should the type of `[3.1]` be inferred as `list[float]` or `list[Float]`?
x.append(1) # Should this be allowed? Most devs would expect it to be!

I think the expression [3.1] should continue to be inferred as list[float], which probably means that 3.1 should continue to be inferred as float and not Float. I think that's OK, but it does lead to an apparent inconsistency because [float(3.1)] is evaluated as list[Float]. The typing spec doesn't dictate type inference rules (currently), so these are not in scope for the spec, but this issue is something that type checker maintainers / authors will need to consider.

Here's a PR (and "mypy_primer" run) that adds back 3 from my list above. This makes pyright conformant with the proposed language in this typing spec update (i.e. it now generates an error for f.numerator in the conformance test case). The "mypy_primer" run shows one change in the dd_trace library. It's in code that looks like this:

x = {"a": float(0)} # Now evaluates to `dict[str, Float]` rather than `dict[str, float]`
x["b"] = 1 # Now a type error because `int` cannot be assigned to this `dict`

This change is not without consequences, but I think the impact is relatively minimal and new type errors are straightforward to fix.

[carljm]

I see, so pyright's implementation doesn't actually expand float to float | int when it's encountered in an annotation, but rather at certain points where the type is used.

I guess with #3 added back, pyright would also error on f: float; f.hex(). The hex/fromhex case is similar to the is_integer case encountered in microsoft/pyright#6032, but I expect is_integer is more commonly used. And is_integer was added to the int type in Python 3.12 to avoid this problem. It doesn't seem like your mypy primer run encountered any issues with calls to .hex or .fromhex, which doesn't surprise me.

One thing that does surprise me on that mypy primer run is that the two new errors don't appear to involve attribute access (your (3)), but rather inferred types for containers (your (4)). E.g. one of the errors is on this line: https://github.com/DataDog/dd-trace-py/blob/main/ddtrace/llmobs/_integrations/bedrock.py#L43

[erictraut]

so pyright's implementation doesn't actually expand float to float | int when it's encountered in an annotation

That's correct. It would be confusing for pyright & pylance users to see float | int in hover text, inlined type annotations, completion suggestions, reveal_type text, etc. if they use float in a type annotation. And likewise, if they specify float | int in a type annotation, it would be confusing to reduce that to just float. I try to retain the same form used in the annotation where possible.

[carljm]

Looks good to me.

[grievejia]

IIUC this is basically saying that if float appears as an argument to isinstance() then we should interpret it differently from the case when float appears in function annotations?

In that case, I wonder what should happen in other cases, e.g. cast(), assert_type(), or other kinds of type forms -- should we interpret float to be the "real" float in those places as well? Does it make sense to have the spec discuss about the "scope" of this kind of special-casing interpretations?

[JelleZijlstra]

The proposed wording says that float should be interpreted as float | int in type expressions. The first argument to cast() is a type expression, but the second argument to isinstance() is not.