cellgraph 0.1.0__py3-none-any.whl

cellgraph/python.py

@@ -0,0 +1,672 @@
+"""The Python language analyzer: defines and references from the AST and symtable.
+
+Ported from Strata's ``notebook/analyzer.py`` as is.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+import symtable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from cellgraph.languages import Analyzed
+
+if TYPE_CHECKING:
+    from cellgraph.analysis import Cell
+
+
+@dataclass
+class CellAnalysis:
+    """Result of analyzing a single cell; ``error`` is None on success."""
+
+    defines: list[str] = field(default_factory=list)
+    references: list[str] = field(default_factory=list)
+    # Defines from in-place mutation (``df["col"] = ...``). The harness forces
+    # serialization of these even when the mutation preserved ``id()``.
+    mutation_defines: list[str] = field(default_factory=list)
+    # Free names that are builtins, kept out of ``references`` so every
+    # ``print``/``len`` caller doesn't list them. A cell can still define
+    # ``input = ...``, so the DAG resolves these against producers too: an
+    # unshadowed builtin wires nothing, a shadowed one gets its edge.
+    builtin_references: list[str] = field(default_factory=list)
+    error: str | None = None
+
+
+def imported_names(source: str) -> set[str]:
+    """Top-level names bound by ``import`` statements in *source*.
+
+    A consumer missing one can re-import it, unlike a missing data artifact, so
+    this picks the log level for an absent upstream artifact. Binding rule
+    matches :meth:`VariableAnalyzer.visit_Import`; star imports contribute nothing.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+    names: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                if alias.name == "*":
+                    continue
+                names.add(alias.asname or alias.name.split(".")[0])
+    return names
+
+
+def _collect_name_targets(target: ast.expr, out: set[str]) -> None:
+    """Recursively collect Name ids from an assignment target.
+
+    Handles ``x``, tuple/list unpacking and ``*rest``. Subscript and attribute
+    targets are mutations and are ignored here.
+    """
+    if isinstance(target, ast.Name):
+        out.add(target.id)
+    elif isinstance(target, (ast.Tuple, ast.List)):
+        for elt in target.elts:
+            _collect_name_targets(elt, out)
+    elif isinstance(target, ast.Starred):
+        _collect_name_targets(target.value, out)
+
+
+def _type_param_names(params: list[ast.type_param]) -> set[str]:
+    """Names bound by PEP 695 type parameters (``[T, *Ts, **P]``)."""
+    return {p.name for p in params if isinstance(p, (ast.TypeVar, ast.TypeVarTuple, ast.ParamSpec))}
+
+
+def _has_inplace_true(keywords: list[ast.keyword]) -> bool:
+    """Return whether a call's keywords contain a literal ``inplace=True``."""
+    return any(
+        kw.arg == "inplace" and isinstance(kw.value, ast.Constant) and kw.value.value is True
+        for kw in keywords
+    )
+
+
+class VariableAnalyzer(ast.NodeVisitor):
+    """AST visitor that collects defined and referenced variables."""
+
+    def __init__(self):
+        """Initialize the analyzer."""
+        self.defines: set[str] = set()
+        self.references: set[str] = set()
+        # Pure ``x = ...`` targets. ``df = ...`` then ``df["col"] = ...`` in
+        # one cell is a local define, not a mutation of an upstream.
+        self.pure_defines: set[str] = set()
+        # Subscript/attribute mutations. Unlike pure rebinds these stay in
+        # references: the cell depends on an upstream producer.
+        self.mutation_defines: set[str] = set()
+        # Names read before the cell binds them (``df = df.dropna()``,
+        # ``print(x); x = 5``): genuine upstream references that survive the
+        # pure-define filter.
+        self.read_before_define: set[str] = set()
+        # Names bound so far in source order: tells ``x = 0\nx += 1``
+        # (local) from a bare ``x += 1`` (upstream read).
+        self._defined_so_far: set[str] = set()
+        self._in_nested_scope = False
+        self._local_vars: set[str] = set()  # Track local scope variables
+        # PEP 563 stringifies annotations, so under it they are not
+        # runtime references.
+        self._future_annotations: bool = False
+
+    def visit_Module(self, node: ast.Module) -> None:
+        """Visit module: process top-level statements."""
+        self._future_annotations = any(
+            isinstance(s, ast.ImportFrom)
+            and s.module == "__future__"
+            and any(alias.name == "annotations" for alias in s.names)
+            for s in node.body
+        )
+        for child in node.body:
+            self.visit(child)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        """Handle: x = ... or x, y = ..."""
+        all_underscore = all(self._is_pure_underscore(target) for target in node.targets)
+        if not all_underscore:
+            # The RHS runs before the targets bind, so ``x = x + 1`` and swaps
+            # like ``a, b = b, a`` read the upstream value.
+            self.visit(node.value)
+        for target in node.targets:
+            self._add_assign_target(target)
+            _collect_name_targets(target, self._defined_so_far)
+
+    def _is_pure_underscore(self, target: ast.expr) -> bool:
+        """Check if a target is a pure _ (not part of unpacking)."""
+        if isinstance(target, ast.Name):
+            return target.id == "_"
+        return False
+
+    def visit_AugAssign(self, node: ast.AugAssign) -> None:
+        """Handle: x += ... or df["col"] += ...
+
+        The LHS is implicitly read, so a Name target is added to references
+        (unless the cell already pure-defined it earlier); without that the DAG
+        misses the upstream edge and the cell hits NameError. Subscript and
+        attribute targets go through ``_add_assign_target``.
+        """
+        if isinstance(node.target, ast.Name):
+            if node.target.id not in self._defined_so_far:
+                self.references.add(node.target.id)
+                self.read_before_define.add(node.target.id)
+        self._add_assign_target(node.target)
+        self.visit(node.value)
+        if isinstance(node.target, ast.Name):
+            self._defined_so_far.add(node.target.id)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        """Handle: x: int = ... or x: int (without value)."""
+        self._add_assign_target(node.target)
+        # Module-scope annotations are evaluated at runtime unless PEP 563.
+        if not self._future_annotations:
+            self.visit(node.annotation)
+        if node.value:
+            self.visit(node.value)
+            if isinstance(node.target, ast.Name):
+                self._defined_so_far.add(node.target.id)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        """Treat ``X.method(..., inplace=True)`` as a mutation of ``X``.
+
+        Otherwise ``df`` looks read-only, and in the shared-namespace batch path
+        a downstream cell sees the mutated object while the stored artifact holds
+        the old value. Only a literal ``inplace=True`` on an attribute call with a
+        name/attribute receiver counts.
+        """
+        if isinstance(node.func, ast.Attribute) and _has_inplace_true(node.keywords):
+            self._add_reference_target(node.func.value)
+            self._add_mutation_define(node.func.value)
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Handle: def f(): the name is defined, the body is a nested scope.
+
+        Decorators, defaults and annotations (unless PEP 563 is on) evaluate at
+        module load, so their free names are module references. Body free names
+        come from the symtable pass.
+        """
+        self.defines.add(node.name)
+        self._visit_function_signature(node)
+        self._defined_so_far.add(node.name)
+        # Don't recurse into function body (it's a nested scope)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        """Handle: async def f(): ..."""
+        self.defines.add(node.name)
+        self._visit_function_signature(node)
+        self._defined_so_far.add(node.name)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Handle: class C: the name is defined, the body is a nested scope.
+
+        Decorators, bases and class keywords evaluate at module load and are
+        walked here; body free names come from the symtable pass.
+        """
+        self.defines.add(node.name)
+        for decorator in node.decorator_list:
+            self.visit(decorator)
+        old_local_vars = self._local_vars
+        self._local_vars = self._local_vars | _type_param_names(node.type_params)
+        for base in node.bases:
+            self.visit(base)
+        for kw in node.keywords:
+            self.visit(kw.value)
+        self._local_vars = old_local_vars
+        self._defined_so_far.add(node.name)
+        # Don't recurse into class body
+
+    def _visit_function_signature(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> None:
+        """Visit decorators, defaults and (without PEP 563) annotations of a function."""
+        for decorator in node.decorator_list:
+            self.visit(decorator)
+        for default in node.args.defaults:
+            self.visit(default)
+        for default in node.args.kw_defaults:
+            if default is not None:
+                self.visit(default)
+        if not self._future_annotations:
+            # PEP 695 type parameters are local to the signature's annotations.
+            old_local_vars = self._local_vars
+            self._local_vars = self._local_vars | _type_param_names(node.type_params)
+            if node.returns is not None:
+                self.visit(node.returns)
+            for arg_list in (node.args.posonlyargs, node.args.args, node.args.kwonlyargs):
+                for arg in arg_list:
+                    if arg.annotation is not None:
+                        self.visit(arg.annotation)
+            if node.args.vararg is not None and node.args.vararg.annotation is not None:
+                self.visit(node.args.vararg.annotation)
+            if node.args.kwarg is not None and node.args.kwarg.annotation is not None:
+                self.visit(node.args.kwarg.annotation)
+            self._local_vars = old_local_vars
+
+    def visit_Import(self, node: ast.Import) -> None:
+        """Handle: import foo, import foo as bar, or import foo.bar (binds ``foo``)."""
+        for alias in node.names:
+            name = alias.asname if alias.asname else alias.name.split(".")[0]
+            self.defines.add(name)
+            self._defined_so_far.add(name)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        """Handle: from foo import bar or from foo import *."""
+        for alias in node.names:
+            if alias.name == "*":
+                # Star imports: defines are unknowable, skip.
+                pass
+            else:
+                name = alias.asname if alias.asname else alias.name
+                self.defines.add(name)
+                self._defined_so_far.add(name)
+
+    def visit_For(self, node: ast.For) -> None:
+        """Handle ``for x in ...``: x is defined at top level."""
+        self._add_assign_target(node.target)
+        self.visit(node.iter)
+        _collect_name_targets(node.target, self._defined_so_far)
+        for stmt in node.body:
+            self.visit(stmt)
+        for stmt in node.orelse:
+            self.visit(stmt)
+
+    def visit_With(self, node: ast.With) -> None:
+        """Handle ``with ... as x``: x is defined at top level."""
+        for item in node.items:
+            if item.optional_vars:
+                self._add_assign_target(item.optional_vars)
+            self.visit(item.context_expr)
+            if item.optional_vars:
+                _collect_name_targets(item.optional_vars, self._defined_so_far)
+        for stmt in node.body:
+            self.visit(stmt)
+
+    def visit_AsyncWith(self, node: ast.AsyncWith) -> None:
+        """Handle: async with ... as x:"""
+        for item in node.items:
+            if item.optional_vars:
+                self._add_assign_target(item.optional_vars)
+            self.visit(item.context_expr)
+            if item.optional_vars:
+                _collect_name_targets(item.optional_vars, self._defined_so_far)
+        for stmt in node.body:
+            self.visit(stmt)
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
+        """Handle ``except E as e``: e is defined at top level."""
+        if node.name:
+            self.defines.add(node.name)
+        if node.type:
+            self.visit(node.type)
+        if node.name:
+            self._defined_so_far.add(node.name)
+        for stmt in node.body:
+            self.visit(stmt)
+
+    def visit_NamedExpr(self, node: ast.NamedExpr) -> None:
+        """Handle: walrus operator := at top level."""
+        if isinstance(node.target, ast.Name):
+            self.defines.add(node.target.id)
+        self.visit(node.value)
+        if isinstance(node.target, ast.Name):
+            self._defined_so_far.add(node.target.id)
+
+    def visit_TypeAlias(self, node: ast.TypeAlias) -> None:
+        """Handle: type A = ... (PEP 695); the lazy value's names come from symtable."""
+        self._add_assign_target(node.name)
+        _collect_name_targets(node.name, self._defined_so_far)
+
+    def visit_MatchAs(self, node: ast.MatchAs) -> None:
+        """Handle: case [x] / case P() as x: the capture binds x."""
+        if node.pattern is not None:
+            self.visit(node.pattern)
+        if node.name is not None:
+            self._bind_capture(node.name)
+
+    def visit_MatchStar(self, node: ast.MatchStar) -> None:
+        """Handle: case [first, *rest]."""
+        if node.name is not None:
+            self._bind_capture(node.name)
+
+    def visit_MatchMapping(self, node: ast.MatchMapping) -> None:
+        """Handle: case {"k": v, **rest}."""
+        for key in node.keys:
+            self.visit(key)
+        for pattern in node.patterns:
+            self.visit(pattern)
+        if node.rest is not None:
+            self._bind_capture(node.rest)
+
+    def _bind_capture(self, name: str) -> None:
+        self.defines.add(name)
+        self.pure_defines.add(name)
+        self._defined_so_far.add(name)
+
+    def visit_Delete(self, node: ast.Delete) -> None:
+        """Handle ``del x``: x is referenced but not defined."""
+        for target in node.targets:
+            self._add_delete_target(target)
+
+    def _add_delete_target(self, target: ast.expr) -> None:
+        """Add the root name of a ``del`` target (``x``, ``x.attr``, ``x[k]``) to references."""
+        if isinstance(target, ast.Name):
+            self.references.add(target.id)
+        elif isinstance(target, (ast.Tuple, ast.List)):
+            for elt in target.elts:
+                self._add_delete_target(elt)
+        elif isinstance(target, ast.Subscript):
+            self._add_delete_target(target.value)
+            self.visit(target.slice)
+        elif isinstance(target, ast.Attribute):
+            self._add_delete_target(target.value)
+
+    def visit_Name(self, node: ast.Name) -> None:
+        """Collect referenced names (Load context)."""
+        if isinstance(node.ctx, ast.Load):
+            # Skip names local to the current scope (e.g. lambda params)
+            if node.id not in self._local_vars:
+                self.references.add(node.id)
+                if node.id not in self._defined_so_far:
+                    self.read_before_define.add(node.id)
+
+    def visit_ListComp(self, node: ast.ListComp) -> None:
+        """``[elt for x in iter if cond]``: loop targets are local; the first iter is outer."""
+        self._visit_comprehension(node, [node.elt])
+
+    def visit_SetComp(self, node: ast.SetComp) -> None:
+        """``{elt for x in iter}``."""
+        self._visit_comprehension(node, [node.elt])
+
+    def visit_DictComp(self, node: ast.DictComp) -> None:
+        """``{k: v for x in iter}``: both key and value are scoped."""
+        self._visit_comprehension(node, [node.key, node.value])
+
+    def visit_GeneratorExp(self, node: ast.GeneratorExp) -> None:
+        """``(elt for x in iter)``."""
+        self._visit_comprehension(node, [node.elt])
+
+    def _visit_comprehension(
+        self,
+        node: ast.ListComp | ast.SetComp | ast.DictComp | ast.GeneratorExp,
+        elements: list[ast.expr],
+    ) -> None:
+        """Walk comprehension parts with loop variables locally scoped.
+
+        The first iterable runs in the outer scope; later iterables, elements
+        and ``if`` clauses see the loop variables. Python 3.13 inlines
+        comprehensions (PEP 709), so symtable has no child scope for them and
+        this AST tracking is what finds their free names.
+        """
+        if not node.generators:
+            return
+
+        # First generator's iter runs in the OUTER scope.
+        self.visit(node.generators[0].iter)
+
+        old_local_vars = self._local_vars
+        try:
+            local_vars = set(self._local_vars)
+            for gen in node.generators:
+                local_vars |= self._extract_target_names(gen.target)
+            self._local_vars = local_vars
+
+            # Element(s) and if-clauses see all loop targets.
+            for elt in elements:
+                self.visit(elt)
+            # Subsequent generators' iter expressions can see prior
+            # loop targets, so they get visited under the local scope.
+            for gen in node.generators[1:]:
+                self.visit(gen.iter)
+            for gen in node.generators:
+                for cond in gen.ifs:
+                    self.visit(cond)
+        finally:
+            self._local_vars = old_local_vars
+
+    def _extract_target_names(self, target: ast.expr) -> set[str]:
+        """Names bound by a comprehension or for-loop target."""
+        names: set[str] = set()
+        if isinstance(target, ast.Name):
+            names.add(target.id)
+        elif isinstance(target, (ast.Tuple, ast.List)):
+            for elt in target.elts:
+                names |= self._extract_target_names(elt)
+        elif isinstance(target, ast.Starred):
+            names |= self._extract_target_names(target.value)
+        return names
+
+    def visit_Lambda(self, node: ast.Lambda) -> None:
+        """Lambda expression: arguments are local scope."""
+        # Defaults evaluate in the enclosing scope, before params shadow.
+        for default in node.args.defaults:
+            self.visit(default)
+        for default in node.args.kw_defaults:
+            if default is not None:
+                self.visit(default)
+        old_local_vars = self._local_vars
+        self._local_vars = self._local_vars | self._get_lambda_params(node.args)
+        self.visit(node.body)
+        self._local_vars = old_local_vars
+
+    def _get_lambda_params(self, args: ast.arguments) -> set[str]:
+        """Extract parameter names from lambda arguments."""
+        params = set()
+        for arg in args.posonlyargs:
+            params.add(arg.arg)
+        for arg in args.args:
+            params.add(arg.arg)
+        if args.vararg:
+            params.add(args.vararg.arg)
+        for arg in args.kwonlyargs:
+            params.add(arg.arg)
+        if args.kwarg:
+            params.add(args.kwarg.arg)
+        return params
+
+    def _add_assign_target(self, target: ast.expr) -> None:
+        """Add the names an assignment target defines.
+
+        Subscript (``df["col"]``) and attribute (``obj.attr``) targets define
+        their root name.
+        """
+        if isinstance(target, ast.Name):
+            self.defines.add(target.id)
+            self.pure_defines.add(target.id)
+        elif isinstance(target, (ast.Tuple, ast.List)):
+            for elt in target.elts:
+                self._add_assign_target(elt)
+        elif isinstance(target, ast.Subscript):
+            # df["col"] = ...: reads df and produces the mutated df, so
+            # downstream reads route through this cell (else they can run
+            # before the mutation and KeyError).
+            self._add_reference_target(target.value)
+            self._add_mutation_define(target.value)
+        elif isinstance(target, ast.Attribute):
+            # obj.attr = ...: same as subscript mutation.
+            self._add_reference_target(target.value)
+            self._add_mutation_define(target.value)
+        elif isinstance(target, ast.Starred):
+            self._add_assign_target(target.value)
+
+    def _add_reference_target(self, node: ast.expr) -> None:
+        """Add the root name of an attribute/subscript mutation to references."""
+        if isinstance(node, ast.Name):
+            self.references.add(node.id)
+        elif isinstance(node, (ast.Attribute, ast.Subscript)):
+            self._add_reference_target(node.value)
+
+    def _add_mutation_define(self, node: ast.expr) -> None:
+        """Record the root name of a mutated target as a define.
+
+        The mutating cell produces the post-mutation value downstream cells see.
+        The name also stays in references (the mutation reads the prior value);
+        ``mutation_defines`` tells the caller not to strip it from them.
+        """
+        if isinstance(node, ast.Name):
+            self.defines.add(node.id)
+            self.mutation_defines.add(node.id)
+        elif isinstance(node, (ast.Attribute, ast.Subscript)):
+            self._add_mutation_define(node.value)
+
+
+def _collect_body_refs(source: str) -> set[str]:
+    """Names referenced inside function/class bodies that resolve via module globals.
+
+    The AST visitor stops at body boundaries; ``symtable`` does the real scope
+    analysis. The caller filters builtins, privates and defines.
+    """
+    try:
+        root = symtable.symtable(source, "<cell>", "exec")
+    except SyntaxError:
+        return set()
+
+    refs: set[str] = set()
+    for child in root.get_children():
+        _walk_body(child, refs)
+    return refs
+
+
+def _walk_body(scope: symtable.SymbolTable, refs: set[str]) -> None:
+    """Recursively collect names that fall through to module globals.
+
+    A symbol does iff it is referenced, ``is_global()``, and not local, a
+    parameter or a closure variable (``is_free()`` resolves via enclosing scopes).
+    """
+    for sym in scope.get_symbols():
+        if (
+            sym.is_referenced()
+            and sym.is_global()
+            and not sym.is_local()
+            and not sym.is_parameter()
+            and not sym.is_free()
+        ):
+            refs.add(sym.get_name())
+    for inner in scope.get_children():
+        _walk_body(inner, refs)
+
+
+def _collect_global_writes(source: str) -> tuple[set[str], set[str]]:
+    """Names a function binds at module scope through ``global X; X = ...``.
+
+    The AST visitor only sees module-level defines, so it misses these.
+
+    Returns ``(writes, writes_with_reads)``; the second subset is also read in
+    the function and stays in references, so the DAG records the cell as both
+    consumer and producer. A bare ``global X`` without an assign, and
+    ``nonlocal``, bind nothing at module scope and are skipped.
+    """
+    try:
+        root = symtable.symtable(source, "<cell>", "exec")
+    except SyntaxError:
+        return set(), set()
+    writes: set[str] = set()
+    read_writes: set[str] = set()
+    for child in root.get_children():
+        _walk_global_writes(child, writes, read_writes)
+    return writes, read_writes
+
+
+def _walk_global_writes(
+    scope: symtable.SymbolTable,
+    writes: set[str],
+    read_writes: set[str],
+) -> None:
+    for sym in scope.get_symbols():
+        if sym.is_assigned() and sym.is_declared_global():
+            writes.add(sym.get_name())
+            if sym.is_referenced():
+                read_writes.add(sym.get_name())
+    for inner in scope.get_children():
+        _walk_global_writes(inner, writes, read_writes)
+
+
+def analyze_cell(source: str) -> CellAnalysis:
+    """Analyze a cell's source and extract its defines and references."""
+    if not source or not source.strip():
+        return CellAnalysis(defines=[], references=[])
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        return CellAnalysis(
+            defines=[],
+            references=[],
+            error=f"Syntax error: {e.msg}",
+        )
+
+    # The visitor stops at function/class bodies; symtable covers those.
+    analyzer = VariableAnalyzer()
+    analyzer.visit(tree)
+
+    nested_refs = _collect_body_refs(source)
+
+    # ``global`` writes inside functions are module defines too.
+    # ``global_read_writes`` are also read there, so they stay in references.
+    global_writes, global_read_writes = _collect_global_writes(source)
+
+    builtin_names = set(dir(builtins)) | {"__name__", "__file__", "__doc__", "__package__"}
+    defines = [v for v in (analyzer.defines | global_writes) if not v.startswith("_")]
+    # A pure assignment in the same cell supersedes a mutation-define.
+    effective_mutation_defines = {
+        v
+        for v in (analyzer.mutation_defines | global_read_writes)
+        if not v.startswith("_") and v in set(defines) and v not in analyzer.pure_defines
+    }
+    # Pure defines are filtered from references (intra-cell rebinds);
+    # mutation-defines and reads before the cell's own binding are kept.
+    pure_defined_names = set(defines) - effective_mutation_defines - analyzer.read_before_define
+    combined_refs = set(analyzer.references) | nested_refs
+    references = [
+        v
+        for v in combined_refs
+        if not v.startswith("_") and v not in builtin_names and v not in pure_defined_names
+    ]
+    builtin_references = [
+        v
+        for v in combined_refs
+        if not v.startswith("_") and v in builtin_names and v not in pure_defined_names
+    ]
+
+    defines = sorted(set(defines))
+    references = sorted(set(references))
+    mutation_defines = sorted(effective_mutation_defines)
+
+    return CellAnalysis(
+        defines=defines,
+        references=references,
+        mutation_defines=mutation_defines,
+        builtin_references=sorted(set(builtin_references)),
+        error=None,
+    )
+
+
+def normalize(source: str) -> str:
+    """Canonical text for *source*: its AST round trip, so comments and layout drop out.
+
+    Source that does not parse falls back to the line strip, which keeps comments.
+    """
+    try:
+        return ast.unparse(ast.parse(source))
+    except SyntaxError:
+        lines = [line.rstrip() for line in source.splitlines()]
+        return "\n".join(lines).strip()
+
+
+class PythonAnalyzer:
+    """The Python language analyzer: ``analyze_cell`` over the cell body."""
+
+    owns_key = True
+
+    def analyze(self, cell: Cell) -> Analyzed:
+        result = analyze_cell(cell.source)
+        return Analyzed(
+            defines=list(result.defines),
+            references=list(result.references),
+            builtin_references=list(result.builtin_references),
+            mutation_defines=list(result.mutation_defines),
+            error=result.error,
+        )
+
+    def normalize(self, body: str) -> str:
+        return normalize(body)