When would you annotate a parameter typing.SupportsIndex instead of int?

## Two different questions hide behind "annotate this as a number" When a parameter should accept "an integer-ish thing", Python offers three spellings, and only two of them work statically. ### 1. `int` — the default, and usually correct Most code should annotate `int`. Thanks to `bool` being a subclass it already accepts booleans, and thanks to PEP 484's promotion an `int` is accepted onwards where `float` is annotated. Application code that does arithmetic wants exactly this. ### 2. `typing.SupportsIndex` — the structural integer `SupportsIndex` is a protocol in `typing`, satisfied by any class defining `__index__`. That dunder was introduced by PEP 357 to answer a specific question: what may be used as a sequence index? The contract is that `__index__` returns an `int` **without loss** — it is not permitted to round or truncate. Python calls it in every place that demands an exact integer: ```python import operator from typing import SupportsIndex class ChannelId: def __init__(self, slot: int) -> None: self.slot = slot def __index__(self) -> int: return self.slot row = ["t0", "t1", "t2"] print(row[ChannelId(2)]) # t2 print(operator.index(ChannelId(2))) print(hex(ChannelId(255))) # 0xff ``` The same object also works in a slice, in `range()`, and as a `bytes` length. Note that `int(x)` is the *lossy* door: it will use `__int__` if present, and `__int__` is allowed to truncate — which is why `operator.index()` exists as the strict alternative. Annotating `SupportsIndex` is a promise about what you will do with the value: hand it to an integer operation, not multiply it. In a sensor-telemetry collector this is exactly the shape that appears. Device channels are wrapped in a small identifier class so they cannot be confused with sample counts, yet the wrapper still has to index a fixed row of readings. Giving it `__index__` and annotating the helper `SupportsIndex` keeps the wrapper usable without either an `int()` sprinkle at every call site or an annotation that lies. `typing.SupportsFloat` is the float-side counterpart, matched by anything with `__float__`; `typing.SupportsInt`, `typing.SupportsComplex`, `typing.SupportsAbs` and `typing.SupportsRound` complete the small family. `SupportsFloat` is used far less than `SupportsIndex`, because the numeric-tower promotion already covers the common case and `__float__` may be lossy. ### 3. The `numbers` ABCs — the trap PEP 3141 gave Python an abstract numeric tower: `numbers.Number`, `numbers.Complex`, `numbers.Real`, `numbers.Rational`, `numbers.Integral`. At runtime it works through **registration**: ```python import numbers from decimal import Decimal print(isinstance(3.0, numbers.Real)) # True print(float in numbers.Real.__mro__) # False - registered, not inherited print(isinstance(Decimal("1.5"), numbers.Number)) # True ``` `float` is not a subclass of `numbers.Real`; it was *registered* as one by a call executed when the module is imported. Static checkers do not execute your program, and they deliberately do not follow `register()`, so as an annotation `numbers.Real` behaves as an unrelated class: passing a plain `float` to a parameter annotated `numbers.Real` is reported as an error. PEP 484 acknowledged this directly, which is why it introduced the `int`/`float`/`complex` promotion instead of telling everyone to import `numbers`. **`numbers` remains useful for `isinstance` checks at runtime; it is not an annotation vocabulary.** ## What the protocol promises, and what it does not `SupportsIndex` guarantees exactly one thing: `__index__` exists and yields an integer. It says nothing about arithmetic, ordering or formatting, so a body that writes `where + 1` is asking for more than the annotation provides and should annotate `int` instead. The contract is also enforced at runtime rather than merely documented: if `__index__` returns anything other than an `int`, the operation fails with `TypeError: __index__ returned non-int (type float)` rather than silently rounding. The same door is used by `range()`, by slice bounds, by `bytes(n)` and by the bit-shift operators, which is why a wrapper that defines `__index__` becomes usable across all of them at once — and why defining it on a type that is *not* conceptually an exact integer is a mistake. ## The judgement call Protocols are not free. `SupportsIndex` in a signature is one more concept for a reader, it accepts objects your error messages may not have been written for, and it does nothing for a body that performs arithmetic — an object with `__index__` is not required to support `+`. Use it when three things hold: the parameter is genuinely a *position or exact integer*, the value is forwarded into an indexing or bit-level operation, and the API is consumed by callers you do not control. Inside one application, `int` is clearer and the conversion belongs at the edge. The last piece of judgement is precision types. `decimal.Decimal` satisfies neither `int` nor `float` statically, and that is deliberate — mixing it with binary floats loses the exactness you adopted it for. Model such an API with an explicit union or an overload rather than reaching for a numeric ABC that no checker understands.