marimo 文件浏览器 `mo.ui.file_browser` 完整指南：从本地目录到 S3/GCS 云存储的文件选择组件

marimo 文件浏览器mo.ui.file_browser完整指南从本地目录到 S3/GCS 云存储的文件选择组件【免费下载链接】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本指南围绕 marimo 的mo.ui.file_browser文件浏览组件展开讲解如何在笔记本中嵌入一个浏览器端文件选择器从指定目录挑选本地或云存储S3 / GCS / Azure中的文件与目录并取回其路径供后续单元消费。读完本文你将掌握该组件的全部参数语义、默认值与校验规则理解其路径限定与安全机制并能结合实际场景写出可直接运行的文件选择与读取代码。file_browser运行在服务端它浏览的是运行 notebook 进程的那台机器或容器上的文件系统因此天然适用于“读取服务端数据文件”“批处理数据目录”“对接云存储桶”等场景其 API 文档定义于 marimo/_plugins/ui/_impl/file_browser.py前端渲染实现位于 frontend/src/plugins/impl/FileBrowserPlugin.tsx。快速上手在笔记本中嵌入文件浏览器file_browser的用法与 marimo 其他 UI 元素一致在单元格中创建组件、显示组件、再读取其值。官方 API 文档docs/api/inputs/file_browser.md给出的最小示例是在单元格中用mo.vstack纵向堆叠展示import marimo as mo app.cell def __(): mo.vstack([mo.ui.file_browser()]) return仓库自带的实战示例位于 examples/ui/file_browser.py展示了更完整的用法先创建组件并渲染再在后续单元格中读取file_browser.valueapp.cell def _(mo): file_browser mo.ui.file_browser() file_browser return (file_browser,) app.cell def _(file_browser): file_browser.value return运行后页面会显示一个带目录树浏览能力的文件选择器当用户选中文件时file_browser.value会响应式地更新为选中项序列。若不传任何参数组件默认以进程当前工作目录为起点、默认允许一次选择多个文件multipleTrue。核心参数详解file_browser的构造函数签名见 marimo/_plugins/ui/_impl/file_browser.py提供了 11 个可配置参数下表汇总了参数语义、默认值与约束参数类型默认值说明initial_pathstr \| Path \| CloudPath起始目录必须是已存在的目录否则抛出ValueError。字符串按本地路径解释传入cloudpathlib的S3Path/GCSPath/AzurePath则浏览对应云存储桶。不传时自动推断见下文“路径推断与默认值”。filetypesSequence[str]None每个目录中仅显示这些扩展名的文件例如[.txt, .csv]None表示显示所有文件。匹配大小写不敏感且会自动补全.前缀。selection_modefile \| directory \| all \| Sequencefile允许用户选择的条目类型all等价于[file, directory]列表顺序无关且自动去重。multipleboolTrue是否允许多选为False时默认值列表超过一项会报错。restrict_navigationboolTrue是否禁止用户导航到给定路径的任意上级目录。默认开启marimo run部署应用时若设为False应用查看者可浏览服务进程可读的任何路径安全注意事项见下文。valuestr \| Path \| SequenceNone默认选中的文件或目录路径必须真实存在、必须位于initial_path之内受限模式下、类型必须被selection_mode允许。空字符串非法None表示无默认值。filterstr \| re.Pattern \| Callable[[Path], bool]None额外的文件过滤条件正则字符串或已编译模式对文件名执行search匹配可调用对象接收文件的Path并返回True表示包含。与filetypes是“且”关系。目录不受 filter 影响始终显示以便导航。limitintNone单目录最多显示的条目数None时自动选择云存储S3/GCS/Azure为 50本地文件系统为 10000。labelstr元素的 Markdown 标签。on_changeCallableNone值变化时的回调函数。ignore_empty_dirsboolFalse为True时递归隐藏不含任何文件的目录含嵌套空目录见下文“大目录与性能”。从源码结构看__init__中会先把selection_mode与value分别经过_normalize_selection_mode、_normalize_values校验再把filetypes统一规范为小写且带.前缀的集合最后把initial-path、selection-mode、filetypes、multiple、restrict-navigation作为组件参数传给前端并注册一个名为list_directory的 RPC 函数用于前端拉取目录内容marimo/_plugins/ui/_impl/file_browser.py。读取选中结果value、name()与path()组件的值类型为Sequence[FileBrowserFileInfo]每一项包含四个字段对应源码中的 FileBrowserFileInfo字段含义id条目唯一标识即路径字符串path完整路径保持与initial_path相同的路径类本地Path或云存储CloudPathname文件名或目录名is_directory是否为目录除了直接访问file_browser.value组件还提供了两个便捷方法源码定义fb mo.ui.file_browser(initial_pathPath(data/), multipleTrue) # 取第 0 个选中项的路径对象越界返回 None fb.path(index0) # - Path(data/xxx.csv) 或 S3Path(...) # 取第 0 个选中项的名称越界返回 None fb.name(index0) # - xxx.csvpath()返回的对象类型与传入的路径类型保持一致——传入本地Path返回Path传入S3Path返回S3Path因此可以直接调用云路径对象的read_text()等方法读取文件内容。这一点由_convert_value中通过self._create_path(file[path])重建路径对象保证marimo/_plugins/ui/_impl/file_browser.py。文件类型过滤与正则 / 回调过滤当目录内容较多时可用filetypes和filter双通道过滤二者是“且”关系AND 语义filetypes按扩展名过滤源码会把每个扩展名转小写并自动补.前缀例如传入txt、.py、.CSV都会被规范化为{.txt, .py, .csv}匹配时对文件后缀做小写比较因此document.TXT、script.Py都能命中marimo/_plugins/ui/_impl/file_browser.py。filter支持三种形式正则字符串内部编译为re.Pattern后对file.name执行search即匹配文件名任意位置要匹配完整文件名请用^/$锚定已编译的re.Pattern可调用对象接收Path返回布尔值例如按文件大小过滤lambda p: p.stat().st_size 50。源码中_passes_filter对可调用 filter 做了异常隔离若回调对某个文件抛出OSError例如损坏的符号链接该文件按“不匹配”处理不会拖垮整个目录列表其他异常则正常向上传播marimo/_plugins/ui/_impl/file_browser.py。对应的测试覆盖了正则字符串、编译模式、可调用对象、OSError隔离、目录不被隐藏、与filetypes叠加等场景tests/_plugins/ui/_impl/test_file_browser.py。# 只看 2024/2025 年的 CSV 报告 mo.ui.file_browser( initial_pathPath(reports), filetypes[.csv], filterrreport_\d{4}\.csv, )selection_mode选择文件、目录还是两者selection_mode决定用户可点选的条目类型接受四种写法mo.ui.file_browser(selection_modefile) # 默认只能选文件 mo.ui.file_browser(selection_modedirectory) # 只能选目录 mo.ui.file_browser(selection_modeall) # 文件 目录 mo.ui.file_browser(selection_mode[file, directory]) # 等价于 all_normalize_selection_mode会把输入统一规范为frozenset字符串file/directory转为单元素集合all展开为{file, directory}列表/元组则去重marimo/_plugins/ui/_impl/file_browser.py。非法取值如both、folder、空列表、含非法元素都会抛出ValueError相关校验在TestNormalizeSelectionMode中有完整覆盖tests/_plugins/ui/_impl/test_file_browser.py。“同时选择文件与目录”的一个典型场景是处理以目录形式存储的数据格式如 deltalake官方 docstring 给出了直接可用的写法marimo/_plugins/ui/_impl/file_browser.pyfile_browser mo.ui.file_browser( initial_pathPath(path/to/dir), selection_modeall, )注意两点联动目录始终会显示在列表中方便导航进入但在selection_modefile时目录不可勾选ignore_empty_dirs与selection_modedirectory组合时列表中的结果全部为目录见对应测试 test_ignore_empty_dirs_directory_selection_mode。路径限定与安全机制restrict_navigationfile_browser默认开启导航限定restrict_navigationTrue用户无法向上导航到initial_path的任意上级目录也无法跳转到兄弟目录或任意绝对路径。这是组件在marimo run部署场景下的重要安全边界。底层实现中每次前端发起list_directoryRPC 时后端都会用_is_path_within校验目标路径是否解析后仍位于initial_path之内marimo/_plugins/ui/_impl/file_browser.py。该校验是解析后的包含性检查因此能防住多种绕过手段测试文件对此有专门覆盖tests/_plugins/ui/_impl/test_file_browser.py 与 [L539-L664)通过..路径穿越逃逸restricted/../sibling→ 拒绝指向受限目录外部的符号链接 → 拒绝兄弟目录、任意绝对路径 → 拒绝循环符号链接 → 拒绝且不会挂起指向受限目录内部子目录的符号链接 → 允许位于受限目录内的已删除路径 → 报“目录不存在”而非限制错误区分两类错误语义。需要特别提醒的安全点若在marimo run部署的应用中把restrict_navigation设为False应用查看者将可以浏览服务进程可读的任何路径请只在可信环境中使用。另外由于前端无法处理相对路径initial_path在初始化时会被normalize_path规范化为绝对路径不做符号链接解析后再传给前端测试test_file_browser_relative_path_sent_to_frontend_as_absolute验证了这一点tests/_plugins/ui/_impl/test_file_browser.py。路径推断与默认值校验initial_path的解析顺序体现了“显式优先、推断兜底”的设计显式传入initial_path时直接使用未显式传入但传了value且未受限restrict_navigationFalse时取所有默认值路径的最近公共父目录_common_parent见 marimo/_plugins/ui/_impl/file_browser.py否则回退到进程当前工作目录Path.cwd()。由于默认restrict_navigationTrue会把导航限制在初始目录内当用户未显式声明initial_path而使用默认工作目录时源码会通过_warn_default_root_once发出一次性警告提示传入initial_path来声明可浏览目录marimo/_plugins/ui/_impl/file_browser.py相关警告行为在 test_warns_once_for_default_root 中有验证。value默认值有一套严格的校验违反即抛ValueError空字符串非法Path()会被解析为当前目录从而掩盖真实输入因此源码在路径规范化之前就显式拒绝见_reject_empty_value默认值必须真实存在multipleFalse时默认值列表最多一项默认值类型必须被selection_mode允许如selection_modefile时默认值不能是目录受限模式下默认值必须位于initial_path之内。这些规则在测试 test_file_browser_rejects_missing_default_value、test_file_browser_rejects_default_value_of_wrong_kind、test_restricted_file_browser_rejects_unreachable_default_value 等用例中均有印证。示例# 未传 initial_path 时从 value 推断起始目录为其父目录 fb mo.ui.file_browser( value[Path(data/2024/a.csv), Path(data/2024/b.csv)], restrict_navigationFalse, )大目录场景limit、自然排序与ignore_empty_dirslimit与截断标记本地文件系统默认上限 10000 条云存储默认 50 条保守起见。list_directory响应包含files、total_count目录全部条目数与is_truncated是否因上限被截断三个字段ListDirectoryResponse。当条目数恰好等于limit时不算截断超过时is_truncatedTrue。相关测试见 test_is_truncated_true_when_limit_exceeded 等用例。自然排序目录内条目按natural_sort排序字母数字混合的“人类直觉顺序”且目录永远排在文件之前。测试用例验证了file1 file2 file10 file20 file100以及dir2 dir10 dir100的排序结果tests/_plugins/ui/_impl/test_file_browser.py。ignore_empty_dirs设为True后递归扫描目录最多 100 层防栈溢出隐藏不含任何文件的目录包括深层嵌套的空目录结构。扫描时跳过目录符号链接以防无限循环文件类型过滤递归生效且大小写不敏感遇到权限错误时“假定目录有文件”以避免隐藏潜在可访问的子目录。边界行为恰好 100 层、超过 100 层、混合大小写扩展名、符号链接环均有测试覆盖tests/_plugins/ui/_impl/test_file_browser.py。云存储支持S3 / GCS / Azurecloudpathlibfile_browser的一个突出能力是直接浏览云存储桶只要initial_path传入cloudpathlib的云路径对象S3Path、GCSPath、AzurePath组件就会从对应存储桶加载文件。官方 docstring 给出了三个可直接运行的示例marimo/_plugins/ui/_impl/file_browser.pyfrom cloudpathlib import S3Path # 浏览 S3 桶 file_browser mo.ui.file_browser( initial_pathS3Path(s3://my-bucket/folder/) ) # 取回的是 S3Path可直接读取内容 file_browser.path(index0).read_text()from cloudpathlib import GSClient, GSPath # 使用带凭据的客户端访问 GCS gs_client GSClient(storage_credentials.json, projectmy-project) cloudpath GSPath(gs://my-bucket/folder, clientgs_client) file_browser mo.ui.file_browser(initial_pathcloudpath)实现上组件会从路径来源value第一项或initial_path捕获路径类与客户端对象self._path_cls保存路径类self._path_kwargs保存client之后所有路径操作构造、列目录、值转换都用同一个类与客户端重建路径对象marimo/_plugins/ui/_impl/file_browser.py 与 [L464-L467)。这意味着只要你传入的是Path的子类含自定义客户端file_browser.path()返回的对象就会保留同样的类型与客户端测试 test_file_browser_infers_custom_path_class_and_client 与 test_extended_path_class 对此做了验证。前后端协作机制从 frontend/src/plugins/impl/FileBrowserPlugin.tsx 可以看到前端插件以marimo-file-browser为组件名注册通过Data接口接收initialPath、filetypes、selectionMode、multiple、restrictNavigation、label六个渲染参数并通过list_directoryRPC入参{path: string}出参{files, total_count, is_truncated}按需向服务端拉取目录内容。前端负责目录树的导航交互与勾选状态服务端Python 侧_list_directory见 marimo/_plugins/ui/_impl/file_browser.py负责过滤、排序、截断与导航权限校验两端通过TypedFileBrowserFileInfoid/path/name/is_directory保持一致的数据契约。综合示例将上述要点组合成一个完整可运行的单元格脚本import marimo as mo from pathlib import Path # 1) 多选 CSV 文件只显示 reports 目录下的 CSV csv_browser mo.ui.file_browser( initial_pathPath(reports), filetypes[.csv], selection_modefile, multipleTrue, ) # 2) 目录 文件均可选适合选择 deltalake 这类目录型格式 mixed_browser mo.ui.file_browser( initial_pathPath(warehouse), selection_modeall, # 等价于 [file, directory] ignore_empty_dirsTrue, ) # 渲染组件 mo.vstack([csv_browser, mixed_browser]) # 3) 在后续单元格中消费选择结果 for f in csv_browser.value: print(csv_browser.name(), -, csv_browser.path())参考资料实现源码 marimo/_plugins/ui/_impl/file_browser.py、官方 API 文档 docs/api/inputs/file_browser.md、运行示例 examples/ui/file_browser.py、测试覆盖 tests/_plugins/ui/_impl/test_file_browser.py。【免费下载链接】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），仅供参考