Skip to content

ty-extensions

ty-extensions is a module that provides experimental typing features supported by ty.

ty bundles the typing stubs for this module, which means that you can use them without installing anything. However, if you rely on runtime evaluation of type annotations, you should add the ty-extensions package as a dependency in your project:

uv add ty-extensions

static_assert

Make sure that a certain condition holds at type-check time.

Example:

static_assert(sys.version_info[:2] >= (3, 13), "Python 3.13 or higher is required")

At runtime, a false condition raises AssertionError (even with Python optimization enabled).

Not

Not[T], also spelled as ~T, represents the set of all objects that do not inhabit the type T.

In type expressions, ty supports the experimental spelling ~T, and also uses it when displaying negation types. While the experimental syntax will raise an exception in runtime contexts or in cases where an annotation expression could be evaluated, however, Not[] can be used in arbitrary contexts if the ty-extensions package is installed.

Intersection

Intersection[T1, T2, ..., Tn], also spelled as T1 & T2 & ... & Tn, represents an intersection type: the set of all objects that inhabit all of the types T1, T2, ..., Tn.

For any two fully static types T1 and T2, Intersection[T1, T2] is a subtype of both T1 and T2. For any type T3 that is a subtype of both T1 and T2, Intersection[T1, T2] is a supertype of T3.

In the following example, although neither P nor Q is a subtype of the other, an instance of S inhabits Intersection[P, Q] because S inherits from both P and Q:

class P: ...
class Q: ...
class S(P, Q): ...

s: Intersection[P, Q] = S()

In type expressions, ty supports the experimental spelling T1 & T2, and also uses this syntax when displaying intersection types. While the experimental syntax will raise an exception in runtime contexts or in cases where an annotation expression could be evaluated, however, Intersection[] can be used in arbitrary contexts if the ty-extensions package is installed.

Nested intersections are flattened at runtime, and duplicate operands are removed using runtime equality, keeping the first occurrence of each. A named alias created using the type statement is always kept as an operand. Intersections are unordered types, so nongeneric intersections always compare equal at runtime when they have the same operands:

>>> from ty_extensions import Intersection
>>> Intersection[Intersection[str, int], str]
ty_extensions.Intersection[str, int]
>>> type Alias = Intersection[str, int]  # Python 3.12+
>>> Intersection[Alias, str]
ty_extensions.Intersection[Alias, str]
>>> Intersection[int, str] == Intersection[str, int]
True
>>> hash(Intersection[int, str]) == hash(Intersection[str, int])
True

Top

Top[T] represents the "top materialization" of T.

For any type T, the top materialization of T is a type that is a supertype of all materializations of T.

For a fully static type T, Top[T] is always exactly the same type as T itself. For example, the top materialization of Sequence[int] is simply Sequence[int].

For a gradual type T that contains Any or Unknown inside it, however, Top[T] will not be equivalent to T. Top[Sequence[Any]] evaluates to Sequence[object]: since Sequence is covariant, no possible materialization of Any exists such that a fully static materialization of Sequence[Any] would not be a subtype of Sequence[object].

Top[T] cannot be simplified further for invariant gradual types. Top[list[Any]] cannot be simplified to any other type: because list is invariant, list[object] is not a supertype of list[int]. The top materialization of list[Any] is simply Top[list[Any]]: the infinite union of list[T] for every possible fully static type T.

Bottom

Bottom[T] represents the "bottom materialization" of T.

For any type T, the bottom materialization of T is a type that is a subtype of all materializations of T.

For a fully static type T, Bottom[T] is always exactly the same type as T itself. For example, the bottom materialization of Sequence[int] is simply Sequence[int].

For a gradual type T that contains Any or Unknown inside it, however, Bottom[T] will not be equivalent to T. Bottom[Sequence[Any]] evaluates to Sequence[Never]: since Sequence is covariant, no possible materialization of Any exists such that a fully static materialization of Sequence[Any] would not be a supertype of Sequence[Never]. (Sequence[Never] is not the same type as the uninhabited type Never: for example, it is inhabited by the empty tuple, ().)

For many invariant gradual types T, Bottom[T] is equivalent to Never, although ty will not necessarily apply this simplification eagerly.

AlwaysTruthy

AlwaysTruthy represents the set of all objects that always evaluate to True in a boolean context.

AlwaysTruthy is inhabited by singleton objects such as True and ..., as well as truthy literal strings, integers and bytestrings. It can also be inhabited by instances of classes with __bool__ methods returning Literal[True].

In practice, most Python objects inhabit neither AlwaysTruthy nor AlwaysFalsy, since their boolean evaluation may be uncertain or depend on runtime state. For example, although an instance of exactly object is always truthy, a variable annotated as having type object could also be an instance of an arbitrary subclass of object that is always falsy. This means that the boolean evaluation of a variable inferred as object is uncertain, so object is not a subtype of AlwaysTruthy.

AlwaysFalsy

AlwaysFalsy represents the set of all objects that always evaluate to False in a boolean context.

AlwaysFalsy is inhabited by singleton objects such as False and None, as well as the literals "", b"" and 0. It can also be inhabited by instances of classes with __bool__ methods returning Literal[False].

In practice, however, most Python objects inhabit neither AlwaysTruthy nor AlwaysFalsy, since their boolean evaluation may be uncertain or depend on runtime state.

JustFloat

JustFloat represents an instance of the class float. This can be used to circumvent the type-system special case that lets float annotations accept values of type int as well.

At runtime, JustFloat is an alias for the built-in float class.

JustComplex

JustComplex represents an instance of the class complex. This can be used to circumvent the type-system special case that lets complex annotations accept values of type float or int as well.

At runtime, JustComplex is an alias for the built-in complex class.

NamedTupleLike

A protocol describing an interface that should be satisfied by all named tuples created using typing.NamedTuple or collections.namedtuple.