MEP-XXXX notebook naming convention

[manzt]

Introduces _mo.py as an optional naming convention for marimo notebooks to enable tooling while preserving Python compatibility and general "just Python" vibe.

Thanks for kickstarting the conversation @willingc, @lucharo

[akshayka]

Thanks for writing this up! I see some of the benefits. In my gut reaction, I have an aesthetic objection, as the special suffix (my_notebook_mo.py) dilutes the message that marimo notebooks are just Python programs.

[koaning]

I don’t mind the idea, but the benefits aren’t 100% clear. What other tools could make the marimo experience better with such a convention?

Also, you mention pytest but I might call that an expectation of the tool more than a convention. You aren't free to pick the prefix of the testfile IIRC.

[manzt]

I have an aesthetic objection, as the special suffix (my_notebook_mo.py) dilutes the message that marimo notebooks are just Python programs.

I agree re: aesthetics it is unfortunate. That said, while marimo notebooks are technically Python programs, there's enough practical distinction that some acknowledgment through guidelines/conventions might be worth considering - it is tedious/error prone to author a new marimo notebook outside of marimo app (maybe lsp helps here); you often want different or to ignore linting rules for your marimo notebooks compared to other .py files (line width, nested imports).

Another option would be to wait and see what conventions emerge naturally (like putting notebooks in a ./notebooks folder) before formalizing anything, and with that this PR can just sit here for feedback.

I don't mind the idea, but the benefits aren't 100% clear.

The main benefits relate to compatibility with tools outside the marimo editor. For example, you might want different linting rules for notebooks or to ignore them from certain rules (easy to glob with *_mo.py). Our VS Code extension could prioritize opening _mo.py files a notebook view instead of text editor. Without parsing file contents, these tools need some way to identify which files are marimo notebooks.

[dmadisetti]

Just adding to the conversation.

Internal naive identification is done with:

• __generated_with in .py
• marimo-version in .md

But these aren't required to be "marimo" notebooks. There's be no current typical naming convention but we use notebook.py for molab, and true detection just falls under "can we run it?"

---

I'm not opposed to this idea, but I wonder if it's something where we need to have an opinion. Even without an internal marimo change, I think taking an official stance would require us adhering to a naming convention. It's not clear how much gained vs letting teams chose their own convention; I personally just use a /notebooks directory (which you mentioned, maybe another alternative?)

Even though marimo notebooks are now loaded via static parsing with an expected fileformat, I would argue that's more of a security guard rail added with the introduction of app.setup (which would otherwise allow arbitrary code execution on notebook startup). True python loading is still currently tested, and could just as easily be used if we wanted to make that a flag (which actually may be a useful plugin loading mechanism)

If marimo behavior were to bifurcate from python behavior (say allowing scripts to be run non-linearly), then I would advocate for .mpy or .ppy over _mo.py, since it should be clear that it's not a typical python script, and can't be expected to run correctly outside of the context of marimo.

---

I would like to see the marimo spec formalized a bit more- maybe giving codes to our current file format "violations", (maybe in flake8 or other standard) before considering how other tools will detect marimo.
In ruff, the test_ prefix isn't detected on the file level, but the function level: https://github.com/astral-sh/ruff/blob/f9091ea8bb5aea454c3c6e8291470d453755c85f/crates/ruff_linter/src/rules/flake8_pytest_style/helpers.rs#L66 (the pytest convention says file name is OK, but configurable: https://docs.pytest.org/en/stable/example/pythoncollection.html#changing-naming-conventions)

I think we can to commit to standardization without a required naming convention