普贤教程 › 包参考

shutil 包

文件/目录操作（子集）

项	值
包名	`shutil`
版本	`0.2.0`
可用版本	`0.1.0 / 0.2.0`
入口	`shutil.px`
分类	`文件系统`
文件数 / 行数	`1 / 162`

安装与引入

bash

pxpkg init          # 首次
pxpkg add shutil@0.2.0
pxpkg install

import shutil

所属分类教程：文件系统

公开接口

函数	参数
`sh_join`	`a, b`
`sh_file_exists`	`path`
`sh_is_dir`	`path`
`sh_read_text`	`path`
`sh_write_text`	`path, s`
`sh_append_text`	`path, s`
`sh_copy`	`src, dst`
`sh_move`	`src, dst`
`sh_remove_file`	`path`
`sh_remove_tree`	`path`
`sh_mkdirs`	`path`
`sh_list_dir`	`path`
`sh_list_files`	`path`

其余 4 个 def（内部与辅助，可直接调用但不属稳定接口）

函数	参数
`sh_basename`	`path`
`sh_dirname`	`path`
`sh_ext`	`path`
`sh_size`	`path`

包内说明（源码头注释）

text

============================================================
普贤生态库：registry/shutil —— 文件/目录操作（子集）
------------------------------------------------------------
纯函数库（有 IO，但无状态），编译（px build）与解释（px run）双模式一致。
sh_file_exists(path) → bool                是否存在
sh_is_dir(path)      → bool                是否目录
sh_read_text(path)   → Ok(str) | Err       读文本
sh_write_text(path, s) → Ok | Err          写文本（覆盖）
sh_append_text(path, s) → Ok | Err         追加文本
sh_copy(src, dst)    → Ok | Err            复制文件
sh_move(src, dst)    → Ok | Err            移动/重命名（rename 失败回退复制+删）
sh_remove_file(path) → Ok | Err            删除文件（不存在 → Err）
sh_remove_tree(path) → Ok | Err            递归删除目录树
sh_mkdirs(path)      → Ok | Err            递归建目录（mkdir -p）
sh_list_dir(path)    → Ok([名称...]) | Err 列目录（先 file_stat 守卫，
规避 PX-DEF-014：list_dir 对
缺失目录直接终止进程）
sh_list_files(path)  → Ok([名称...]) | Err 仅列普通文件
sh_join(a, b)        → str                 路径拼接（处理尾部 "/"）
说明：失败一律 Err 不终止进程（用 *_opt 变体与显式守卫）。
============================================================
路径拼接：a 尾部 "/" 去重