| import marimo |
|
|
| __generated_with = "0.9.2" |
| app = marimo.App() |
|
|
|
|
| @app.cell |
| def __(): |
| import marimo as mo |
|
|
| mo.md("# Welcome to marimo! 🌊🍃") |
| return (mo,) |
|
|
|
|
| @app.cell |
| def __(mo): |
| slider = mo.ui.slider(1, 22) |
| return (slider,) |
|
|
|
|
| @app.cell |
| def __(mo, slider): |
| mo.md( |
| f""" |
| marimo is a **reactive** Python notebook. |
| |
| This means that unlike traditional notebooks, marimo notebooks **run |
| automatically** when you modify them or |
| interact with UI elements, like this slider: {slider}. |
| |
| {"##" + "🍃" * slider.value} |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.accordion( |
| { |
| "Tip: disabling automatic execution": mo.md( |
| rf""" |
| marimo lets you disable automatic execution: just go into the |
| notebook settings and set |
| |
| "Runtime > On Cell Change" to "lazy". |
| |
| When the runtime is lazy, after running a cell, marimo marks its |
| descendants as stale instead of automatically running them. The |
| lazy runtime puts you in control over when cells are run, while |
| still giving guarantees about the notebook state. |
| """ |
| ) |
| } |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| Tip: This is a tutorial notebook. You can create your own notebooks |
| by entering `marimo edit` at the command line. |
| """ |
| ).callout() |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| ## 1. Reactive execution |
| |
| A marimo notebook is made up of small blocks of Python code called |
| cells. |
| |
| marimo reads your cells and models the dependencies among them: whenever |
| a cell that defines a global variable is run, marimo |
| **automatically runs** all cells that reference that variable. |
| |
| Reactivity keeps your program state and outputs in sync with your code, |
| making for a dynamic programming environment that prevents bugs before they |
| happen. |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(changed, mo): |
| ( |
| mo.md( |
| f""" |
| **✨ Nice!** The value of `changed` is now {changed}. |
| |
| When you updated the value of the variable `changed`, marimo |
| **reacted** by running this cell automatically, because this cell |
| references the global variable `changed`. |
| |
| Reactivity ensures that your notebook state is always |
| consistent, which is crucial for doing good science; it's also what |
| enables marimo notebooks to double as tools and apps. |
| """ |
| ) |
| if changed |
| else mo.md( |
| """ |
| **🌊 See it in action.** In the next cell, change the value of the |
| variable `changed` to `True`, then click the run button. |
| """ |
| ) |
| ) |
| return |
|
|
|
|
| @app.cell |
| def __(): |
| changed = False |
| return (changed,) |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.accordion( |
| { |
| "Tip: execution order": ( |
| """ |
| The order of cells on the page has no bearing on |
| the order in which cells are executed: marimo knows that a cell |
| reading a variable must run after the cell that defines it. This |
| frees you to organize your code in the way that makes the most |
| sense for you. |
| """ |
| ) |
| } |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| **Global names must be unique.** To enable reactivity, marimo imposes a |
| constraint on how names appear in cells: no two cells may define the same |
| variable. |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.accordion( |
| { |
| "Tip: encapsulation": ( |
| """ |
| By encapsulating logic in functions, classes, or Python modules, |
| you can minimize the number of global variables in your notebook. |
| """ |
| ) |
| } |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.accordion( |
| { |
| "Tip: private variables": ( |
| """ |
| Variables prefixed with an underscore are "private" to a cell, so |
| they can be defined by multiple cells. |
| """ |
| ) |
| } |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| ## 2. UI elements |
| |
| Cells can output interactive UI elements. Interacting with a UI |
| element **automatically triggers notebook execution**: when |
| you interact with a UI element, its value is sent back to Python, and |
| every cell that references that element is re-run. |
| |
| marimo provides a library of UI elements to choose from under |
| `marimo.ui`. |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell |
| def __(mo): |
| mo.md("""**🌊 Some UI elements.** Try interacting with the below elements.""") |
| return |
|
|
|
|
| @app.cell |
| def __(mo): |
| icon = mo.ui.dropdown(["🍃", "🌊", "✨"], value="🍃") |
| return (icon,) |
|
|
|
|
| @app.cell |
| def __(icon, mo): |
| repetitions = mo.ui.slider(1, 16, label=f"number of {icon.value}: ") |
| return (repetitions,) |
|
|
|
|
| @app.cell |
| def __(icon, repetitions): |
| icon, repetitions |
| return |
|
|
|
|
| @app.cell |
| def __(icon, mo, repetitions): |
| mo.md("# " + icon.value * repetitions.value) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| ## 3. marimo is just Python |
| |
| marimo cells parse Python (and only Python), and marimo notebooks are |
| stored as pure Python files — outputs are _not_ included. There's no |
| magical syntax. |
| |
| The Python files generated by marimo are: |
| |
| - easily versioned with git, yielding minimal diffs |
| - legible for both humans and machines |
| - formattable using your tool of choice, |
| - usable as Python scripts, with UI elements taking their default |
| values, and |
| - importable by other modules (more on that in the future). |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| ## 4. Running notebooks as apps |
| |
| marimo notebooks can double as apps. Click the app window icon in the |
| bottom-right to see this notebook in "app view." |
| |
| Serve a notebook as an app with `marimo run` at the command-line. |
| Of course, you can use marimo just to level-up your |
| notebooking, without ever making apps. |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| ## 5. The `marimo` command-line tool |
| |
| **Creating and editing notebooks.** Use |
| |
| ``` |
| marimo edit |
| ``` |
| |
| in a terminal to start the marimo notebook server. From here |
| you can create a new notebook or edit existing ones. |
| |
| |
| **Running as apps.** Use |
| |
| ``` |
| marimo run notebook.py |
| ``` |
| |
| to start a webserver that serves your notebook as an app in read-only mode, |
| with code cells hidden. |
| |
| **Convert a Jupyter notebook.** Convert a Jupyter notebook to a marimo |
| notebook using `marimo convert`: |
| |
| ``` |
| marimo convert your_notebook.ipynb > your_app.py |
| ``` |
| |
| **Tutorials.** marimo comes packaged with tutorials: |
| |
| - `dataflow`: more on marimo's automatic execution |
| - `ui`: how to use UI elements |
| - `markdown`: how to write markdown, with interpolated values and |
| LaTeX |
| - `plots`: how plotting works in marimo |
| - `sql`: how to use SQL |
| - `layout`: layout elements in marimo |
| - `fileformat`: how marimo's file format works |
| - `markdown-format`: for using `.md` files in marimo |
| - `for-jupyter-users`: if you are coming from Jupyter |
| |
| Start a tutorial with `marimo tutorial`; for example, |
| |
| ``` |
| marimo tutorial dataflow |
| ``` |
| |
| In addition to tutorials, we have examples in our |
| [our GitHub repo](https://www.github.com/marimo-team/marimo/tree/main/examples). |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| ## 6. The marimo editor |
| |
| Here are some tips to help you get started with the marimo editor. |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell |
| def __(mo, tips): |
| mo.accordion(tips) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md("""## Finally, a fun fact""") |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(mo): |
| mo.md( |
| """ |
| The name "marimo" is a reference to a type of algae that, under |
| the right conditions, clumps together to form a small sphere |
| called a "marimo moss ball". Made of just strands of algae, these |
| beloved assemblages are greater than the sum of their parts. |
| """ |
| ) |
| return |
|
|
|
|
| @app.cell(hide_code=True) |
| def __(): |
| tips = { |
| "Saving": ( |
| """ |
| **Saving** |
| |
| - _Name_ your app using the box at the top of the screen, or |
| with `Ctrl/Cmd+s`. You can also create a named app at the |
| command line, e.g., `marimo edit app_name.py`. |
| |
| - _Save_ by clicking the save icon on the bottom right, or by |
| inputting `Ctrl/Cmd+s`. By default marimo is configured |
| to autosave. |
| """ |
| ), |
| "Running": ( |
| """ |
| 1. _Run a cell_ by clicking the play ( ▷ ) button on the top |
| right of a cell, or by inputting `Ctrl/Cmd+Enter`. |
| |
| 2. _Run a stale cell_ by clicking the yellow run button on the |
| right of the cell, or by inputting `Ctrl/Cmd+Enter`. A cell is |
| stale when its code has been modified but not run. |
| |
| 3. _Run all stale cells_ by clicking the play ( ▷ ) button on |
| the bottom right of the screen, or input `Ctrl/Cmd+Shift+r`. |
| """ |
| ), |
| "Console Output": ( |
| """ |
| Console output (e.g., `print()` statements) is shown below a |
| cell. |
| """ |
| ), |
| "Creating, Moving, and Deleting Cells": ( |
| """ |
| 1. _Create_ a new cell above or below a given one by clicking |
| the plus button to the left of the cell, which appears on |
| mouse hover. |
| |
| 2. _Move_ a cell up or down by dragging on the handle to the |
| right of the cell, which appears on mouse hover. |
| |
| 3. _Delete_ a cell by clicking the trash bin icon. Bring it |
| back by clicking the undo button on the bottom right of the |
| screen, or with `Ctrl/Cmd+Shift+z`. |
| """ |
| ), |
| "Disabling Automatic Execution": ( |
| """ |
| Via the notebook settings (gear icon) or footer panel, you |
| can disable automatic execution. This is helpful when |
| working with expensive notebooks or notebooks that have |
| side-effects like database transactions. |
| """ |
| ), |
| "Disabling Cells": ( |
| """ |
| You can disable a cell via the cell context menu. |
| marimo will never run a disabled cell or any cells that depend on it. |
| This can help prevent accidental execution of expensive computations |
| when editing a notebook. |
| """ |
| ), |
| "Code Folding": ( |
| """ |
| You can collapse or fold the code in a cell by clicking the arrow |
| icons in the line number column to the left, or by using keyboard |
| shortcuts. |
| |
| Use the command palette (`Ctrl/Cmd+k`) or a keyboard shortcut to |
| quickly fold or unfold all cells. |
| """ |
| ), |
| "Code Formatting": ( |
| """ |
| If you have [ruff](https://github.com/astral-sh/ruff) installed, |
| you can format a cell with the keyboard shortcut `Ctrl/Cmd+b`. |
| """ |
| ), |
| "Command Palette": ( |
| """ |
| Use `Ctrl/Cmd+k` to open the command palette. |
| """ |
| ), |
| "Keyboard Shortcuts": ( |
| """ |
| Open the notebook menu (top-right) or input `Ctrl/Cmd+Shift+h` to |
| view a list of all keyboard shortcuts. |
| """ |
| ), |
| "Configuration": ( |
| """ |
| Configure the editor by clicking the gears icon near the top-right |
| of the screen. |
| """ |
| ), |
| } |
| return (tips,) |
|
|
|
|
| if __name__ == "__main__": |
| app.run() |
|
|
