Duplicate from marimo-team/marimo-app-template

Co-authored-by: Myles Scolnick <[email protected]>

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12
+COPY --from=ghcr.io/astral-sh/uv:0.4.20 /uv /bin/uv
+
+RUN useradd -m -u 1000 user
+ENV PATH="/home/user/.local/bin:$PATH"
+ENV UV_SYSTEM_PYTHON=1
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN uv pip install -r requirements.txt
+
+COPY --chown=user . /app
+USER user
+
+CMD ["marimo", "run", "app.py", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,13 @@
+---
+title: marimo app template
+emoji: 🍃
+colorFrom: indigo
+colorTo: purple
+sdk: docker
+pinned: true
+license: mit
+short_description: Template for deploying a marimo application to HF
+---
+
+Check out marimo at <https://github.com/marimo-team/marimo>
+Check out the configuration reference at <https://huggingface.co/docs/hub/spaces-config-reference>

app.py

@@ -0,0 +1,470 @@
+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()

development.md

@@ -0,0 +1,8 @@
+# Development
+
+## Testing your Dockerfile locally
+
+```bash
+docker build -t marimo-app .
+docker run -it --rm -p 7860:7860 marimo-app
+```

requirements.txt

@@ -0,0 +1,5 @@
+marimo
+# Or a specific version
+# marimo>=0.9.0
+
+# Add other dependencies as needed