Chapter 54: Filesystem and OS Abstraction

Python 程序一旦离开纯对象计算，就会进入操作系统边界：路径需要解释成文件系统位置，文件需要映射到 OS 资源句柄，子进程需要继承环境变量和标准流，解释器自身还会暴露 argv、sys.path、模块表和异常状态。本章讨论的主问题是：怎样把一个 Python 程序中的路径、文件、进程、环境变量和解释器状态放回同一条 runtime 边界链中判断。

读完本章后，读者应能定位一个 I/O 现象发生在哪一层：pathlib 的路径对象层、os 的系统接口层、sys 的解释器状态层、Python file object 的缓冲与编码层，还是 subprocess 创建的新进程层。这个定位能力会直接影响工程判断，例如配置文件写入是否具备原子替换属性，CLI 参数乱码应查看哪种编码，子进程为何看不到某个环境变量，以及文件对象关闭后底层 fd 是否仍然可用。

本章使用一个贯穿材料：一个部署脚本读取环境变量，拼出应用目录，写入配置文件，再启动一个子进程读取该配置。这个例子同时触发路径语义、环境变量、文件描述符、标准流、exit code 和解释器状态。

from pathlib import Path
import json
import os
import subprocess
import sys


def deploy_config() -> subprocess.CompletedProcess[str]:
    app_home = Path(os.environ.get("APP_HOME", ".")).expanduser()
    config_dir = app_home / "config"
    config_dir.mkdir(parents=True, exist_ok=True)

    target = config_dir / "runtime.json"
    temp = target.with_suffix(".json.tmp")

    payload = {
        "argv": sys.argv,
        "cwd": os.getcwd(),
        "module_search_root": sys.path[0] if sys.path else "",
    }

    with temp.open("w", encoding="utf-8") as file:
        json.dump(payload, file)
        file.flush()
        os.fsync(file.fileno())

    os.replace(temp, target)

    child_env = os.environ | {"APP_CONFIG": os.fspath(target)}
    return subprocess.run(
        [sys.executable, "-c", "import os; print(os.environ['APP_CONFIG'])"],
        cwd=os.fspath(app_home),
        env=child_env,
        text=True,
        capture_output=True,
        check=False,
    )

这段代码的关键关系可以压缩成一条边界链：路径对象先表达位置，文件对象把文本编码与缓冲叠加在 fd 上，os 把 fd 和目录操作交给操作系统，subprocess 创建新的进程边界，sys 提供当前解释器的启动参数、模块搜索路径和可执行文件路径。后文每节都会回到这条链，拆开对应层的责任和失败条件。

下面的图只描述本章贯穿材料中的资源流向，边界从 Python 对象层进入 OS 资源层，再进入子进程层。

图中的 Path、file object、fd、filesystem、process 分属不同层。工程排查时要先确认现象在哪一层出现，再选择对应证据：路径拼接错误看 Path 的 lexical 结果，权限错误看真实文件系统操作，写入丢失看缓冲与 fsync，子进程配置错误看 env 传递，命令失败看 returncode、stdout 和 stderr。

54.1 pathlib

pathlib 把路径从普通字符串提升为带语义的对象。这里的语义包含路径风格、组件切分、父子拼接、后缀、相对关系和少量真实文件系统操作。Python 官方文档把 pathlib 分成 pure paths 和 concrete paths：pure paths 只做计算性路径处理，concrete paths 在 pure paths 基础上加入 I/O 操作。

贯穿材料中的 app_home = Path(os.environ.get("APP_HOME", ".")).expanduser() 先创建当前平台的 concrete path。Path 对象仍然只是 Python 对象；创建它不会检查目录是否存在，也不会打开文件。expanduser() 会把用户目录标记展开成具体路径字符串形态，随后 config_dir.mkdir(...) 才跨入真实文件系统操作。

PurePath 的价值在于隔离路径解析和 OS 访问。读取 Windows 路径配置、生成远程部署路径、比较后缀和父目录时，程序可以使用 PureWindowsPath 或 PurePosixPath 在当前平台上计算路径形态。它能回答“这个路径字符串如何被某种平台规则切分”，无法回答“这个文件在当前机器上是否存在”。

Path 的价值在于把路径表达和常见 I/O 放在同一个对象上。target.with_suffix(".json.tmp") 只生成另一个路径对象；temp.open("w", encoding="utf-8") 会打开文件；target.exists()、target.stat()、target.resolve() 会查询真实 filesystem 状态。判断 pathlib 代码时要先区分方法属于 lexical operation 还是 filesystem operation。

下面的例子展示同一个路径对象在两类操作中的差异。代码目的是证明：parent 和拼接只处理路径文本结构，resolve() 会触发现实路径解析。

from pathlib import Path, PurePosixPath

logical = PurePosixPath("logs/../runtime.log")
print(logical.parent)           # logs/..
print(logical.parts)            # ('logs', '..', 'runtime.log')

real = Path("logs/../runtime.log")
print(real.resolve())           # 需要结合当前工作目录和文件系统解析

PurePosixPath("logs/../runtime.log").parent 的结果来自字符串组件规则。它不会假设 logs 是普通目录、符号链接，还是压根不存在。Path.resolve() 进入当前机器的 filesystem 语义，会受当前工作目录、符号链接、权限和路径存在性影响。这个边界解释了为什么部署脚本在写入前使用 mkdir()，在传给子进程前使用 os.fspath(target)：前者创建真实目录，后者把 PathLike 对象显式转回 OS 接口接受的文件系统路径表示。

pathlib 还参与跨库协议。实现 __fspath__() 的对象属于 path-like object，os.fspath() 会把它规范化为 str 或 bytes。这让 Path 可以被 open()、os.replace()、subprocess.run(cwd=...) 等接口接受。工程上可以在业务层保留 Path，在进入低层接口或日志边界时再转成 str，这样路径拼接和路径格式化集中在同一套语义上。

pathlib 的主要风险来自把 lexical 结果当作权限或存在性结论。Path("a/../b") 的父目录、后缀和名字都可计算，但这个路径最终指向哪里，要结合 cwd、符号链接、挂载点和权限。路径对象给的是位置表达，真实文件系统给的是状态结果。

54.2 os

os 模块是 Python 标准库中最接近操作系统接口的一层。它暴露进程参数、环境变量、目录切换、权限、文件描述符、底层读写、rename/replace、stat 以及平台能力查询。Python 官方文档把 os 定位为 miscellaneous operating system interfaces，这个名称说明它覆盖的是一组 OS 边界入口，而非单一抽象对象。

贯穿材料中 os.getcwd() 读取当前进程工作目录，os.fsync(file.fileno()) 要求内核把文件数据推向存储设备，os.replace(temp, target) 执行目标路径替换，os.fspath(target) 把 PathLike 对象转成文件系统路径表示。这些调用发生在 Python object model 和 OS resource model 的交界处。

os 的核心判断顺序是：先看函数是否操作当前进程状态，再看它是否操作路径命名空间，再看它是否操作 fd。os.environ 和 os.getcwd() 属于当前进程状态；os.makedirs()、os.replace()、os.stat() 属于路径命名空间；os.read()、os.write()、os.fsync()、os.dup() 属于 fd 层。混淆这三层会导致错误排查方向偏移。

下面的例子展示 file object 和 os fd 接口的衔接。代码目的是证明：Python 的 file object 负责文本编码和缓冲，os.fsync() 接收的是底层 fd。

from pathlib import Path
import os

path = Path("runtime.txt")
with path.open("w", encoding="utf-8") as file:
    file.write("ready\n")
    file.flush()
    os.fsync(file.fileno())

file.write() 写入的是 Python 文本接口，文本会经过编码和缓冲。file.flush() 把 Python 层缓冲推向 OS；os.fsync(file.fileno()) 使用 fd 请求 OS 同步。这个顺序说明“写入函数返回成功”只覆盖 Python 层调用成功，持久性判断还要看缓冲、内核页缓存、文件系统和存储设备策略。对配置文件、锁文件、索引文件这类状态文件，写入路径必须明确同步边界。

os.replace() 常用于原子替换目标文件。贯穿材料先写临时文件，再替换正式配置文件。这样读者看到的目标路径要么保留旧内容，要么指向新文件；中间半截 JSON 暴露给读取者的概率被系统调用语义压低。这个结论还依赖同一 filesystem、权限、目录存在性和平台实现。跨设备移动、网络文件系统、权限受限目录和杀进程时机都可能改变观察结果。

os 还承载平台差异。Unix 有权限位、uid/gid、文件描述符继承、信号、符号链接和大小写敏感路径；Windows 有 drive、UNC path、环境变量 key 大写化、不同的权限模型和进程创建规则。Python 把一部分差异包装成统一函数签名，但函数可用性、异常类型、路径解释和继承行为仍受平台影响。写跨平台代码时，os.name、sys.platform、Path flavour、能力检测函数和失败异常都属于判断证据。

os 的工程使用边界可以归纳成一句话：需要表达路径结构时优先留在 pathlib，需要改变进程状态、查询 OS 状态或操作 fd 时进入 os，需要递归复制、删除目录树和高级文件操作时再引入 shutil 或 tempfile。这样能让每一层承担清晰责任。

54.3 sys

sys 暴露的是当前 Python 解释器实例的状态。它看起来也包含路径和 I/O 对象，例如 sys.path、sys.argv、sys.stdin、sys.stdout、sys.stderr，但这些对象的归属层是 interpreter state。Python 官方文档将 sys 描述为 system-specific parameters and functions；在本章语境中，它回答“当前解释器怎样启动、怎样查模块、当前异常和 hook 状态是什么”。

贯穿材料中的 sys.argv 记录用户程序参数，sys.path[0] 记录模块搜索路径的第一个位置，sys.executable 提供当前解释器可执行文件路径。它们不直接操作文件系统，却会影响文件系统访问和子进程行为：sys.path 决定 import 搜索入口，sys.argv 影响 CLI 解析，sys.executable 决定子进程使用哪个 Python 解释器。

sys.argv 是解释器启动时形成的参数列表。文档说明 argv[0] 通常是脚本名，使用 -c 时为 '-c'，没有脚本名时为空字符串；Unix 上命令行参数由 OS 以 bytes 传入，Python 使用 filesystem encoding 和 surrogateescape 解码。这个细节解释了 CLI 参数乱码排查的边界：业务代码看到的是已经解码后的 str，需要原始 bytes 时应通过 os.fsencode(arg) 反向取得。

sys.path 是 import system 的搜索路径列表。它由环境变量、安装默认值、启动方式和 site 初始化共同影响，程序也可以修改它。贯穿材料把 sys.path[0] 写入配置，目的不是推荐把它持久化，而是让读者看到：解释器状态可以被序列化成外部文件，外部文件再反过来影响下一轮启动和部署行为。排查“本地能导入、服务中导入失败”时，cwd、sys.path[0]、PYTHONPATH、虚拟环境和启动命令应放在同一组证据里看。

sys.modules 是已加载模块缓存表。它不是普通业务缓存，而是 import system 的 runtime 状态。一个模块被导入后，对应 module object 会留在 sys.modules 中；后续导入通常复用该对象。文件系统上的 .py 文件变化不会自动替换内存中的 module object。这个边界会影响热更新、插件加载、测试隔离和 reload 风险。

sys.exception() 和 sys.exc_info() 暴露当前异常处理状态。Python 3.11 起，sys.exception() 返回当前最内层 exception handler 正在处理的异常实例；没有 handler 时返回 None。这类接口说明 sys 并非单纯“系统信息集合”，它可以读取解释器当前控制流状态。调试框架、日志框架和测试框架使用这些接口时，会碰到 frame、traceback、引用生命周期和 hook 行为。

sys.settrace()、sys.setprofile()、sys.excepthook、sys.unraisablehook 属于 runtime hook 边界。它们能观察或改变解释器可见行为，也会带来性能开销和全局状态风险。工程判断时应把 hook 当作全局解释器配置处理，确认安装时机、恢复策略、线程边界和异常路径。

54.4 filesystem abstraction

filesystem abstraction 指 Python 对文件系统命名空间、路径编码、权限、链接、临时文件、替换操作和跨平台差异的统一表达。它的工作目标是让业务代码用稳定对象和函数描述文件操作，同时保留足够的 OS 事实，让失败原因能被定位。

贯穿材料写入配置文件时，涉及六个 filesystem 判断点：路径从环境变量来，路径可能相对当前工作目录，目录可能不存在，目标文件可能已存在，临时文件与目标文件需要位于同一目录，替换后读取者应看到完整 JSON。每个判断点对应不同证据：输入字符串、cwd、权限、目录结构、文件系统边界和原子替换语义。

路径编码是第一层边界。Python 代码中路径通常是 str，OS 可能以 bytes 或平台原生 Unicode API 表示路径。Unix 上文件名可以包含非 UTF-8 bytes，Python 使用 filesystem encoding 和 error handler 保持往返能力；Windows 上路径以 Unicode 语义为主。CLI 参数、环境变量和文件名都可能受到编码边界影响。排查乱码时，应把 sys.getfilesystemencoding()、os.fsencode()、os.fsdecode()、locale、UTF-8 mode 和启动环境放在一起看。

权限是第二层边界。Path.exists() 返回 false 可能意味着路径不存在，也可能来自权限或平台返回信息受限。open()、mkdir()、replace() 抛出的 PermissionError、FileNotFoundError、IsADirectoryError、NotADirectoryError、OSError 会给出更接近 OS 的失败原因。工程代码应在真正操作点捕捉异常，并把 path、operation、cwd 和权限上下文写入日志。

符号链接是第三层边界。Path("a/../b") 的 lexical 结果无法判断真实目标，因为 a 可能是符号链接。Path.resolve() 会尝试把符号链接和相对组件归一到真实路径；但它也会受路径存在性和权限影响。安全敏感路径、沙箱路径和上传文件路径应区分“文本上位于某目录下”和“解析后真实目标位于某目录下”。

临时文件和原子替换是第四层边界。贯穿材料中临时文件放在目标文件同一目录，随后用 os.replace(temp, target) 替换。这个模式让同目录权限、同 filesystem 和读者可见性更可控。临时文件如果放到系统临时目录，再跨设备移动到目标目录，就可能遇到 EXDEV 或原子性丢失。配置写入、数据库快照、索引文件和缓存元数据都应把临时文件位置作为设计条件。

跨平台差异是第五层边界。大小写敏感性、路径分隔符、drive、UNC path、保留文件名、换行符、执行权限、文件锁和 rename 覆盖规则都可能影响同一段代码。pathlib 能统一很多路径构造语法，os 能统一很多接口名字，但它们不会消除平台的文件系统事实。跨平台测试应覆盖路径大小写、空格、非 ASCII 字符、长路径、符号链接和权限受限目录。

filesystem abstraction 的可复用判断顺序是：先固定输入路径来源，再确定 lexical 结果，再确认 cwd 和平台 flavour，再执行真实 I/O 操作，再根据异常和 stat 结果判断状态。这个顺序能把“路径长得对”与“文件系统接受这个操作”分开处理。

54.5 process abstraction

process abstraction 把一个运行中的程序看成 OS 进程：它有 pid、父子关系、工作目录、环境变量、打开的 fd、标准输入输出错误流、退出码和信号状态。Python 的 subprocess 模块把创建子进程、连接标准流和取得返回码封装成高层接口。官方文档说明 subprocess 能创建新进程、连接 input/output/error pipes 并取得 return codes。

贯穿材料用 subprocess.run(...) 启动一个新的 Python 进程。args 决定执行什么，cwd 决定子进程工作目录，env 决定子进程看到的环境变量，text=True 决定管道输出解码成字符串，capture_output=True 捕获 stdout/stderr，check=False 让调用方自己判断 returncode。这些参数分别对应 process abstraction 的不同部分。

pid 标识运行中的 OS 进程；returncode 标识它已经结束后的退出状态。subprocess.run() 返回 CompletedProcess，这个对象代表已完成的子进程结果。通常 returncode == 0 表示成功；在 POSIX 上，负值 -N 表示子进程被信号 N 终止。这个边界说明进程失败判断要同时检查 stdout 文本、returncode 和 stderr。

标准流是子进程最常见的数据边界。stdin 是写给子进程的数据入口，stdout 是普通输出，stderr 是错误输出或诊断输出。capture_output=True 等价于捕获 stdout 和 stderr；text=True 会把 bytes 按指定或默认编码解码成 str。如果命令输出很大，管道缓冲、内存占用、阻塞和超时都可能成为问题；这时应选择流式读取、文件重定向或更细的 Popen 控制。

环境变量在进程边界处复制。env=child_env 传给 subprocess.run() 后，子进程获得这份 mapping 对应的环境；父进程后续修改 os.environ 不会改变已经启动的子进程。贯穿材料用 os.environ | {"APP_CONFIG": os.fspath(target)} 构造子进程环境，说明部署脚本应显式声明传给子进程的配置，减少对外部 shell 状态的隐式依赖。

信号和超时属于进程生命周期控制。timeout 可以限制等待时间；POSIX signal 可以终止、暂停或通知进程；Windows 有不同的进程控制模型。Python 把一部分差异折叠进 subprocess API，但 signal 编号、终止语义、进程组和控制台行为仍与平台绑定。需要管理长任务、服务进程和子进程树时，应明确进程组、清理策略和超时后的资源回收。

process abstraction 的可复用判断顺序是：先确认 args 和 executable，再确认 cwd，再确认 env，再确认 stdin/stdout/stderr 策略，最后根据 returncode、异常、stderr 和超时状态下结论。这个顺序能把“命令没启动”“启动后找不到文件”“运行失败”“输出解码失败”拆成不同问题。

54.6 environment variable

environment variable 是进程启动时继承的一组字符串配置。它处在 shell、服务管理器、容器、操作系统和 Python runtime 的交界处。Python 中最常见的入口是 os.environ，它是一个 mapping，key 和 value 都以字符串形式暴露；官方文档说明该 mapping 通常在 Python 启动期间首次导入 os 时捕获，修改 mapping 会自动调用底层环境更新函数。

贯穿材料中 APP_HOME 决定应用目录，APP_CONFIG 被传给子进程。前者从父进程环境读取，后者由 Python 代码构造后传入新进程。两个变量都只是字符串；它们不会自动验证路径存在性、权限或编码可用性。环境变量进入业务逻辑后，应尽快转成更具体的对象，例如 Path、整数、布尔配置或枚举值，并在边界处给出错误信息。

环境变量影响 import path 和 runtime flag。PYTHONPATH 会参与初始化 sys.path；PYTHONUTF8、locale 相关变量和启动参数会影响 UTF-8 mode、文件系统编码和标准流编码；虚拟环境相关变量会影响解释器发现库的位置。排查部署差异时，环境变量、启动命令、sys.flags、sys.path 和 sys.executable 应一起记录。

os.environ 是当前进程中的环境映射视图。直接修改 os.environ["NAME"] = "value" 会更新当前进程环境，并影响之后创建的子进程默认继承内容。已经运行的子进程不会被反向更新。Python 3.14 文档还提供 os.reload_environ()，用于把外部修改重新加载到 os.environ 和 os.environb，并明确标注该函数非线程安全。多线程服务中读取环境变量应在启动阶段完成，运行中频繁重载会扩大状态竞争面。

Windows 与 Unix 的环境变量语义存在差异。Windows 上 key 会转成大写；Unix 上 key/value 与文件系统编码和 surrogateescape 相关；POSIX 环境还可以用 bytes 形式处理。跨平台配置应约束变量名大小写、编码、缺省值和错误提示。把环境变量当成 typed config 之前，应完成解析和校验。

环境变量的工程边界可以归纳为：它适合作为进程启动配置，不适合作为进程内动态状态总线。配置读取应集中在启动阶段，解析后转为明确类型，传给子进程时使用显式 env mapping，日志中记录必要键名和来源，敏感值只记录是否存在和来源层级。

54.7 file descriptor

file descriptor 是 OS 级资源句柄，通常表现为一个小整数。它指向内核中的打开文件、管道、socket、终端或其他 I/O 对象。Python file object 在 fd 上叠加了 buffering、encoding、换行转换、上下文管理和高级方法。这个层次关系解释了为什么同一个文件操作会同时出现 file.write()、file.flush()、file.fileno() 和 os.write()。

贯穿材料中的 file.fileno() 把 Python file object 映射回底层 fd。随后 os.fsync() 使用这个 fd 要求 OS 同步。with temp.open(...) as file: 则保证 file object 在退出时关闭，关闭通常会释放其持有的 fd。这里的 owner 是 file object；fd 是它管理的 OS 资源；os.fsync() 只是借用 fd 执行同步操作。

下面的例子展示 fd 层绕过文本编码和 Python 缓冲。代码目的是证明：os.write() 接收 bytes 和 fd，返回实际写入字节数。

import os

fd = os.open("raw.log", os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
try:
    written = os.write(fd, b"raw bytes\n")
    os.fsync(fd)
finally:
    os.close(fd)

print(written)

这段代码没有 file object，所以没有 encoding="utf-8"、没有文本换行处理，也没有 file object 的上下文管理。资源所有权由代码手动维护，finally 中必须关闭 fd。使用 fd 层接口的收益是控制粒度更低，例如非阻塞、继承、dup、管道、sendfile、设备文件和原子标志；代价是调用方要处理 bytes、部分读写、关闭顺序、异常路径和平台可用性。

fd 还会跨进程边界。标准输入、标准输出、标准错误在多数平台上对应约定 fd 或句柄；subprocess 可以把管道、文件或 DEVNULL 连接给子进程。Python 3.4 之后，新创建的 fd 默认更倾向于非继承，以降低无意泄漏给子进程的风险；但标准流、显式传递的 handle、平台规则和 subprocess 参数仍会影响继承结果。排查“文件被占用”“子进程持有旧日志文件”“端口无法释放”时，要检查 fd/handle 是否被其他对象或子进程持有。

fd 生命周期要与 file object 生命周期分开判断。file.close() 会关闭其持有的 fd；os.close(fd) 直接关闭 fd，之后继续使用原 file object 可能得到 OSError；os.dup(fd) 会创建指向同一底层资源的新 fd，关闭其中一个不会自动关闭另一个。涉及 fileno()、detach()、fdopen() 和 dup() 的代码必须明确 owner 转移关系。

file descriptor 的可复用判断顺序是：先确认谁拥有 fd，再确认 fd 指向什么资源，再确认是否有 Python buffering，再确认是否会被子进程继承，最后确认关闭路径和异常路径。这个顺序能解释多数底层 I/O 泄漏、阻塞和同步问题。

54.8 path semantics

path semantics 指路径字符串在特定平台、当前工作目录、路径风格、文件系统规则和安全边界下如何被解释。它覆盖 relative/absolute、cwd、home、大小写敏感性、separator、drive、URI 和 sandbox。pathlib 让路径操作更结构化，但路径语义最终仍由平台和文件系统共同决定。

相对路径依赖 cwd。贯穿材料中 Path(os.environ.get("APP_HOME", ".")) 在环境变量缺失时得到 .，也就是当前工作目录。随后 subprocess.run(..., cwd=os.fspath(app_home)) 又把子进程工作目录切到应用目录。父进程和子进程各自有自己的 cwd；子进程中相对路径会基于它的 cwd 解析。排查相对路径错误时，必须记录父进程启动目录、传给子进程的 cwd 和代码内部构造路径的时机。

absolute path 也带平台差异。POSIX 上 /var/app 以根目录开头；Windows 上绝对路径通常需要 drive 和 root，例如 C:\app，UNC path 还包含 server/share。PureWindowsPath("/app") 在 Windows 风格下可能只有 root 而缺 drive，语义与 C:\app 不同。跨平台代码应把“是否 absolute”交给 Path.is_absolute() 这类语义函数，而非用字符串前缀粗略判断。

home expansion 是 shell 习惯进入 Python 后的显式动作。Path("~/app") 本身只是包含波浪号的路径对象；调用 expanduser() 后才会根据当前用户环境展开。部署脚本、定时任务和服务进程中的 home 可能不同，容器内用户也可能没有预期 home 目录。使用 ~ 配置时，应在启动阶段展开并记录展开结果。

大小写敏感性和 separator 会影响缓存键、去重和安全判断。Windows 路径通常大小写不敏感但保留大小写，POSIX 文件系统通常大小写敏感；macOS 还取决于具体 volume 配置。PureWindowsPath("FOO") == PureWindowsPath("foo") 与 PurePosixPath("FOO") == PurePosixPath("foo") 的结果不同。把路径当作 dict key、缓存 key 或权限白名单时，应先确认目标平台的 case-folding 语义。

URI 和本地路径属于不同命名体系。file:// URI、HTTP URL、S3 key、zip 内路径和本地 filesystem path 都可以长得像“路径”，但解析规则、权限模型和 I/O API 不同。Python 中 Path 主要表达本地 filesystem path；把 URL 传给 Path 会得到一个普通路径对象，无法获得网络资源语义。需要处理远程资源时，应使用对应库的 URI 解析和访问接口。

sandbox 是路径语义中最容易出安全问题的部分。判断用户输入是否落在某个目录内，应先把 base 和 candidate 变成解析后的真实路径，再用同一平台语义比较归属关系。只看字符串前缀会被 ..、符号链接、大小写、分隔符和编码差异绕开。这个判断属于安全边界，应把路径解析失败、权限不足和符号链接策略作为显式分支处理。

path semantics 的最终判断顺序是：先确定路径来源，再确定当前进程或子进程的 cwd，再确定平台 flavour，再展开 home 和环境变量，再解析符号链接和真实位置，最后进入权限、存在性和操作结果判断。这个顺序能把路径从“字符串”还原成可验证的 runtime 事实。

最小自检任务

阅读下面的代码，判断它在路径、环境变量、file object、fd、子进程和解释器状态上分别发生了什么。重点回答四个问题：settings 是哪一层的对象，配置文件写入何时进入 OS 层，子进程从哪里得到 APP_SETTINGS，以及 sys.path[0] 记录的是什么状态。

from pathlib import Path
import os
import subprocess
import sys

settings = Path(os.environ.get("APP_HOME", ".")) / "settings.json"
settings.parent.mkdir(parents=True, exist_ok=True)

with settings.open("w", encoding="utf-8") as stream:
    stream.write("{}\n")
    stream.flush()
    os.fsync(stream.fileno())

result = subprocess.run(
    [sys.executable, "-c", "import os; print(os.environ['APP_SETTINGS'])"],
    env=os.environ | {"APP_SETTINGS": os.fspath(settings)},
    text=True,
    capture_output=True,
)

print(sys.path[0])
print(result.returncode, result.stdout)

答案要点

settings 是 Path 对象，它先表达路径结构，是否存在和是否可写要等 mkdir()、open()、fsync() 等真实 I/O 操作给出结果。settings.parent.mkdir(...) 进入 filesystem 操作，settings.open(...) 创建 Python file object 并打开底层 fd，stream.write() 先经过文本编码和缓冲，stream.flush() 推动 Python 缓冲写出，os.fsync(stream.fileno()) 使用 fd 请求 OS 同步。

子进程通过 env=os.environ | {"APP_SETTINGS": os.fspath(settings)} 得到 APP_SETTINGS。这里传入的是新进程环境 mapping；子进程启动后读取自己的环境变量副本。os.fspath(settings) 把 PathLike 对象转成文件系统路径表示，适合跨进程边界传递。

sys.path[0] 是当前解释器的 import 搜索路径状态之一，受启动方式、脚本位置、当前工作目录和环境影响。它不是配置文件所在目录的自动证明，也不是子进程的 sys.path[0]。判断导入问题时，需要同时查看父进程启动方式、子进程命令、cwd、PYTHONPATH 和虚拟环境。

这段代码的完整边界链是：环境变量字符串 → Path 路径对象 → 真实目录和文件操作 → Python file object → fd → OS 同步 → 显式子进程环境 → 子进程 stdout/returncode → 当前解释器 sys.path 观察。稳定的排查方式是逐层固定输入和证据，再判断失败发生在哪一层。

本章知识点总结

• 路径对象：pathlib 把路径字符串包装成带平台语义的对象，先表达位置结构，再由具体方法决定是否进入真实文件系统。
• PurePath 边界：PurePath 只做路径文本和风格计算，不能证明目标存在、权限可用或符号链接解析结果。
• PathLike 协议：实现 __fspath__() 的对象可以通过 os.fspath() 转成底层接口接受的路径表示。
• os 分层：os 同时暴露进程状态、路径命名空间和 fd 接口，排查时应先确认调用落在哪一层。
• 写入持久性：Python file object 的写入会经过编码和缓冲，flush() 与 os.fsync() 分别对应 Python 缓冲和 OS 同步边界。
• 解释器状态：sys.argv、sys.path、sys.modules、异常信息和 hook 都属于当前解释器 runtime state。
• 文件系统语义：路径编码、权限、符号链接、临时文件、原子替换和平台差异共同决定一次文件操作的真实结果。
• 进程边界：subprocess 把 executable、args、cwd、env、标准流、returncode 和 signal 组织成子进程控制模型。
• 环境变量：环境变量是进程启动配置，进入 Python 后应解析为明确类型，传给子进程时应使用显式 env mapping。
• fd 资源：file descriptor 是 OS 级句柄，Python file object 在其上叠加 buffering、encoding 和 context manager。
• 路径语义：relative/absolute、cwd、home、case sensitivity、separator、drive、URI 和 sandbox 都会改变路径解释结果。
• 排查顺序：同类问题应按路径来源、平台语义、真实 I/O、fd 生命周期、子进程环境和解释器状态逐层固定证据。