ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

marimo 中文指南:响应式 Python 笔记本的安装、核心特性与快速上手

marimo 中文指南:响应式 Python 笔记本的安装、核心特性与快速上手 marimo 中文指南响应式 Python 笔记本的安装、核心特性与快速上手【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimomarimo 是一款响应式 Python 笔记本运行一个单元格它会自动运行所有依赖该单元格变量的下游单元格从而保证代码、输出与程序状态始终一致同时笔记本以纯 Python.py文件存储原生支持 Git 版本控制既可当作脚本在命令行执行也可部署为交互式 Web 应用。本文以 README_Chinese.md 为核心脉络结合仓库源码如 marimo/_cli/cli.py、marimo/_tutorials/init.py展开帮助读者理解 marimo 的设计理念、核心机制并掌握从安装、创建、运行到转换 Jupyter 笔记本的完整上手流程。marimo 是什么把笔记本重新定义为 Python 程序marimo 是一个响应式的 Python 笔记本环境其核心承诺是你的代码、输出和程序状态永远保持一致。这与传统笔记本如 Jupyter中手动重跑单元格、隐藏状态残留的典型问题形成鲜明对比——marimo 通过静态分析代码依赖关系消除了这些容易出错的环节。marimo 笔记本以纯 Python 格式存储不是容易出错的 JSON因此天然具备以下能力可作为 Python 脚本直接执行并通过命令行参数进行配置可作为 Web 应用部署隐藏并锁定 Python 代码可被 Git 正常追踪与版本化diff 清晰可读可从一个笔记本导入函数和类到另一个笔记本参见 docs/guides/reusing_functions.md。在源码层面marimo 的公开 API 非常丰富见 marimo/init.py包括核心的App、Cell、ui、sql、md、state、status、lazy、persistent_cache等命名空间与函数以及用于部署的create_asgi_app、MarimoIslandGeneratorWASM/Island 模式。为什么选择 marimo功能特性总览原文档以为什么选择 marimo列出了 12 项核心特性这里完整罗列并补充其在仓库中的对应落点特性说明仓库对应资源 功能齐全替代jupyter、streamlit、jupytext、ipywidgets、papermill等工具marimo/_cli/cli.py 提供 edit/run/convert/export 等命令⚡️ 响应式运行一个单元格自动运行所有依赖单元格或将它们标记为过时docs/guides/reactivity.md️ 交互性将滑块、表格、图表等 UI 元素绑定到 Python 代码无需回调函数docs/guides/interactivity.md 支持 Git 版本控制笔记本以.py文件格式存储marimo/_ast/codegen.py代码生成️ 为数据设计用 SQL 查询数据框和数据库过滤和搜索数据框docs/guides/working_with_data/sql.md、docs/guides/working_with_data/dataframes.md 可复现无隐藏状态、确定性执行、内置包管理docs/guides/configuration/runtime_configuration.md 可执行作为 Python 脚本执行通过命令行参数配置docs/guides/scripts.md 可分享部署为交互式 Web 应用或幻灯片通过 WASM 在浏览器中运行docs/guides/apps.md、docs/guides/wasm.md 可复用从一个笔记本导入函数和类到另一个笔记本docs/guides/reusing_functions.md 便于测试可在笔记本上运行 pytestdocs/guides/testing/⌨️ 现代编辑器GitHub Copilot、AI 助手、vim 快捷键、变量浏览器等docs/guides/editor_features/‍ 多编辑器支持VS Code 扩展、PyCharm 插件、neovim 等docs/guides/editor_features/注第 12 项多编辑器支持来自英文版 README.md 的 Highlights中文版 README 同样强调现代编辑器特性两者共同构成 marimo 完整的编辑器生态。响应式编程环境六大核心机制marimo 的独特价值集中体现在其响应式运行时。以下机制均可在 docs/guides/reactivity.md 与相关 API 文档中找到对应说明。独有的响应式设计运行一个单元格marimo 会通过静态分析代码中变量的引用关系自动运行引用其变量的所有单元格彻底避免手动重跑单元格这一容易出错的工作删除一个单元格marimo 会将其变量从程序内存中清除从而消除隐藏状态。这正是 marimo 保证无隐藏状态、确定性执行的根基。兼容计算密集型笔记本延迟模式对于计算密集的笔记本marimo 允许将运行时配置为延迟模式此时受影响的单元格会被**标记为过时stale**而不是自动运行。这样既保留了程序状态一致性的保证又能防止意外执行昂贵的单元格。该配置项可在笔记本的运行时配置界面中调整也可通过用户配置持久化。同步的 UI 元素marimo 的交互性不需要回调函数当你与 滑块、下拉菜单、数据框转换器、聊天界面 等 UI 元素交互时使用这些元素的单元格会自动以最新值重新运行。UI 元素的值直接绑定到 Python 变量代码与界面始终保持同步。交互式数据框marimo 内置交互式数据框查看器支持对数百万行数据分页浏览、搜索、过滤和排序全程无需编写代码。这一功能在 docs/guides/working_with_data/dataframes.md 中有详细介绍底层由 marimo/_data 模块数据源发现、预览、图表等支撑。高效运行时与确定性执行顺序高效运行时marimo 通过静态分析代码只运行真正需要运行的单元格参见 marimo/_ast 中的解析器与编译器实现。确定性执行顺序笔记本按照基于变量引用而非单元格页面位置的确定性顺序执行因此你可以按照想讲述的故事来自由组织笔记本的排版而执行结果不受页面位置影响。动态 Markdown 和 SQL动态 Markdown使用 Markdown 创建依赖 Python 数据的动态文档让文档随数据实时变化。SQL 单元格构建依赖 Python 值的 SQL 查询并针对数据框、数据库、CSV、Google Sheets 或其他数据源执行marimo 内置的 SQL 引擎会把查询结果作为 Python 数据框返回。值得强调的是即使使用了 Markdown 或 SQL你的笔记本仍然是纯 Python 代码——SQL 单元格会被编译为等效的 Python 调用底层由 marimo/_sql 模块与 marimo/_ast/sql_visitor.py 处理从而保持文件格式、Git 版本控制与脚本执行能力的统一。内置包管理marimo 内置支持所有主流包管理器允许你在导入时安装包。更进一步marimo 可以将包依赖序列化到笔记本文件中并在隔离的 venv 沙箱中自动安装它们——这一机制在marimo edit --sandbox/marimo run --sandbox等 CLI 选项中体现详见下文依赖通过 PEP 723 内联元数据跟踪。快速起步从安装到运行安装在终端运行pip install marimo # 或 conda install -c conda-forge marimo marimo tutorial intro要安装包含额外依赖项的版本启用 SQL 单元格、AI 补全等功能运行pip install marimo[recommended]若只需 SQL 功能可单独安装marimo[sql]例如官方 SQL 教程 marimo/_tutorials/sql.py 中即要求pip install marimo[sql]创建新笔记本使用以下命令创建或编辑笔记本marimo edit也可以直接指定文件名marimo edit notebook.py在源码层面edit命令见 marimo/_cli/cli.py 中main.command注册的edit提供了一系列实用选项其中常用参数包括参数默认值说明-p, --port自动选择服务监听端口--host127.0.0.1服务绑定主机--headless关闭不自动启动浏览器--token / --no-token开启是否启用基于会话的 token 认证--no-token关闭--token-password随机生成指定认证 token 值--base-url/服务基础路径需以/开头--watch关闭监听文件变化在其他编辑器中保存后自动重载--sandbox / --no-sandbox视环境而定在隔离环境中运行笔记本依赖通过 PEP 723 内联元数据跟踪并自动安装需要 uv--trusted / --untrusted视环境而定是否在本机直接运行远程笔记本--untrusted时在 Docker 容器中运行--timeout无无连接超过指定分钟数后自动关闭服务器marimo edit还支持 Unix 风格的标准输入管道例如cat notebook.py | marimo edit源码通过_get_stdin_contents实现非阻塞读取。运行应用将笔记本作为 Web 应用运行此时 Python 代码被隐藏且不可编辑marimo run your_notebook.pyrun命令与edit共享大部分服务器参数端口、认证、base-url 等同时把会话模式切换为只读的RUN模式。应用部署的更多细节参见 docs/guides/apps.md含幻灯片布局与 docs/guides/deploying/。作为脚本执行在命令行中将笔记本作为脚本执行python your_notebook.pymarimo 笔记本是合法的 Python 文件可直接运行并可通过mo.cli_args读取命令行参数参见 marimo/init.py 中的cli_args导出以及 docs/guides/scripts.md 和示例 examples/running_as_a_script/。自动转换已有的 Jupyter 笔记本通过命令行将 Jupyter 笔记本自动转换为 marimo 格式marimo convert your_notebook.ipynb your_notebook.pyconvert命令实现见 marimo/_cli/convert/commands.py支持的输入格式不止.ipynb.ipynb本地或 GitHub 托管转换时剥离输出.md/.qmd仅转换{python}围栏代码块.py若已是合法的 marimo 笔记本则不转换否则按 py:percent 格式尝试转换保留顶层注释与文档字符串此路径依赖jupytext。常用选项-o, --output可直接指定输出文件例如marimo convert your_nb.ipynb -o your_nb.py marimo convert your_nb.md -o your_nb.py marimo convert script.py -o your_nb.py转换完成后即可marimo edit your_nb.py继续编辑。文档同时提醒由于 marimo 的响应式执行与传统笔记本不同跨单元格修改变量例如在多个单元格中逐步修改同一个数据框的代码可能需要重构。教程列出所有可用教程marimo tutorial --help仓库 marimo/_tutorials/init.py 中定义了完整的教程清单按tutorial_order依次为intro、dataflow、ui、markdown、plots、sql、layout、fileformat、external-dependencies、markdown-format、for-jupyter-users。这些教程的源码即仓库 marimo/_tutorials 目录下的intro.py、dataflow.py、sql.py等文件运行marimo tutorial 名称即可在编辑器中打开对应示例。CLI 全局选项所有 marimo 子命令共享一组全局选项见 marimo/_cli/cli.py 中main组-l, --log-level日志级别可选DEBUG/INFO/WARN/ERROR/CRITICAL默认WARN-q, --quiet抑制标准输出-y, --yes自动确认所有提示用于非交互式运行-d, --development-mode开发模式开启调试日志与服务器自动重载。例如转换命令可配合全局参数使用marimo -q -y convert script.py -o your_nb.py常见问题FAQ关于 marimo 与传统笔记本尤其是 Jupyter的差异、响应式执行细节等常见问题请参阅 docs/faq.md。例如marimo 解决了传统笔记本的哪些典型问题隐藏状态、手动重跑、执行顺序混乱等在该 FAQ 中有系统说明。深入体验与更多资源marimo 上手简单同时为高级用户保留了很大的发挥空间。仓库中提供了丰富的可运行示例examples/ui滑块、下拉、表格、表单、聊天等全部 UI 组件的演示examples/sql连接 SQLite、PostgreSQL、MotherDuck、查询数据框、读取 CSV/JSON/Parquet 等 SQL 场景examples/frameworks与 FastAPI、Flask、FastHTML 等框架集成的部署示例examples/running_as_a_script以脚本方式运行并接收命令行参数的示例docs/examples/Markdown、输出、运行单元格等专题示例文档。此外marimo 支持将笔记本部署为可分享的交互式 Web 应用或幻灯片docs/guides/apps.md也支持通过 WASM 在浏览器中运行docs/guides/wasm.md——后者由仓库 pyodide/ 目录与marimo._runtime._wasm相关模块提供支撑见 marimo/init.py 中针对emscripten平台的运行时引导逻辑。参与贡献与社区marimo 欢迎所有形式的贡献详见仓库根目录的 CONTRIBUTING.md。项目同时维护了活跃的社区渠道并已加入 NumFOCUS 生态参见 README.md 中的相关说明是更广泛的 Python 科学计算生态的一员。愿景对 Python 笔记本的重塑marimo 是对 Python 笔记本的重塑把笔记本变成一个可复制、可交互、可共享的 Python 程序而不是容易出错的 JSON 便笺。其设计理念受到 Pluto.jl、ObservableHQ 等响应式数据流项目的启发是向函数式、声明式、响应式编程理念在数据科学工具链中落地的一次实践。在仓库中这一愿景最直观的体现就是文件格式本身你在 examples/ 目录下看到的每个.py文件都是一个完整的 marimo 笔记本——可以用marimo edit打开编辑用marimo run部署为应用用python直接执行也可以放进 Git 仓库中进行版本管理。这正是 marimo一个文件、多种用法的设计哲学。【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表