pycroscope.name_check_visitor

The core of the pycroscope type checker.

NameCheckVisitor is the AST visitor that powers pycroscope’s type inference. It is the central object that invokes other parts of the system.

class pycroscope.name_check_visitor.ComprehensionLengthInferenceLimit(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

If we iterate over something longer than this, we don’t try to infer precise types for comprehensions. Increasing this can hurt performance.

class pycroscope.name_check_visitor.UnionSimplificationLimit(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

We may simplify unions with more than this many values.

class pycroscope.name_check_visitor.OutputFormatOption(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Output format for reported errors (“detailed” or “concise”).

class pycroscope.name_check_visitor.DisallowCallsToDunders(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Set of dunder methods (e.g., ‘{“__lshift__”}’) that pycroscope is not allowed to call on objects.

class pycroscope.name_check_visitor.DisallowedImports(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

List of imports that will trigger an error.

Entries may be top-level modules (e.g., “os”) or dotted submodule paths (e.g., “os.path”).

class pycroscope.name_check_visitor.ForLoopAlwaysEntered(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

If True, we assume that for loops are always entered at least once, which affects the potentially_undefined_name check. This will miss some bugs but also remove some annoying false positives.

class pycroscope.name_check_visitor.IgnoreNoneAttributes(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

If True, we ignore None when type checking attribute access on a Union type.

class pycroscope.name_check_visitor.UnimportableModules(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Do not attempt to import these modules if they are imported within a function.

class pycroscope.name_check_visitor.ExtraBuiltins(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Even if these variables are undefined, no errors are shown.

class pycroscope.name_check_visitor.IgnoredPaths(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Attribute accesses on these do not result in errors.

class pycroscope.name_check_visitor.IgnoredEndOfReference(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

When these attributes are accessed but they don’t exist, the error is ignored.

class pycroscope.name_check_visitor.IgnoredForIncompatibleOverride(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

These attributes are not checked for incompatible overrides.

class pycroscope.name_check_visitor.IgnoredUnusedAttributes(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

When these attributes are unused, they are not listed as such by the unused attribute finder.

class pycroscope.name_check_visitor.IgnoredUnusedAttributePaths(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Fully-qualified attribute paths to suppress in unused-attribute results.

Each entry should look like package.module.ClassName.attribute.

class pycroscope.name_check_visitor.IgnoredUnusedClassAttributes(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

List of pairs of (class, set of attribute names). When these attribute names are seen as unused on a child or base class of the class, they are not listed.

class pycroscope.name_check_visitor.IgnoreUnusedAttributePredicates(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Predicates that suppress specific unused class-attribute reports.

Each predicate receives the declaring class and attribute name. If it returns True, the unused-attribute report is skipped.

class pycroscope.name_check_visitor.UnusedClassAttribute(typ: type, attr_name: str, is_method: bool)

class pycroscope.name_check_visitor.CheckForDuplicateValues(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

For subclasses of these classes, we error if multiple attributes have the same value. This is used for the duplicate_enum check.

class pycroscope.name_check_visitor.AllowDuplicateValues(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

For subclasses of these classes, we do not error if multiple attributes have the same value. This overrides CheckForDuplicateValues.

class pycroscope.name_check_visitor.TransformGlobals(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Transform global variables.

class pycroscope.name_check_visitor.IgnoredTypesForAttributeChecking(value: T, applicable_to: tuple[str, ...] = (), from_command_line: bool = False, priority: int = 0)

Used in the check for object attributes that are accessed but not set. In general, the check will only alert about attributes that don’t exist when it has visited all the base classes of the class with the possibly missing attribute. However, these classes are never going to be visited (since they’re builtin), but they don’t set any attributes that we rely on.

class pycroscope.name_check_visitor.ClassAttributeChecker(*, enabled: bool = True, should_check_unused_attributes: bool = False, should_serialize: bool = False, options: Options = Options(options={}, module_path=()), ts_finder: TypeshedFinder | None = None)

Helper class to keep track of attributes that are read and set on instances.

record_attribute_read(typ: type, attr_name: str, node: AST, visitor: NameCheckVisitor) → None

Records that attribute attr_name was accessed on type typ.

record_attribute_set(typ: type | ClassOwner, attr_name: str, node: AST | None, value: Value, *, is_synthetic: bool = False) → None

Records that attribute attr_name was set on type typ.

record_class_examined(cls: type) → None

Records that we examined the attributes of class cls.

serialize_type(typ: type | ClassOwner) → object

Serialize a type so it is pickleable.

We do this to make it possible to pass ClassAttributeChecker objects around to parallel workers.

get_attribute_value(typ: type, attr_name: str) → Value

Gets the current recorded value of the attribute.

check_attribute_reads() → None

Checks that all recorded attribute reads refer to valid attributes.

This is done by checking for each read whether the class has the attribute or whether any code sets the attribute on a class instance, among other conditions.

check_unused_attributes() → None

Attempts to find attributes.

This is still approximate, but it reasons about inheritance by resolving each recorded read against the receiver class and all examined subclasses.

class pycroscope.name_check_visitor.StackedContexts

Object to keep track of a stack of states.

This is used to indicate all the AST node types that are parents of the node being examined.

class pycroscope.name_check_visitor.CallSiteCollector

Class to record function calls with their origin.

class pycroscope.name_check_visitor.NameCheckVisitor(filename: str, contents: str, tree: Module, *, settings: Mapping[Error, bool] | None = None, fail_after_first: bool = False, verbosity: int = 50, unused_finder: UnusedObjectFinder | None = None, module: ModuleType | None = None, attribute_checker: ClassAttributeChecker | None = None, collector: CallSiteCollector | None = None, annotate: bool = False, add_ignores: bool = False, checker: Checker, is_code_only: bool = False)

Visitor class that infers the type and value of Python objects and detects errors.

config_filename: ClassVar[str | None] = None

Path (relative to this class’s file) to a pyproject.toml config file.

record_any_used() → None

Record that Any was used to secure a match.

check(ignore_missing_module: bool = False) → list[Failure]

Run the visitor on this module.

visit(node: AST) → Value

Visit a node and return the pycroscope.value.Value corresponding to the node.

resolve_name(node: Name, error_node: AST | None = None, suppress_errors: bool = False) → tuple[Value, frozenset[object | None]]

Resolves a Name node to a value.

Parameters:

• node (ast.AST) – Node to resolve the name from

• error_node (Optional[ast.AST]) – If given, this AST node is used instead of node for displaying errors.

• suppress_errors (bool) – If True, do not produce errors if the name is undefined.

compute_function_info(node: FunctionDef | AsyncFunctionDef | Lambda, *, is_nested_in_class: bool = False, enclosing_class: TypedValue | None = None, potential_function: object | None = None) → Generator[FunctionInfo, None, None]

Visits a function’s decorator list.

get_attribute(root_composite: Composite, attr: str, node: AST | None = None, *, ignore_none: bool = False, use_fallback: bool = False, record_reads: bool = True, self_value: Value | None = None) → Value

Get an attribute of this value.

Returns pycroscope.value.UNINITIALIZED_VALUE if the attribute cannot be found.

varname_for_constraint(node: AST) → VarnameWithOrigin | None

Given a node, returns a variable name that could be used in a local scope.

varname_for_self_constraint(node: AST | None) → VarnameWithOrigin | None

Helper for constraints on self from method calls.

Given an ast.Call node representing a method call, return the variable name to be used for a constraint on the self object.

pycroscope.name_check_visitor.get_task_cls(fn: object) → type[Any]

Returns the task class for an async function.