arcane-typing

This package provides advanced typing patterns for Python projects that use ty.

Usage

Add arcane-typing as a dependency to your project:

uv add arcane-typing

Use one of its typing features in your code, for example:

from arcane_typing import has_attr_of_type

def get_name(obj: object) -> str:
    if has_attr_of_type(obj, "name", str):
        return obj.name.upper()
    else:
        return "<unknown>"

Use ty to type-check your code:

uv add --dev ty  # If you are not already using it

uv run ty check

Features

Core functionality and types

• Intersection[A, B] is an intersection type that represents values that are both of type A and type B.
• Not[T] describes values that are not of type T.
• TypeOf[expr] can be used to obtain ty's inferred type for an expression in a type annotation or type alias.
• Top[T] can be used to refer to the top-materialization of T.
• Bottom[T] can be used to refer to the bottom-materialization of T.
• FunctionLikeCallable[P, R] works just like Callable[P, R] but also allows attributes like __name__, __qualname__, or __code__ to be accessed.
• NonEmptyString excludes the empty string literal from str.
• NonStringSequence excludes bare str from Sequence[str].
• try_import_module(name) returns the specific module type for a resolvable name, or None if it is not available.
• static_assert(condition[, msg]) enforces a condition at type-check time.

TypedDict-related features

• TypeOf[Keys[T]] gives a union of string literals for the keys that can appear in a TypedDict T.
• TypeOf[Values[T]] gives the union of value types that can appear in a TypedDict T.

Type-narrowing helpers

• has_attr_of_type(obj, "name", T) narrows obj.name to type T if the attribute exists and if it is an instance of T (which can be a class or a union of classes)
• has_item_of_type(obj, "key", T) narrows obj["key"] to T if the mapping contains the key and its value is an instance of T.
• is_sequence_of(obj, T) checks that obj is a sequence and that every element is an instance of T (which can be a class or a union of classes). It narrows obj to Sequence[T] on success.

Development

Use uv to run the following development tasks:

# Linting and formatting
uv run ruff check
uv run ruff format --check

# Type checking
TY_UV=scripts uv run ty check

# Markdown tests
uv run mdtest.py