mypy.server.astmerge

Merge a new version of a module AST and symbol table to older versions of those.

When the source code of a module has a change in fine-grained incremental mode, we build a new AST from the updated source. However, other parts of the program may have direct references to parts of the old AST (namely, those nodes exposed in the module symbol table). The merge operation changes the identities of new AST nodes that have a correspondence in the old AST to the old ones so that existing cross-references in other modules will continue to point to the correct nodes. Also internal cross-references within the new AST are replaced. AST nodes that aren't externally visible will get new, distinct object identities. This applies to most expression and statement nodes, for example.

We perform this merge operation so that we don't have to update all external references (which would be slow and fragile) or always perform translation when looking up references (which would be hard to retrofit).

The AST merge operation is performed after semantic analysis. Semantic analysis has to deal with potentially multiple aliases to certain AST nodes (in particular, MypyFile nodes). Type checking assumes that we don't have multiple variants of a single AST node visible to the type checker.

Discussion of some notable special cases:

• If a node is replaced with a different kind of node (say, a function is replaced with a class), we don't perform the merge. Fine-grained dependencies will be used to rebind all references to the node.
• If a function is replaced with another function with an identical signature, call sites continue to point to the same object (by identity) and don't need to be reprocessed. Similarly, if a class is replaced with a class that is sufficiently similar (MRO preserved, etc.), class references don't need any processing. A typical incremental update to a file only changes a few externally visible things in a module, and this means that often only few external references need any processing, even if the modified module is large.
• A no-op update of a module should not require any processing outside the module, since all relevant object identities are preserved.
• The AST diff operation (mypy.server.astdiff) and the top-level fine-grained incremental logic (mypy.server.update) handle the cases where the new AST has differences from the old one that may need to be propagated to elsewhere in the program.

See the main entry point merge_asts for more details.