Monty 沙箱中的 pathlib 模块：Path 类的纯路径操作与受控文件 I/O 完整指南

Monty 沙箱中的 pathlib 模块Path 类的纯路径操作与受控文件 I/O 完整指南【免费下载链接】montyA minimal, secure Python interpreter written in Rust for use by AI项目地址: https://gitcode.com/GitHub_Trending/monty3/montypathlib是 Monty用 Rust 编写的最小化、面向 AI 场景的安全 Python 解释器沙箱内文件路径操作的核心模块。本文以仓库内 limitations/pathlib.md 为骨架结合 crates/monty/src/modules/pathlib.rs、crates/monty/src/types/path.rs 与 crates/monty/test_cases/pathlib__pure.py 等源码与测试用例系统讲解 Monty 中pathlib.Path的能力边界、实现原理与 CPython 的差异帮助你写出既能在沙箱内安全运行、又能无缝迁移回 CPython 的路径处理代码。模块概览整个 pathlib 只有一个类Monty 的pathlib模块与 CPython 不同它只导出一个类pathlib.Path。模块创建逻辑位于 crates/monty/src/modules/pathlib.rscreate_module构造一个名为pathlib的模块对象仅设置一个属性Path其值为内置类型Type::Path。也就是说pathlib.PurePath、pathlib.PurePosixPath、pathlib.PureWindowsPath、pathlib.PosixPath、pathlib.WindowsPath均不存在于 Monty 中直接访问会得到AttributeError。import pathlib p pathlib.Path(a.txt) assert p.name a.txt如上代码来自 crates/monty/test_cases/pathlib__import.py它同时验证了两种导入方式均可用import pathlib后通过属性访问以及from pathlib import Path直接导入。虚拟路径永远是 POSIX 形式Monty 沙箱内不存在宿主机的真实文件系统视图所有路径都是“虚拟 POSIX 路径”。一个Path实例内部存储的永远是以正斜杠分隔的字符串如/mnt/data/foo.txt即使宿主机是 WindowsPath(C:/Users/foo)也不会被解释为 Windows 路径而是字面意义上的 POSIX 路径C:/Users/foo。这一点在 docs/limitations/filesystem.md 的 “Virtual paths are always POSIX” 一节有明确说明。对应的底层实现是 crates/monty/src/types/path.rs 中的normalize_path构造路径时反斜杠会被替换为正斜杠path.replace(\\, /)因此即使你传入带反斜杠的字符串也会被归一化。此外该函数还会移除.组件/a/./b→/a/b折叠连续斜杠//a///b→/a/b移除末尾斜杠根路径/除外不解析..组件——因为这需要 I/O 来确认符号链接属于宿主机的职责。类对象与实例共享同一个类型Monty 的Path类对象与其实例共享同一个类型对象因此类对象会以实例名对外应答import pathlib pathlib.Path.__name__ # PosixPath repr(pathlib.Path) # class PosixPath pathlib.Path.nonexistent # AttributeError: type object PosixPath has no attribute nonexistentCPython 中这里报错会称呼Path而 Monty 统一称呼PosixPath这是为了兼容性而刻意为之。repr 输出同样如此实例的repr是PosixPath(/usr/bin)由 crates/monty/src/types/path.rs 中的py_repr_fmt直接格式化为PosixPath({path})形式。不过实例层面的拼写与 CPython 保持一致例如Path(/a) / 1会抛出与 CPython 相同的TypeError: unsupported operand type(s) for /: PosixPath and int见下方“/运算符”一节。构造规则Path(*segments)支持零个或多个段参数每个段可以是str或另一个Path构造时按顺序拼接from pathlib import Path str(Path()) # . str(Path(folder, file.txt)) # folder/file.txt str(Path(/usr, local, bin)) # /usr/local/bin str(Path(start, /absolute, end)) # /absolute/end —— 绝对段会替换前面的内容上述断言均来自 crates/monty/test_cases/pathlib__pure.py与 CPython 行为完全一致。其实现位于 crates/monty/src/types/path.rs 的Path::init无参数时返回Path(.)单参数直接转换多参数时通过fold_joinpath逐个拼接任何绝对路径段都会替换掉之前的所有内容。Bytes 路径被拒绝传入bytes会抛出TypeError。这与 CPython 允许 bytes 路径按os.fsdecode语义解码不同是 Monty 的一个明确差异。从源码看路径字符串提取函数extract_path_stringcrates/monty/src/types/path.rs只接受 intern 字符串、堆上Str或Path三种值其他类型统一报TypeError: expected str or Path, got type。不提供Path.cwd()与Path.home()沙箱没有“当前目录”和“家目录”的概念因此Path.cwd()与Path.home()未实现。如果你在沙箱代码里依赖它们需要改为通过宿主显式挂载的虚拟路径定位文件挂载机制见 docs/limitations/filesystem.md 与下文“路径规范化与沙箱边界”一节。纯路径操作不触发任何 I/O 的方法与属性纯路径方法完全在解释器内部完成不向宿主发起系统调用。已实现的有成员说明name最后一个路径组件路径以分隔符结尾时为空串parent父路径相对无目录路径返回.根路径/返回自身stem去掉最后一个后缀的文件名隐藏文件如.bashrc原样返回suffix最后一个后缀含点隐藏文件返回空串suffixes全部后缀列表如[.tar, .gz]parts路径组件元组绝对路径以/开头is_absolute()是否以/开头joinpath(*other)拼接多个段绝对段替换前者with_name(name)替换末段文件名with_stem(stem)替换 stem保留后缀with_suffix(suffix)替换/删除后缀as_posix()返回 POSIX 字符串内部本就存储 POSIX 形式__fspath__()实现os.PathLike协议未实现的纯方法包括anchor、drive、root、relative_to、is_reserved、match、full_match、with_segments。各属性的计算逻辑集中在 crates/monty/src/types/path.rs 与属性分发getattr_by_staticcrates/monty/src/types/path.rs中。注意两个与 CPython 一致的细节suffixes返回列表parts返回元组类型不同隐藏文件仅一个点且后续无第二个点如.bashrc的stem返回自身、suffix返回空串与 CPython 相同。属性访问还做了 intern 字符串快路径优化py_getattrcrates/monty/src/types/path.rs优先按 intern ID 匹配name/parent/stem/suffix/suffixes/parts未命中直接抛出AttributeError堆分配字符串则走慢路径做字符串比较。/运算符双向拼接/运算符在两个方向上都可用且行为与 CPython 一致str(Path(/usr) / local) # /usr/local str(Path(/usr) / Path(/etc)) # /etc —— 绝对右操作数替换左操作数 str(/usr / Path(bin)) # /usr/bin __rtruediv__ str( / Path(a)) # a str(Path(/usr) / ) # /usr str(Path(/usr) / .) # /usr aug Path(/a) aug / b # /a/b增强赋值同样支持实现上py_truediv_impl与py_rtruediv_implcrates/monty/src/types/path.rs分别调用path_div与path_rdivcrates/monty/src/types/path.rs。非路径操作数会抛出与 CPython 逐字一致的TypeErrorPath(/usr) / 1 # TypeError: unsupported operand type(s) for /: PosixPath and int 1 / Path(/usr) # TypeError: unsupported operand type(s) for /: int and PosixPath Path(/usr) / bbin # TypeError: unsupported operand type(s) for /: PosixPath and bytes另外注意操作数必须是str或Pathbytes一律拒绝这与构造规则保持一致。点号的词法归一化Path构造时会对.组件做词法归一化但不解析..后者需要宿主 I/O 确认符号链接语义str(Path(/a/./b)) # /a/b str(Path(/a/b/.)) # /a/b str(Path(./a)) # a str(Path(/a/b/..)) # /a/b/.. —— .. 保留 str(Path(/a///b)) # /a/b str(Path(.)) # .这些断言来自 crates/monty/test_cases/pathlib__pure.py对应normalize_path中“空段与.段跳过、..保留”的分支逻辑。..的具体处理方式见后文“..在虚拟命名空间中解析”一节它与 CPython 在符号链接存在时存在细微差异。I/O 方法向宿主让渡控制权yield to host文件系统相关方法无法在解释器内完成它们会构造一个OsCall操作系统调用请求由 VM 让渡yield给宿主进程解析。已实现的方法存在性/类型查询exists()、is_file()、is_dir()、is_symlink()读取read_text()、read_bytes()写入write_text(data)、write_bytes(data)、append_text(data)、append_bytes(data)目录/删除/移动mkdir(mode0o777, parentsFalse, exist_okFalse)、unlink()、rmdir()、rename(target)枚举/元数据iterdir()、stat()解析resolve()、absolute()打开open(...)—— 具体文件 API 与差异见 docs/limitations/open.md从源码看 OsCall 的分发链路Monty 在 crates/monty/src/os_dispatch.rs 中通过is_path_os_method预检一旦属性名命中Exists、IsFile、IsDir、IsSymlink、ReadText、ReadBytes、StatMethod、Iterdir、Resolve、Absolute、Unlink、Rmdir、WriteText、AppendText、WriteBytes、AppendBytes、Mkdir、Renamecrates/monty/src/types/path.rs 中的py_call_attr就提取路径字符串、把参数所有权转移给构建器build_path_os_callcrates/monty/src/os_dispatch.rs将其组装为带类型化参数结构的OsFunctionCall变体最终以CallResult::OsCall返回给 VM 让渡宿主。路径型方法如exists走path_only!宏只传路径读写类方法额外提取数据参数mkdir/rename则走各自的参数解析结构。Path.mkdir()的参数行为mkdir解析mode、parents、exist_ok三个参数其中mode仅为了签名兼容而被接受——Monty 不建模 POSIX 权限位传入任意值都不影响结果。参数解析由PathMkdirArgscrates/monty/src/os_dispatch.rs完成三个字段默认值分别对应0o777、False、False。两个重要差异missing_ok和target_is_directory关键字不被解析。这两个是 CPython 其他方法unlink/rmdir接受的参数Monty 只接受上面文档化的位置参数传入多余关键字会报错。过多位置参数的错误信息口径不同。Path.mkdir()的 too-many-positional 错误只统计可见参数MontyPath.mkdir() takes from 0 to 3 positional arguments but 4 were givenCPython会把绑定的self一并计入报takes from 1 to 4 … but 5 were given真值语义与 CPython 一致crates/monty/test_cases/pathlib__os.py 专门覆盖了这类边界mkdir(exist_ok)空串为假必须抛出FileExistsErrormkdir(parents[])在父目录缺失时必须抛出FileNotFoundError而mkdir(parentsyes)、mkdir(exist_ok[0])这类非空真值对象则应正常通过。Path.open()复用内置 open 机制Path.open(moder, ...)与内置open()共享同一套底层机制py_call_attr把self作为隐式file参数前置再转发给builtin_open见 crates/monty/src/types/path.rs因此 docs/limitations/open.md 中列出的所有差异对open(path, ...)与path.open(...)同样适用。要点摘录更新模式r/w/a等与独占创建模式x被拒绝ValueError只有file和mode被真正处理buffering、encoding、errors、newline、closefd、opener传非默认值会抛TypeError: name argument is not yet supportedencodingutf-8例外被接受为无操作返回的文件对象支持read/readline/readlines/write/seek/tell/close等但不支持truncate()、fileno()、isatty()与for line in f:迭代Monty从不在调用间持有宿主文件描述符每次读写都是一次性 OS 调用因此宿主外部进程能在两次调用之间观察到中间状态。未实现的 I/O 方法以下方法当前未实现glob、rglob、touch、chmod、lchmod、owner、group、symlink_to、hardlink_to、link_to、readlink、lstat、samefile、walk、replace、expanduser。沙箱代码中如依赖目录通配或符号链接操作需要改用iterdir()自行过滤或由宿主在挂载前完成相应文件准备。路径规范化与沙箱边界每一个 I/O 调用都会路由到宿主的挂载表mount table路径被严格限定在挂载根目录内解析。完整的沙箱文件系统语义见 docs/limitations/filesystem.md其中与pathlib强相关的约束包括无挂载即无文件系统未显式挂载任何目录时open()与所有pathlibI/O 方法对任何路径都会抛PermissionError。Path.exists()等布尔谓词则不抛错、统一返回False被封锁的路径与不存在的路径不可区分。挂载模式决定权限ReadOnly只读、ReadWrite读写、OverlayMemory写时复制写入仅留在内存、不触达宿主。在ReadOnly挂载上执行write_text、mkdir、unlink等会抛PermissionError。非普通文件不可读写对 FIFO、socket、设备节点等特殊文件的读、写、追加与open会抛PermissionErrorCPython 会阻塞等待对端exists/is_file/is_dir/is_symlink/stat仍可作用于特殊文件。路径长度与组件数上限超过 4096 字节、或超过 64 个组件的路径抛OSError [Errno 36] File name too long超长时exists等谓词返回False而resolve()/absolute()直接抛错。64 组件上限是 Monty 自有的约束CPython 没有。..在虚拟命名空间中解析..在触达文件系统前就被词法折叠始终指向词法父目录而不是像 POSIX 那样先跟随符号链接再解析。因此当路径中混有符号链接目录时如ld - sub/deep读取ld/../sibling.txtMonty 得到sibling.txt而 CPython 得到sub/sibling.txt。这是让..永远无法逃逸的刻意设计仅影响与符号链接混用的路径。空字节拒绝任何路径组件含空字节都会抛ValueError。返回值是虚拟路径resolve()等返回给沙箱的永远是虚拟路径绝不会是宿主路径。路径是 UTF-8 字符串沙箱命名空间严格 UTF-8含非 UTF-8 名称条目的目录重命名会被拒绝。I/O 谓词的沙箱语义来自 docs/limitations/filesystem.md 的几条与pathlib直接相关的语义需要特别留意直接挂载ReadWrite/ReadOnly中仅相对目标的符号链接被跟随绝对目标的链接抛PermissionError即使目标就在同一挂载内。OverlayMemory模式则完全拒绝符号链接任何含符号链接的路径操作都抛PermissionError但is_symlink()仍返回True。布尔谓词exists()/is_file()/is_dir()永不抛错离开挂载范围的路径一律返回False。重命名仅在源与目标落在同一个挂载内时被服务跨挂载或一侧无挂载抛OSError [Errno 18] Invalid cross-device link。挂载根目录自身不能被重命名或删除rename/rmdir对挂载根路径抛PermissionError。测试用例验证行为即契约仓库的测试用例完整覆盖了本文描述的 API 表面既是行为契约也是可复制的示例crates/monty/test_cases/pathlib__pure.py纯路径操作的完整断言——构造、name/parent/stem/suffix/suffixes/parts、is_absolute、joinpath、with_name/with_suffix、/运算符含__rtruediv__、增强赋值、非法操作数的TypeError文案、as_posix、__fspath__、点号归一化与repr。文件头部标注了skip-cpython-windowsWindows 上的 CPython 解析路径方式不同因此该用例仅在非 Windows 宿主上做 CPython 对照。crates/monty/test_cases/pathlib__os.pyI/O 方法的端到端验证标注call-external需要宿主配合——exists/is_file/is_dir/is_symlink、read_text/read_bytes、write_text/write_bytes、mkdir含parents/exist_ok与真值语义边界、unlink/rmdir、rename、iterdir返回Path对象而非字符串且结果可继续参与运算、stat含按索引访问与文件类型位校验、resolve/absolute以及“纯路径拼接 I/O 调用”的组合用法。crates/monty/test_cases/pathlib__os_read_error.py错误路径验证——读取不存在的文件抛FileNotFoundError: [Errno 2] No such file or directory: /nonexistent错误文案与 CPython 一致。crates/monty/test_cases/pathlib__import.py模块导入与属性访问验证。实用建议在 Monty 沙箱中正确使用 pathlib综合以上能力边界编写沙箱内路径代码时有几点实用建议把Path当作“纯 POSIX 字符串 受控 I/O”来用。纯路径操作拼接、取name/parent/suffix、is_absolute、joinpath等与 CPython 完全一致可以放心使用需要做目录匹配时用iterdir() 手动过滤替代glob。文件操作前先确认挂载。没有挂载就没有文件系统在运行前通过宿主挂载ReadWrite或OverlayMemory目录否则read_text/write_text一律PermissionError。OverlayMemory特别适合 AI 场景的临时数据写入被捕获在内存中、随本轮喂送结束而丢弃。读写文本用read_text()/write_text()二进制用read_bytes()/write_bytes()避免直接依赖open()的高级模式——更新模式与x独占模式都不支持。不要依赖cwd()/home()、符号链接和..穿越语义。沙箱路径一律从挂载根出发..只做词法折叠涉及符号链接的树如node_modules需要宿主预先把链接改写成相对目标再挂载。注意mkdir(mode...)的权限参数无实际效果mode仅为签名兼容目录权限由挂载配置统一决定。复用路径拼接的测试写法base / subdir / nested.txt之后再read_text()的链式写法在 Monty 中工作良好见 crates/monty/test_cases/pathlib__os.py这与你熟悉的 CPython 风格完全一致。小结Monty 的pathlib是一个刻意最小化的实现Path是唯一的类永远表示沙箱内的虚拟 POSIX 路径纯路径操作在解释器内完成与 CPython 保持高度一致含错误文案而一切涉及文件系统的操作都通过OsCall让渡给宿主由挂载表在虚拟路径空间内安全裁决。理解“纯路径在 VM 内、I/O 在宿主”这条分界线就能在沙箱约束下写出既安全、又贴近 CPython 习惯的代码。深入阅读 crates/monty/src/modules/pathlib.rs、crates/monty/src/types/path.rs 与 crates/monty/src/os_dispatch.rs 三个文件配合 docs/limitations/open.md 与 docs/limitations/filesystem.md 两篇边界文档即可掌握该模块的全部细节。【免费下载链接】montyA minimal, secure Python interpreter written in Rust for use by AI项目地址: https://gitcode.com/GitHub_Trending/monty3/monty创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考