Introduce the astcompile pass

[antocuni]

This PR introduces a new pass astcompile in the pipeline.
astcompile takes a "parsed" AST and produce a new AST which is more suited for execution.

In particular, it handles:

• ast.Name specialization: depending on the symbol, it becomes ast.NameLocalDirect, ast.NameOuterCell, etc.
• ast.Assign specialization: similar to above, it becomes ast.AssignLocal, ast.AssignOuter, etc.
• for loop desugaring
• augmented assign desugaring

Previously, all these transformation were done at runtime by ASTFrame, and then saved on the ugly dicts ASTFrame._specialized_names, etc., so that they could be reused by DopplerFrame.

Having a separate pass makes it easier to inspect the result and to add more desugaring when needed.

While we were at it, we also simplified the relationship between ast.Assign and ast.AssignExpr. Now all the logic is done by the various AssignExpr variants, and the statement versions are just thin wrappers over them. This makes it possible to reduce code duplication and make the whole logic easier.

For example, given:

X = 1
def main() -> None:
    y = X

❯ spy astcompile /tmp/x.spy 
Module(
    stage='astcompiled',
    filename='/tmp/x.spy',
    docstring=None,
    decls=[
        ...
        GlobalFuncDef(
            funcdef=FuncDef(
                stage='astcompiled',
                ...
                body=[
                    AssignLocal(
                        expr=AssignExprLocal(
                            target=StrLiteral(value='y'),
                            sym=Symbol('y', 'const', 'direct'),
                            value=NameOuterDirect(
                                sym=Symbol('X', 'const', 'direct'),
[...]

Note that:

• we have a new stage attribute which keeps track of which lowering we did so far
• we have specialized AssignLocal and NameOuterDirect nodes

We can also use the spy backend, useful for e.g. this:

def main() -> None:
    for i in range(10):
        print(i)

❯ spy astcompile --format spy /tmp/x.spy 
def main() -> None:
    _$iter0 = range(10).__fastiter__()
    while _$iter0.__continue_iteration__():
        i = _$iter0.__item__()
        _$iter0 = _$iter0.__next__()
        print(i)

[github-actions]

Documentation Preview
Preview documentation for PR #649.
Last Updated: 2026-08-10 22:20 UTC