pycroscope.annotations

Code for understanding type annotations.

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

There are three major functions:

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 pycroscope.annotations.Context(*, self_key: type | ~pycroscope.value.ClassOwner | None, visitor: ~pycroscope.annotations.AnnotationVisitor | None = None, can_assign_ctx: ~pycroscope.value.CanAssignContext | None = None, active_type_params: ~pycroscope.type_params.ActiveTypeParams = <factory>, new_type_param_owner: type | ~pycroscope.value.ClassOwner | ~pycroscope.value.FunctionOwner | ~pycroscope.value.AliasOwner | ~typing_extensions.Sentinel | None = None)

A context for evaluating annotations.

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

should_suppress_errors: bool = False

While this is True, no annotation errors are emitted.

should_allow_undefined_names: bool = False

While this is True, unresolved names may evaluate to an unknown type.

new_type_param_owner: type | ClassOwner | FunctionOwner | AliasOwner | Sentinel | None = None

Fallback owner for freshly synthesized type parameters.

suppress_errors() → AbstractContextManager[None]

Temporarily suppress all annotation-evaluation errors.

allow_undefined_names() → AbstractContextManager[None]

Temporarily treat undefined annotation names as unknown types.

add_evaluation(obj: object, name: str, module: str, evaluator: Callable[[], Value]) → 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 pycroscope.value.Value corresponding to a name.

get_error_node() → AST | None

Return the node that should be used as fallback for annotation errors.

class pycroscope.annotations.RuntimeEvaluator(node: ast.FunctionDef | ast.AsyncFunctionDef, return_annotation: pycroscope.value.Value, globals: collections.abc.Mapping[str, object], *, self_key: type | pycroscope.value.ClassOwner | None, visitor: pycroscope.annotations.AnnotationVisitor | None = None, can_assign_ctx: pycroscope.value.CanAssignContext | None = None, active_type_params: pycroscope.type_params.ActiveTypeParams = <factory>, new_type_param_owner: type | pycroscope.value.ClassOwner | pycroscope.value.FunctionOwner | pycroscope.value.AliasOwner | typing_extensions.Sentinel | None = None)
get_name(node: Name) → Value

Return the pycroscope.value.Value corresponding to a name.

class pycroscope.annotations.SyntheticEvaluator(node: ast.FunctionDef | ast.AsyncFunctionDef, return_annotation: pycroscope.value.Value, annotations_context: pycroscope.annotations.Context)
pycroscope.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 pycroscope.value.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.

pycroscope.annotations.annotation_expr_from_ast(ast_node: AST, visitor: NameCheckVisitor | None = None, ctx: Context | None = None, suppress_errors: bool = False) → AnnotationExpr

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

pycroscope.annotations.type_from_runtime(val: object, visitor: CanAssignContext | None = None, node: AST | None = None, globals: Mapping[str, object] | None = None, ctx: Context | None = None, suppress_errors: bool = False, allow_undefined_names: bool = False) → Value

Given a runtime annotation object, return a pycroscope.value.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.

pycroscope.annotations.type_from_value(value: Value, visitor: CanAssignContext | None = None, node: AST | None = None, ctx: Context | None = None, suppress_errors: bool = False, allow_undefined_names: bool = False) → Value

Given a pycroscope.value.Value representing an annotation, return a pycroscope.value.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 – pycroscope.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.

class pycroscope.annotations.RuntimeAnnotationsContext(owner: object, node: ast.AST | None = None, *, self_key: type | pycroscope.value.ClassOwner | None, visitor: pycroscope.annotations.AnnotationVisitor | None = None, can_assign_ctx: pycroscope.value.CanAssignContext | None = None, active_type_params: pycroscope.type_params.ActiveTypeParams = <factory>, new_type_param_owner: type | pycroscope.value.ClassOwner | pycroscope.value.FunctionOwner | pycroscope.value.AliasOwner | typing_extensions.Sentinel | None = None)
class pycroscope.annotations.DecoratorValue(decorator: object, args: tuple[pycroscope.value.Value, ...])