mypy.server.astdiff

module documentation
(source)

Utilities for comparing two versions of a module symbol table.

The goal is to find which AST nodes have externally visible changes, so that we can fire triggers and re-process other parts of the program that are stale because of the changes.

Only look at detail at definitions at the current module -- don't recurse into other modules.

A summary of the module contents:

  • snapshot_symbol_table(...) creates an opaque snapshot description of a module/class symbol table (recursing into nested class symbol tables).
  • compare_symbol_table_snapshots(...) compares two snapshots for the same module id and returns fully qualified names of differences (which act as triggers).

To compare two versions of a module symbol table, take snapshots of both versions and compare the snapshots. The use of snapshots makes it easy to compare two versions of the same symbol table that is being mutated.

Summary of how this works for certain kinds of differences:

  • If a symbol table node is deleted or added (only present in old/new version of the symbol table), it is considered different, of course.
  • If a symbol table node refers to a different sort of thing in the new version, it is considered different (for example, if a class is replaced with a function).
  • If the signature of a function has changed, it is considered different.
  • If the type of a variable changes, it is considered different.
  • If the MRO of a class changes, or a non-generic class is turned into a generic class, the class is considered different (there are other such "big" differences that cause a class to be considered changed). However, just changes to attributes or methods don't generally constitute a difference at the class level -- these are handled at attribute level (say, 'mod.Cls.method' is different rather than 'mod.Cls' being different).
  • If an imported name targets a different name (say, 'from x import y' is replaced with 'from z import y'), the name in the module is considered different. If the target of an import continues to have the same name, but it's specifics change, this doesn't mean that the imported name is treated as changed. Say, there is 'from x import y' in 'm', and the type of 'x.y' has changed. This doesn't mean that that 'm.y' is considered changed. Instead, processing the difference in 'm' will be handled through fine-grained dependencies.
Class ​Snapshot​Type​Visitor Creates a read-only, self-contained snapshot of a type object.
Function compare​_symbol​_table​_snapshots Return names that are different in two snapshots of a symbol table.
Function encode​_optional​_str Undocumented
Function snapshot​_definition Create a snapshot description of a symbol table node.
Function snapshot​_optional​_type Undocumented
Function snapshot​_simple​_type Undocumented
Function snapshot​_symbol​_table Create a snapshot description that represents the state of a symbol table.
Function snapshot​_type Create a snapshot representation of a type using nested tuples.
Function snapshot​_types Undocumented
Function snapshot​_untyped​_signature Create a snapshot of the signature of a function that has no explicit signature.
Variable ​Snapshot​Item Undocumented
def compare_symbol_table_snapshots(name_prefix, snapshot1, snapshot2): (source)

Return names that are different in two snapshots of a symbol table.

Only shallow (intra-module) differences are considered. References to things defined outside the module are compared based on the name of the target only.

Recurse into class symbol tables (if the class is defined in the target module).

Return a set of fully-qualified names (e.g., 'mod.func' or 'mod.Class.method').

Parameters
name​_prefix:strUndocumented
snapshot1:Dict[str, SnapshotItem]Undocumented
snapshot2:Dict[str, SnapshotItem]Undocumented
Returns
Set[str]Undocumented
def encode_optional_str(s): (source)

Undocumented

Parameters
s:Optional[str]Undocumented
Returns
strUndocumented
def snapshot_definition(node, common): (source)

Create a snapshot description of a symbol table node.

The representation is nested tuples and dicts. Only externally visible attributes are included.

Parameters
node:Optional[SymbolNode]Undocumented
common:Tuple[object, ...]Undocumented
Returns
Tuple[object, ...]Undocumented
def snapshot_optional_type(typ): (source)

Undocumented

Parameters
typ:Optional[Type]Undocumented
Returns
Optional[SnapshotItem]Undocumented
def snapshot_simple_type(typ): (source)

Undocumented

Parameters
typ:TypeUndocumented
Returns
SnapshotItemUndocumented
def snapshot_symbol_table(name_prefix, table): (source)

Create a snapshot description that represents the state of a symbol table.

The snapshot has a representation based on nested tuples and dicts that makes it easy and fast to find differences.

Only "shallow" state is included in the snapshot -- references to things defined in other modules are represented just by the names of the targets.

Parameters
name​_prefix:strUndocumented
table:SymbolTableUndocumented
Returns
Dict[str, SnapshotItem]Undocumented
def snapshot_type(typ): (source)
Create a snapshot representation of a type using nested tuples.
Parameters
typ:TypeUndocumented
Returns
SnapshotItemUndocumented
def snapshot_types(types): (source)

Undocumented

Parameters
types:Sequence[Type]Undocumented
Returns
SnapshotItemUndocumented
def snapshot_untyped_signature(func): (source)

Create a snapshot of the signature of a function that has no explicit signature.

If the arguments to a function without signature change, it must be considered as different. We have this special casing since we don't store the implicit signature anywhere, and we'd rather not construct new Callable objects in this module (the idea is to only read properties of the AST here).

Parameters
func:Union[OverloadedFuncDef, FuncItem]Undocumented
Returns
Tuple[object, ...]Undocumented
SnapshotItem = (source)

Undocumented