Skip to content

Commit dc3b7af

Browse files
Update typing FAQ for numeric tower displays (#4198)
Update the typing FAQ to match the numeric-tower display changes in astral-sh/ruff#27406. We now render `float` and `complex` annotations canonically and use `float*` and `complex*` for exact runtime types; the FAQ explains both forms and preserves the existing `JustFloat`/`JustComplex` guidance.
1 parent 261fd8f commit dc3b7af

1 file changed

Lines changed: 26 additions & 7 deletions

File tree

‎docs/reference/typing-faq.md‎

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ Like `Any` and `Unknown`, `Divergent` is a gradual type, so ty allows any operat
8989
`Divergent` part of a type. Unlike `Unknown`, it does not represent missing type information. It is
9090
an internal type used by ty and cannot be used in annotations.
9191

92-
## Why does ty show `int | float` when I annotate something as `float`?
92+
## Why does ty show `float*` or `complex*`?
9393

9494
The [Python typing specification](https://typing.python.org/en/latest/spec/special-types.html)
9595
includes a special rule for numeric types where an `int` can be used wherever a `float` is expected:
@@ -101,13 +101,32 @@ def circle_area(radius: float) -> float:
101101
circle_area(2) # OK: int is allowed where float is expected
102102
```
103103

104-
This rule is a special case, since `int` is not actually a subclass of `float`. To support this, ty
105-
treats `float` annotations as meaning `int | float`. Unlike some other type checkers, ty makes this
106-
behavior explicit in type hints and error messages. For example, if you
107-
[hover over the `radius` parameter](https://play.ty.dev/fdc144c6-031c-4af9-b520-a4c6ccde9261), ty
108-
will show `int | float`.
104+
This rule is a special case, since `int` is not actually a subclass of `float`. A `float` annotation
105+
therefore accepts both integers and actual floating-point values, and ty displays this complete type
106+
as `float`. When ty knows that a value is an actual `float`, rather than an `int`, it displays the
107+
more precise type as `float*`:
109108

110-
A similar rule applies to `complex`, which is treated as `int | float | complex`.
109+
```py
110+
def takes_float(value: float) -> None:
111+
reveal_type(value) # float
112+
113+
114+
reveal_type(1.0) # float*
115+
```
116+
117+
A similar rule applies to `complex`: a `complex` annotation accepts `int`, `float`, and `complex`
118+
values, and ty displays it as `complex`. A value known to be an actual `complex`, rather than an
119+
`int` or a `float`, is displayed as `complex*`:
120+
121+
```py
122+
def takes_complex(value: complex) -> None:
123+
reveal_type(value) # complex
124+
125+
126+
reveal_type(1j) # complex*
127+
```
128+
129+
The starred spellings only appear in ty's output; they cannot be used in Python annotations.
111130

112131
!!! info
113132

0 commit comments

Comments
 (0)