Skip to content

Commit 2002ae1

Browse files
authored
Restore docstring for aststrip.py (#7332)
1 parent 882e37e commit 2002ae1

File tree

1 file changed

+31
-3
lines changed

1 file changed

+31
-3
lines changed

mypy/server/aststrip.py

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,34 @@
1-
"""
2-
This module essentially copies functionality of server/aststrip.py. See its docstring for details.
3-
TODO: copy docstring here, when this is the default implementation.
1+
"""Strip/reset AST in-place to match state after semantic analyzer pre-analysis.
2+
3+
Fine-grained incremental mode reruns semantic analysis main pass
4+
and type checking for *existing* AST nodes (targets) when changes are
5+
propagated using fine-grained dependencies. AST nodes attributes are
6+
sometimes changed during semantic analysis main pass, and running
7+
semantic analysis again on those nodes would produce incorrect
8+
results, since this pass isn't idempotent. This pass resets AST
9+
nodes to reflect the state after semantic pre-analysis, so that we
10+
can rerun semantic analysis.
11+
(The above is in contrast to behavior with modules that have source code
12+
changes, for which we re-parse the entire module and reconstruct a fresh
13+
AST. No stripping is required in this case. Both modes of operation should
14+
have the same outcome.)
15+
Notes:
16+
* This is currently pretty fragile, as we must carefully undo whatever
17+
changes can be made in semantic analysis main pass, including changes
18+
to symbol tables.
19+
* We reuse existing AST nodes because it makes it relatively straightforward
20+
to reprocess only a single target within a module efficiently. If there
21+
was a way to parse a single target within a file, in time proportional to
22+
the size of the target, we'd rather create fresh AST nodes than strip them.
23+
(This is possible only in Python 3.8+)
24+
* Currently we don't actually reset all changes, but only those known to affect
25+
non-idempotent semantic analysis behavior.
26+
TODO: It would be more principled and less fragile to reset everything
27+
changed in semantic analysis main pass and later.
28+
* Reprocessing may recreate AST nodes (such as Var nodes, and TypeInfo nodes
29+
created with assignment statements) that will get different identities from
30+
the original AST. Thus running an AST merge is necessary after stripping,
31+
even though some identities are preserved.
432
"""
533

634
import contextlib

0 commit comments

Comments
 (0)