From 9f645d3fc84efff84de39473678b6b30d9690a45 Mon Sep 17 00:00:00 2001 From: Ivan Levkivskyi Date: Tue, 13 Aug 2019 15:46:16 +0100 Subject: [PATCH] Restore docstring for aststrip.py --- mypy/server/aststrip.py | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/mypy/server/aststrip.py b/mypy/server/aststrip.py index 96e627c7a8f4..a8a07a05e174 100644 --- a/mypy/server/aststrip.py +++ b/mypy/server/aststrip.py @@ -1,6 +1,34 @@ -""" -This module essentially copies functionality of server/aststrip.py. See its docstring for details. -TODO: copy docstring here, when this is the default implementation. +"""Strip/reset AST in-place to match state after semantic analyzer pre-analysis. + +Fine-grained incremental mode reruns semantic analysis main pass +and type checking for *existing* AST nodes (targets) when changes are +propagated using fine-grained dependencies. AST nodes attributes are +sometimes changed during semantic analysis main pass, and running +semantic analysis again on those nodes would produce incorrect +results, since this pass isn't idempotent. This pass resets AST +nodes to reflect the state after semantic pre-analysis, so that we +can rerun semantic analysis. +(The above is in contrast to behavior with modules that have source code +changes, for which we re-parse the entire module and reconstruct a fresh +AST. No stripping is required in this case. Both modes of operation should +have the same outcome.) +Notes: +* This is currently pretty fragile, as we must carefully undo whatever + changes can be made in semantic analysis main pass, including changes + to symbol tables. +* We reuse existing AST nodes because it makes it relatively straightforward + to reprocess only a single target within a module efficiently. If there + was a way to parse a single target within a file, in time proportional to + the size of the target, we'd rather create fresh AST nodes than strip them. + (This is possible only in Python 3.8+) +* Currently we don't actually reset all changes, but only those known to affect + non-idempotent semantic analysis behavior. + TODO: It would be more principled and less fragile to reset everything + changed in semantic analysis main pass and later. +* Reprocessing may recreate AST nodes (such as Var nodes, and TypeInfo nodes + created with assignment statements) that will get different identities from + the original AST. Thus running an AST merge is necessary after stripping, + even though some identities are preserved. """ import contextlib