fix: handle private imports

[dmadisetti]

📝 Summary

Replaces #9308 and closes #9151

A scoping change introduced in #8762 changed _ prefixed imports by turning then into privates.
While this is consistent with the remainder of marimo's private pattern, it is technically a breaking change as of 0.22.0, and the edge case was not correctly handled. The change lead to a bug where imports referenced in scope were not correctly addressed.

This PR provides an intentional mangling skip for these import cases.

PR #9309 considered the alternative of properly mangling imports, but found that import _private.submodule had no easily resolvable name- and thus could not offer a consistent behavior.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	May 27, 2026 10:50pm

[cubic-dev-ai]

1 issue found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="marimo/_ast/compiler.py">

<violation number="1" location="marimo/_ast/compiler.py:368">
P2: Import exemption too wide. It also exports user aliases like `import x as _y` as public defs. Keep alias-based `_` imports cell-local.

(Based on your team's feedback about preserving backward compatibility for existing public behavior.) [FEEDBACK_USED]</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as User Code
    participant Visitor as ScopedVisitor  
    participant Compiler as compile_cell()
    participant Cache as Serialize/Dequeue (hash.py)
    participant Runtime as Kernel Runtime

    Note over User,Runtime: Private Import Resolution Flow

    User->>Visitor: Parse cell with underscore import (e.g., "import _private.module" or "from foo import _bar")
    Visitor->>Visitor: _get_alias_name() - Skip mangling for all import aliases
    
    alt Import uses "as _name" pattern
        Visitor->>Visitor: Leave asname unmangled (cell-local via is_local check in compile_cell())
    else Standard underscore import
        Visitor->>Visitor: Leave basename unmangled
    end
    
    Note over Visitor: visit_Name() - Handle underscore refs
    alt Load reference to underscore name  
        Visitor->>Visitor: Check if block defines unmangled name
        opt Unmangled name defined (e.g., by import)
            Visitor->>Visitor: Keep node.id as original (no mangling)
        end
        opt Only mangled name defined
            alt Nested scope OR undefined
                Visitor->>Visitor: Apply mangling
            end
        end
    end
    
    Visitor-->>Compiler: defs contains import names (incl. underscore-prefixed)
    
    Compiler->>Compiler: Build nonlocals set
    alt Name starts with _
        alt Import definition present
            Compiler->>Compiler: Include in nonlocals (graph node)
        else No import
            Compiler->>Compiler: Include in temporaries (cell-local)
        end
    end
    
    User->>Cache: Cache/Serialize cell with underscore import reference
    Cache->>Cache: serialize_and_dequeue_content_refs()
    Cache->>Cache: Mangle local_ref for lookup
    
    alt Mangied key not in imports
        Cache->>Cache: Try unmangled key in imports
        alt Unmangled key found (import case)
            Cache->>Cache: Use unmangled key for import resolution
        end
    end
    
    User->>Runtime: Execute cells
    Runtime->>Runtime: test_underscore_prefixed_import_in_cell()
    Note over Runtime: Same cell: underscore import resolves correctly
    
    Runtime->>Runtime: test_underscore_prefixed_import_across_cells()
    Note over Runtime: Cross-cell: underscore import works at runtime via shared globals
    Note over Runtime: NO reactive graph edge created (trade-off)
    
    Runtime->>Runtime: test_lru_cache_underscore_alias()
    Note over Runtime: Cache hits work correctly with unmangled import references
    
    alt Error case
        Runtime->>Runtime: test_underscore_imports_never_mangled()
        Note over Runtime: No "_cell_test_" suffix in unparsed AST
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Import exemption too wide. It also exports user aliases like import x as _y as public defs. Keep alias-based _ imports cell-local.

(Based on your team's feedback about preserving backward compatibility for existing public behavior.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At marimo/_ast/compiler.py, line 368:

<comment>Import exemption too wide. It also exports user aliases like `import x as _y` as public defs. Keep alias-based `_` imports cell-local.

(Based on your team's feedback about preserving backward compatibility for existing public behavior.) </comment>

<file context>
@@ -356,7 +356,18 @@ def compile_cell(
+        if not is_local(name)
+        or (
+            name in v.variable_data
+            and any(d.kind == "import" for d in v.variable_data[name])
+        )
+    }
</file context>