types-bits

u1..u10 and i1..i10 as fully materialized Literal unions. Generated .pyi, zero runtime cost, exhaustively checked.

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from types_bits import u4

x: u4 = 15  # ok
y: u4 = 16  # error, on every checker

camas runs the gate; camas --list enumerates it. CI fans the same tree out over a runner axis, with both matrix axes emitted from tasks.py. camas bench and camas bench_shapes regenerate everything below into bench/results/.

Runtime cost

Zero. The stub is a PEP 484 .pyi behind TYPE_CHECKING. import types_bits loads two modules and no stdlib (tests/test_runtime.py). Every number below is type-checker wall clock, per check run.

Check cost by width

Seconds, cold, best of one, Python 3.14.1 / WSL2. Encoding flat (uN: TypeAlias = Literal[0, ..., 2**N-1]), declaring u1..uN (so a probe at N bits holds 2^(N+1)-2 literals) and widening each into the next.

Shipped library (u1..u10 + i1..i10): mypy 1.51, basedpyright 1.28, pyright 1.08, pyrefly 0.23, zuban 0.08, ty 0.06 — matching the uN: TypeAlias = int control.

xychart-beta
    title "16 bits"
    x-axis [zuban, mypy, basedpyright, pyright, pyrefly, ty]
    y-axis "seconds" 0 --> 55
    bar [48.73, 2.58, 0.60, 0.55, 0.39, 0.34]

zuban, same sweep — 12x then 15x per extra 2 bits past 12:

xychart-beta
    title "zuban vs width"
    x-axis "bits" [8, 10, 12, 14, 16]
    y-axis "seconds" 0 --> 55
    line [0.10, 0.11, 0.28, 3.25, 48.73]

The other five, 0–3s axis. Rising line is mypy; flat cluster is pyright, basedpyright, pyrefly, ty:

xychart-beta
    title "mypy, pyright, basedpyright, pyrefly, ty"
    x-axis "bits" [8, 10, 12, 14, 16]
    y-axis "seconds" 0 --> 3
    line [1.54, 1.53, 1.58, 1.63, 2.58]
    line [0.60, 0.62, 0.59, 0.54, 0.55]
    line [0.72, 0.65, 0.70, 0.63, 0.60]
    line [0.27, 0.26, 0.32, 0.26, 0.39]
    line [0.07, 0.07, 0.11, 0.20, 0.34]

Fixed vs marginal cost

u(N-1) and u(N) declared in every row; only the use count varies. Italic rows are the uN: TypeAlias = int control.

10 bits — indistinguishable from int:

16 bits — 98,304 literals:

• Declaration: fixed per check run, ~linear in literals (~8 µs/literal on mypy). Not per importing file, not per use.
• Assignment: free. Enumerated membership is a hash lookup.
• Widening: free except zuban at width.

Widening

Cost tracks the narrow operand, not the wide one. Wide side fixed at u16, one widening:

Measured under the PEP 695 spelling; no task reproduces this sweep.

Both operands must be large. At the 10-bit ceiling the worst case (u9 → u10) is 0.10s. Annotating a boundary at one width, so callers assign literals rather than widen between adjacent wide aliases, avoids the shape entirely.

Encodings

Measured under the PEP 695 spelling, before the PEP 613 switch; camas bench_full regenerates.

xychart-beta
    title "ty at 14 bits by encoding"
    x-axis [union, nested, annotated, flat]
    y-axis "seconds" 0 --> 46
    bar [44.24, 0.23, 0.22, 0.17]

Runtime tier

PEP 562 module __getattr__ resolves the same names to Annotated[int, Ge(lo), Le(hi)] (PEP 593), the shape annotated-types consumers read. tests/test_runtime.py pins it against the static bounds for all 20 widths. Needs the rt extra; annotated_types imports on first attribute access.

from pydantic import TypeAdapter
from types_bits import u8  # Annotated[int, Ge(0), Le(255)] at runtime

TypeAdapter(u8).validate_python(256)  # ValidationError

Prior art

range-typed-integers defines u8 = NewType('u8', Annotated[int, ValueRange(0, 255)]) for the byte widths u8..u64 / i8..i64.

Verified against every checker in the gate: mypy reports the same Incompatible types in assignment (expression has type "int", variable has type "u8") on the in-range and out-of-range lines alike. The range is metadata no checker reads (PEP 746 would not change this). ValueRange is O(1) per type, so it reaches u64; enumeration is O(2^N), so it stops at u10.

PEPs

No PEP provides bounded integers.

• python/typing#554, "Support for Range Types?" — closed. Requested an Ada-style RangeType.
• discuss.python.org, "Use type hinting with bound constraints, e.g. int[0:15]" — no resolution. Objections: most constraints are not statically validatable; ranges need new type-system machinery; arithmetic is not closed. Landed on Annotated + annotated-types with runtime validation.

fixtures/reject.py covers the arithmetic case: every checker rejects u4 + u4 where a u4 is required. mypy widens the sum to int; ty and zuban widen it to Literal[0, ..., 30].