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:
static_assert
Make sure that a certain condition holds at type-check time.
Example:
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:
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.