ml_switcheroo.core.rewriter

Rewriter Package.

This package provides the core AST transformation logic via a composable pipeline.

Components: - RewriterPipeline: Orchestrates the execution of sequence passes. - RewriterContext: Shared state container (Symbol Table, Semantics). - RewriterPass: Base interface for transformation logic.

Core Passes: - StructuralPass: Handles class inheritance, method renaming, signature changes. - ApiPass: Handles API mapping, argument pivoting, and macro expansion. - AuxiliaryPass: Handles decorators and control flow safety.

Submodules

• ml_switcheroo.core.rewriter.context
• ml_switcheroo.core.rewriter.interface
• ml_switcheroo.core.rewriter.normalization_utils
• ml_switcheroo.core.rewriter.passes
• ml_switcheroo.core.rewriter.patcher
• ml_switcheroo.core.rewriter.pipeline
• ml_switcheroo.core.rewriter.types

Classes

RewriterContext	Shared state container for the rewriting pipeline.
RewriterPipeline	Manages a sequence of rewriting passes and executes them in order.
RewriterPass	Abstract contract for a transformation pass in the rewriting pipeline.
StructuralPass	Pass responsible for modifying the structural scaffolding of the code.
ApiPass	Transformation pass for rewiring API usage.
AuxiliaryPass	Pass dealing with auxiliary syntax constructs: decorators and control flow.

Package Contents

class ml_switcheroo.core.rewriter.RewriterContext(semantics: ml_switcheroo.semantics.manager.SemanticsManager, config: ml_switcheroo.config.RuntimeConfig, symbol_table: ml_switcheroo.analysis.symbol_table.SymbolTable | None = None, arg_injector: Callable[[str, str | None], None] | None = None, preamble_injector: Callable[[str], None] | None = None)

Shared state container for the rewriting pipeline.

Encapsulates all mutable state required during the AST traversal, allowing multiple RewriterStage passes to operate on a consistent context.

semantics

config

symbol_table = None

scope_stack: List[Set[str]]

signature_stack: List[ml_switcheroo.core.rewriter.types.SignatureContext] = []

alias_map: Dict[str, str]

current_stmt_errors: List[str] = []

current_stmt_warnings: List[str] = []

module_preamble: List[str] = []

in_module_class: bool = False

hook_context

property source_fw: str

Returns effective source framework string.

property target_fw: str

Returns effective target framework string.

class ml_switcheroo.core.rewriter.RewriterPipeline(passes: List[ml_switcheroo.core.rewriter.interface.RewriterPass])

Manages a sequence of rewriting passes and executes them in order.

passes

run(module: libcst.Module, context: ml_switcheroo.core.rewriter.context.RewriterContext) → libcst.Module

Executes all registered passes sequentially on the module.

Parameters:

• module – The source AST to transform.

• context – The shared execution state containing semantics and config.

Returns:

The fully transformed AST.

class ml_switcheroo.core.rewriter.RewriterPass

Bases: abc.ABC

Abstract contract for a transformation pass in the rewriting pipeline.

Passes encapsulate discrete transformation logic (e.g. Structural Rewriting, API Remapping) and are executed sequentially by the pipeline.

abstractmethod transform(module: libcst.Module, context: ml_switcheroo.core.rewriter.context.RewriterContext) → libcst.Module

Executes the transformation logic on the given CST module.

Parameters:

• module – The input LibCST module.

• context – The shared rewriter context containing configuration and state.

Returns:

The transformed LibCST module.

class ml_switcheroo.core.rewriter.StructuralPass

Bases: ml_switcheroo.core.rewriter.interface.RewriterPass

Pass responsible for modifying the structural scaffolding of the code.

It transforms class definitions, function signatures, and type hints to match the idioms of the target framework.

transform(module: libcst.Module, context: ml_switcheroo.core.rewriter.context.RewriterContext) → libcst.Module

Executes the structural transformation.

Parameters:

• module – The source CST.

• context – Shared rewriter state.

Returns:

The transformed CST.

class ml_switcheroo.core.rewriter.ApiPass

Bases: ml_switcheroo.core.rewriter.interface.RewriterPass

Transformation pass for rewiring API usage.

Handles resolving function calls to Abstract Operations (The Hub) and then projecting them to the Target Framework (The Spoke). Also handles attribute renaming and stateful assignment tracking.

transform(module: libcst.Module, context: ml_switcheroo.core.rewriter.context.RewriterContext) → libcst.Module

Executes the API transformation logic.

Parameters:

• module – The source CST.

• context – Shared rewriter state.

Returns:

The transformed CST.

class ml_switcheroo.core.rewriter.AuxiliaryPass

Bases: ml_switcheroo.core.rewriter.interface.RewriterPass

Pass dealing with auxiliary syntax constructs: decorators and control flow.

transform(module: libcst.Module, context: ml_switcheroo.core.rewriter.context.RewriterContext) → libcst.Module

Executes the auxiliary transformation logic.

Parameters:

• module – The source CST.

• context – Shared state.

Returns:

The transformed CST.