Scope for-loop iterator variables to their loop context

[richbai90]

Suggestion: Scope for-loop iterator variables to their loop context

Problem

for item in collection:
    # do stuff

This pattern is one of the most common constructs in Python programming. Typically, the item variable is intended to be temporary and only meaningful within the loop's context. However, in Python, this variable persists in the namespace after the loop completes.

In marimo, this behavior creates unexpected issues when the same iterator variable name is reused across different cells:

Proposed Solution

I suggest that marimo treats for-loop iterator variables as scoped to their loop context by default. This would better align with the programmer's intent, where these variables are typically meant to be temporary.

Current Workarounds

Currently, users must:

• Use private variable naming conventions like _item to indicate temporary status
• Be careful to use unique iterator variable names across all cells
• Explicitly delete variables after use

Benefits

• Reduces unexpected variable collisions between cells
• Better matches programmer intent for iterator variables
• Maintains compatibility with standard Python while improving the notebook experience

Implementation Considerations

This could be implemented as:

• A default behavior with an option to disable
• An opt-in feature via configuration

Would love to hear your thoughts on this suggestion!

[dmadisetti]

Maintains compatibility with standard Python while improving the notebook experience

This is not true, keeping the last variable in scope is standard python. Maybe keeping it in scope within just the cell makes sense- but maybe frustrating if you did want the correct behavior.

But this is a common complaint.

what about implicitly private variables being declared:

# suggested as import because it's easiest to hook into the ast
from marimo.private import i, j, k, dynamic_name
# reuse i as much as you want across cells

---

Another suggestion (harder to implement, and less elegant)

from marimo import range, enumerate, zip

Where the imported behavior is what you proposed? (Users could also do mo.range as well)

---

Here are some other suggestions that have been mentioned before:

• just make the auto-fix buttons better (auto rename to _i)
• treat single character variables in a special way. But this once again has issues if it's not what you expect.

[dmadisetti]

marimo.locals might make more sense

[richbai90]

I'm not sure if I like the dynamic imports. What about something like this?

import marimo as mo
let i, j, k = mo.locals()
# use i, j, k wherever you like 

The AST can infer how many variables that mo.locals() should return.

[richbai90]

Taking inspiration from Rust, I appreciate how it elegantly supports arbitrary scoping with curly braces:

fn foo() {
    let x: i32 = 0;
    {
        let x: i32 = 1;
        println!("{}", x); // prints 1
    }
    println!("{}", x); // prints 0
}

We could implement something similar in Marimo using Python's context management syntax. Here are three possible approaches:

Option 1: Explicit Context Manager

with marimo_local_scope:
    # do local work here

Option 2: Minimalist Approach

with _:
    # do local stuff

Option 3: Flexible Intent Expression

with anything as _:
    # do local stuff

I believe Option 3 is the strongest choice for several reasons:

• Doesn't introduce new keywords or pollute the global namespace
• Gives authors complete control to express intent in their preferred way
• Uses _ which aligns with Python's established convention for private variables (and Marimo's conventions)

For language consistency, scoped variables should remain accessible outside the with block but within the same cell. This preserves Python's function scoping behavior, and since each Marimo cell is essentially a function, this approach would allow underlying Python semantics to remain in tact.

Considerations

When exporting notebooks as Python files, Marimo would need to define the context manager(s) used for this scoping mechanism. This would ensure the exported code runs correctly in a standard Python interpreter without raising NameError exceptions for undefined context managers.

[dmadisetti]

Yay for convergent design. I think I suggested something similar in #1477
but I think the with block is still a little cumbersome, also that one can shadow a global definition is less than desirable.

Option 3 would be pretty hard to implement in pure python. As I see it, you'd have to inject a context manager with the correct name. It also doesn't fall under the convention of definition, so still breaks python expectation.

I personally like option 2 here, but option 1 is the only one that captures the explicit requirement.

---

Here's the scoreboard so far:

i, j, k = mo.locals()

• ✅ pure python
• 1/2 statically detectable (possible, use heuristic, needs runtime magic)
• ✅ obvious, explicit

from marimo.local_scope import i, j, k

• ✅ pure python
• ✅ statically detectable
• ✅ obvious, explicit

with mo.local_scope:
    ...

• ✅ pure python
• ✅ statically detectable (still need the heuristic to trigger on the block, but everything else is fine)
• 1/2 Explicit, allows shadowing in global scope which may not be obvious

---

Would like to hear more on why import doesn't sit well with you. Conscious of my own biases, and always happy to be wrong.

I think the assignment option does work too- just more of a pain implementation wise, with some brittle points of failure. I don't think implementation difficulty means it should be excluded- just that it should be worth the extra effort

[dmadisetti]

Also the with option is not exclusive with the other 2. But assignment and import should probably be exclusive

[richbai90]

While the proposed solution of from mo.locals import i, j, foo, bar could work for iterator variables, I have significant concerns with this approach:

Issues with Import Syntax

1. Unexpected Mental Model

from mo.locals import i, j, foo, bar, whatever
for i in range(10):
    # ...

This syntax is fundamentally confusing. If I encountered this code without prior knowledge, I'd be perplexed about why values are being imported and then immediately reassigned. It creates a mental disconnect between the expected behavior of imports (bringing in existing functionality) and what's actually happening (declaring local variables).

2. Disrupts Programming Flow

Having to declare variables ahead of time breaks the natural flow of programming:

• I'd need to anticipate all local variables before writing my code
• If I realize mid-development that I need another local variable, I'd have to interrupt my flow to go modify the import statement
• It adds cognitive overhead to the development process

Proposed Alternative: Context Manager Approach

Instead, I find the context manager approach to be much more intuitive:

# In the initial setup cell
from marimo import local_scope

# Later, in any cell where local scope is needed
with local_scope:
    # Everything declared here is local to this scope
    for i in range(10):
        # i is local
    # Other local variables as needed

Benefits of the Context Manager Approach:

1. Clarity: The scope boundaries are visually clear
2. Flexibility: No need to predeclare variable names
3. Intuitive: Follows Python's established pattern for managing context
4. Scalable: Works for any scenario requiring local scope, not just loops

Summary

While the import syntax might solve the specific issue of iterator variables in loops, the context manager approach provides a more comprehensive, intuitive, and flexible solution for managing scope in Marimo notebooks. It allows for a more natural programming experience without forcing users to predefine their variable names or interrupt their workflow.

[dmadisetti]

I agree that redefining variables is counter intuitive- I also agree local_scope makes sense. However, it still provides some overhead, and doesn't offer much more than what is already done with the wrap in a function button:

I'm not sure the added complexity is worth it for a marginal solution

---

A declarative approach could be:

# Only allowed in the setup cell
marimo.declare_local("i", "j", "k", "ax", "fig") # mo.declare_local("i,j,k,ax,fig")

or even on the app level:

App(locals=["i", "j", "k", "ax", "fig"])

I'm partial to the first case, because it is declared in code (So immediately obvious to the user, where as App parameters are usually a bit more hidden in the editor interface). Both cases can actually can be implemented without any additional static analysis.

• ✅ pure python
• ✅ statically detectable by heuristic (but not needed for implementation)
• ✅ obvious, explicit

A downside is that the local declarations could be obscured, in a way that's not possible in the other options:

my_locals = ["i", "j", "k", "ax", "fig"]
if condition:
    my_locals.pop(1)
marimo.declare_local(my_locals)

But we could do a bit of analysis to throw an error

---

Regarding the concerns:

I'd need to anticipate all local variables before writing my code

If I realize mid-development that I need another local variable, I'd have to interrupt my flow to go modify the import statement

I think a quick fix-button (like above) can address this pretty easily. I think it can also be implemented in a way that doesn't require a full notebook rerun (like we do with import cells). A benefit of the import approach is that this is done for free.

It adds cognitive overhead to the development process

Agreed in that I think the feature could be abused in such a way that a notebook becomes confusing.
However, there's the proposal for marimo lint, that would provide best practices suggestions specific to marimo: #1543
I think that these are reasonable lint rules:

• limit variables to 3 characters: motivation; prefer the _ prefix, and restrict local variables to common shorthand temp variables used in typical python (fig, ax, i, j, x, y, etc..)
• more than 1 reference: motivation; if you only use the variable once (or not at all), then it should not be declared local.

But aside from that, I think it's set it and leave it. I would argue it's more cognitive load to remember what the variable i contains, or ax if you are using declare_local reasonably.

[PetterS]

I still think that just allowing variables that are first written to (not read) in all cells where they appear would be nice and safe. #1477

[akshayka]

I think that solution works well for cases when you don't want to read the variable, such as loop variables. But it's trickier if you do intend to read one of the multiply-defined variables later on?

If you have two cells:

df = ...

df = some_expensive_calculation()

But then later decide you want to use the second df in a third cell — you can't, without changing the name of df in the first cell, which then may in turn render several other cells stale. That seems not nice? That was one of my primary concerns. But am I overthinking it? I am open to feedback. I'd certainly love to find a way to make this more convenient.

[richbai90]

Honestly, I'd take this a step further. Maintain some type of dependency graph and each time a variable is defined/redefined is a root node. This solves the problem you posed because cell 2 would be dependent on cell 1 but cell 3 would be a root node.

Here's an example:

Cell 1: df write before read
Cell 2: df write before read
Cell 3: df read before write, new_df write before read
Cell 4: df read before write
Cell 5: df write before read
Cell 6: df read before write
Cell 7: new_df read before write
Cell 8: new_df write before read

The resulting dependency graph would look something like this

flowchart TD
    A[c1: df = ...] 
    B["c2: df = expensive_calc()"]
    C[c3: new_df = df + ...]
    D["c4: df[col_1] = ..."]
    E[c5: df = ...]
    F["c6: df[col_2] = ..."]
    G[c7: new_df += ...]
    H[c8: new_df = ...]
    B--->D
    B--->C
    E--->F
    C--->G

Loading

I'm not sure how this would work in the context of the Marimo internals and it may be too lenient for some. In this case I think it's a question of which behavior is more burdensome, the current behavior or the potential pit-fall. Given that the noted pit-fall is more of an edge case, I think the proposal in #1477 make a lot of sense.

[dmadisetti]

Just because we'd track state doesn't mean it doesn't make it less confusing, or create the same issues we've been trying to solve (you might just be more aware with the right UX, but it's still not good practice). There's also the issue of associating the correct df with the right graph, when you can just do this with a new name.

Mutation operations are also basically impossible to trace since there's FFI, local packages, and a million other things to potentially support.

---

A bit opinionated but: the policy of no repeated variables is the best and correct one

However, I do think it's worth exploring how to loosen the policy a little since temp variables like df, ax and fig are so idiomatic to python.

So, not trying to solve the reassignment issue, just the "I don't want to prefix everything with _" issue

[richbai90]

If tackling the reassignment issue is a non start, I'm not sure there's a more intuitive way than the undscore prefix. Maybe it's just something developers will have to adapt to in order to get the niceness that marimo provides.

[PetterS]

I think that solution works well for cases when you don't want to read the variable,

Yes, that is the only case it should solve.