pyanalyze.annotations

Code for understanding type annotations.

This file contains functions that turn various representations of Python type annotations into pyanalyze.value.Value objects.

There are three major functions:

• type_from_runtime() takes a runtime Python object, for example type_from_value(int) -> TypedValue(int).

• type_from_value() takes an existing pyanalyze.value.Value object. For example, evaluating the expression int will produce KnownValue(int), and calling type_from_value() on that value will produce TypedValue(int).

• type_from_ast() takes an AST node and evaluates it into a type.

These functions all rely on each other. For example, when a forward reference is found in a runtime annotation, the code parses it and calls type_from_ast() to evaluate it.

These functions all use Context objects to resolve names and show errors.

class pyanalyze.annotations.Context

A context for evaluating annotations.

The base implementation does very little. Subclass this to do something more useful.

should_suppress_undefined_names: bool = False

While this is True, no errors are shown for undefined names.

suppress_undefined_names() → ContextManager[None]

Temporarily suppress errors about undefined names.

add_evaluation(obj: object) → Generator[None, None, None]

Temporarily add an object to the set of objects being evaluated.

This is used to prevent infinite recursion when evaluating forward references.

show_error(message: str, error_code: Error = Error(name='invalid_annotation', description='Invalid type annotation'), node: AST | None = None) → None

Show an error found while evaluating an annotation.

get_name(node: Name) → Value

Return the Value corresponding to a name.

class pyanalyze.annotations.RuntimeEvaluator(node: ast.FunctionDef | ast.AsyncFunctionDef, return_annotation: pyanalyze.value.Value, globals: Mapping[str, object], func: Callable[..., Any])

get_name(node: Name) → Value

Return the Value corresponding to a name.

class pyanalyze.annotations.SyntheticEvaluator(node: ast.FunctionDef | ast.AsyncFunctionDef, return_annotation: pyanalyze.value.Value, error_ctx: pyanalyze.node_visitor.ErrorContext, annotations_context: pyanalyze.annotations.Context)

get_name(node: Name) → Value

Return the Value corresponding to a name.

pyanalyze.annotations.type_from_ast(ast_node: AST, visitor: NameCheckVisitor | None = None, ctx: Context | None = None) → Value

Given an AST node representing an annotation, return a Value.

Parameters:

• ast_node – AST node to evaluate.

• visitor – Visitor class to use. This is used in the default Context to resolve names and show errors. This is ignored if ctx is given.

• ctx – Context to use for evaluation.

pyanalyze.annotations.type_from_runtime(val: object, visitor: NameCheckVisitor | None = None, node: AST | None = None, globals: Mapping[str, object] | None = None, ctx: Context | None = None, *, allow_unpack: bool = False) → Value

Given a runtime annotation object, return a Value.

Parameters:

• val – Object to evaluate. This will usually come from an __annotations__ dictionary.

• visitor – Visitor class to use. This is used in the default Context to resolve names and show errors. This is ignored if ctx is given.

• node – AST node that the annotation derives from. This is used for showing errors. Ignored if ctx is given.

• globals – Dictionary of global variables that can be used to resolve names. Ignored if ctx is given.

• ctx – Context to use for evaluation.

• allow_unpack – Whether to allow Unpack types.

pyanalyze.annotations.type_from_value(value: Value, visitor: NameCheckVisitor | None = None, node: AST | None = None, ctx: Context | None = None, *, is_typeddict: bool = False, allow_unpack: bool = False) → Value

Given a Value <pyanalyze.value.Value representing an annotation, return a Value representing the type.

The input value represents an expression, the output value represents a type. For example, the impl of typing.cast(typ, val) calls type_from_value() on the value it receives for its typ argument and returns the result.

Parameters:

• value – Value <pyanalyze.value.Value to evaluate.

• visitor – Visitor class to use. This is used in the default Context to resolve names and show errors. This is ignored if ctx is given.

• node – AST node that the annotation derives from. This is used for showing errors. Ignored if ctx is given.

• ctx – Context to use for evaluation.

• is_typeddict – Whether we are at the top level of a TypedDict definition.

class pyanalyze.annotations.TypeQualifierValue(qualifier: Literal['Required', 'NotRequired', 'ReadOnly'], value: pyanalyze.value.Value)

class pyanalyze.annotations.DecoratorValue(decorator: object, args: Tuple[pyanalyze.value.Value, ...])