Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: module autoreloading #3420

Merged
merged 2 commits into from
Jan 14, 2025
+57 −21
Merged

docs: module autoreloading #3420

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1456b36
docs: module autoreloading
akshayka Jan 14, 2025
5b4f4b8
link to autoreloader in jupyter doc
akshayka Jan 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 19 additions & 18 deletions docs/guides/coming_from/jupyter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,24 +164,25 @@ subprocess.run(["ls", "-l"])

### Common magic commands replacements

| Magic Command | Replacement |
|--------------|-------------|
| %cd | `os.chdir()`, see also [`mo.notebook_dir()`][marimo.notebook_dir] |
| %clear | Right-click or toggle the cell actions |
| %debug | Python's built-in debugger: `breakpoint()` |
| %env | `os.environ` |
| %load | N/A - use Python imports |
| %load_ext | N/A |
| %matplotlib | marimo auto-displays plots |
| %pwd | `os.getcwd()` |
| %who_ls | `dir()`, `globals()`, [`mo.refs()`][marimo.refs], [`mo.defs()`][marimo.defs] |
| %system | `subprocess.run()` |
| %%time | `time.perf_counter()` or Python's timeit module |
| %%timeit | Python's timeit module |
| %%writefile | `with open("file.txt", "w") as f: f.write()` |
| %%capture | [`mo.capture_stdout()`][marimo.capture_stdout], [`mo.capture_stderr()`][marimo.capture_stderr] |
| %%html | [`mo.Html()`][marimo.Html] or [`mo.md()`][marimo.md] |
| %%latex | [`mo.md(r'$$...$$')`][marimo.md] |
| Magic Command | Replacement |
| ------------- | ---------------------------------------------------------------------------------------------- |
| %cd | `os.chdir()`, see also [`mo.notebook_dir()`][marimo.notebook_dir] |
| %clear | Right-click or toggle the cell actions |
| %debug | Python's built-in debugger: `breakpoint()` |
| %env | `os.environ` |
| %load | N/A - use Python imports |
| %load_ext | N/A |
| %autoreload | marimo's [module autoreloader](../../editor_features/module_autoreloading/) |
| %matplotlib | marimo auto-displays plots |
| %pwd | `os.getcwd()` |
| %who_ls | `dir()`, `globals()`, [`mo.refs()`][marimo.refs], [`mo.defs()`][marimo.defs] |
| %system | `subprocess.run()` |
| %%time | `time.perf_counter()` or Python's timeit module |
| %%timeit | Python's timeit module |
| %%writefile | `with open("file.txt", "w") as f: f.write()` |
| %%capture | [`mo.capture_stdout()`][marimo.capture_stdout], [`mo.capture_stderr()`][marimo.capture_stderr] |
| %%html | [`mo.Html()`][marimo.Html] or [`mo.md()`][marimo.md] |
| %%latex | [`mo.md(r'$$...$$')`][marimo.md] |

### Installing packages with marimo's package manager

Expand Down
34 changes: 34 additions & 0 deletions docs/guides/editor_features/module_autoreloading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Module autoreloading

marimo has an advanced module autoreloader built-in, which you can
enable in the [notebook settings](../../configuration/runtime_configuration/).
When you make edits to Python modules that your notebook has imported, the
module autoreloader will automatically mark cells that use them as stale and,
optionally, automatically run them.

!!! question "Why autoreload?"

Autoreloading enables a workflow that many developers find
productive: develop complex logic in Python modules, and use the marimo
notebook as a DAG or main script that orchestrates your logic.

Based on static analysis, the reloader only runs cells affected by your edits.
The reloader is recursive, meaning that marimo tracks modifications for modules
imported by your notebook's imported modules too. These two featuers make
marimo's module autoreloader far more advanced than IPython's.

Autoreloading comes in two types:

1. **autorun**: automatically re-runs cells affected by module modification.

<figure>
<video controls loop width="100%" height="100%" align="center" src="/_static/docs-module-reloading.mp4"> </video>
<figcaption align="center">When set to autorun, marimo's reloader automatically run cells when you edit Python files.</figcaption>
</figure>

2. **lazy**: marks cells affected by module modifications as stale, letting you know which cells need to be re-run.

<figure>
<video controls loop width="100%" height="100%" align="center" src="/_static/docs-module-reloading-lazy.mp4"> </video>
<figcaption align="center">When set to lazy, marimo's reloader marks cells as stale when you edit Python files.</figcaption>
</figure>
2 changes: 1 addition & 1 deletion docs/guides/editor_features/package_management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,4 @@ they use. This makes it possible to share standalone notebooks without shipping
`requirements.txt` files alongside them, and guarantees your notebooks will
work weeks, months, even years into the future.

To learn more, see the [Package Reproducibility Guide](../package_reproducibility.md)
To learn more, see the [Package Reproducibility Guide](../package_reproducibility.md).
5 changes: 3 additions & 2 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,9 +90,10 @@ nav:
- Editor features:
- Editor features: guides/editor_features/index.md
- Editor overview: guides/editor_features/overview.md
- AI Completion: guides/editor_features/ai_completion.md
- AI completion: guides/editor_features/ai_completion.md
- Package management: guides/editor_features/package_management.md
- Module autoreloading: guides/editor_features/module_autoreloading.md
- Hotkeys: guides/editor_features/hotkeys.md
- Package Management: guides/editor_features/package_management.md
- Run notebooks as apps: guides/apps.md
- Run notebooks as scripts: guides/scripts.md
- Test notebooks:
Expand Down
Loading