# `os.path` --- 常見的路徑名操作

原始碼： Lib/posixpath.py (用於 POSIX 系統) 和 Lib/ntpath.py (用於 Windows).

該模組實現了一些有用的路徑名操作函式。若要讀取或寫入檔案，請參閱 `open()` 函數，要存取檔案系統，請參閱 `os` 模組。路徑參數可以以字串、位元組或任何依照 `os.PathLike` 協議實作的物件傳遞。

與 Unix shell 不同，Python 不會自動進行路徑展開（path expansions）。當應用程式需要進行類似 shell 的路徑展開時，可以明確地呼叫 `expanduser()` 和 `expandvars()` 等函式。（另請參閱 `glob` 模組。）

也參考

`pathlib` 模組提供了高階的路徑物件。

備註

所有這些函數都只接受位元組或字串物件作為參數。如果回傳的是路徑或檔案名稱，結果將是相同型別的物件。

備註

由於不同的作業系統具有不同的路徑命名慣例，在標準函式庫中的路徑模組有數個版本可供使用，而 `os.path` 模組都會是運行 Python 之作業系統所適用本地路徑。然而，如果你想要操作始終以某個不同於本機格式表示的路徑，你也可以引入並使用對應的模組。它們都具有相同的介面：

- `posixpath` 用於 UNIX 形式的路徑

- `ntpath` 用於 Windows 的路徑

在 3.8 版的變更: 對於包含有作業系統層級無法表示之字元或位元組的路徑，`exists()`、`lexists()`、`isdir()`、`isfile()`、`islink()` 和 `ismount()` 函式現在會回傳 `False`，而不是引發例外。

os.path.abspath(path)

  回傳經正規化的絕對路徑名 path 。在大多數平台上，這等效於按照以下方式呼叫 `normpath()` 函式：`normpath(join(os.getcwd(), path))`。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.basename(path)

  回傳路徑名 path 的基底名稱。這是將 path 傳遞給函式 `split()` 後回傳結果中的第二個元素。請注意，此函式的結果與 Unix 的 basename 程式不同；對於 `'/foo/bar/'`，basename 回傳 `'bar'`，而 `basename()` 函式回傳空字串（`''`）。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.commonpath(paths)

  回傳序列 paths 中每個路徑名的最長共同子路徑。如果 paths 同時包含絕對路徑和相對路徑、paths 位於不同的磁碟機或 paths 為空，則引發 `ValueError`。與 `commonprefix()` 不同，此函式回傳的是有效路徑。

  適用：Unix、Windows。

  在 3.5 版新加入.

  在 3.6 版的變更: 接受一個類路徑物件的序列。

os.path.commonprefix(list)

  回傳 list 中所有路徑的最長路徑前綴（逐字元比較）。如果 list 為空，則回傳空字串（`''`）。

  備註

  由於此函式是逐字元比較，因此可能會回傳無效的路徑。若要獲得有效的路徑，請參考 `commonpath()` 函式。

      >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
      '/usr/l'

      >>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
      '/usr'

  在 3.6 版的變更: 接受一個 path-like object。

os.path.dirname(path)

  回傳路徑名 path 的目錄名稱。這是將 path 傳遞給函式 `split()` 後回傳之成對結果中的第一個元素。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.exists(path)

  如果 path 是一個存在的路徑或一個開啟的檔案描述器則回傳 `True`。對於已損壞的符號連結則回傳 `False`。在某些平台上，即使 path 實際存在，如果未被授予執行 `os.stat()` 的權限，此函式仍可能回傳 `False`。

  在 3.3 版的變更: 現在 path 可以是一個整數：如果它是一個開啟的檔案描述器，則回傳 `True`；否則回傳 `False`。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.lexists(path)

  如果 path 是一個存在的路徑則回傳 `True`。對於已損壞的符號連結也回傳 `True`。在缺乏 `os.lstat()` 的平台上，與 `exists()` 函式等效。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.expanduser(path)

  在 Unix 和 Windows 上，將引數中以 `~` 或 `~user` 開頭的部分替換為該 user 的家目錄。

  在 Unix 上，如果環境變數 `HOME` 有被設置，則將初始的 `~` 替換為該變數的值；否則將使用內建模組 `pwd` 在密碼目錄中查找當前使用者的家目錄。對於初始的 `~user`，直接在密碼目錄中查找該使用者的家目錄。

  在 Windows 上，如果 `USERPROFILE` 有被設置，則使用該變數的值；否則將結合 `HOMEPATH` 和 `HOMEDRIVE`。對於初始的 `~user`，會檢查當前使用者的家目錄的最後一個目錄元件是否與 `USERNAME` 相符，如果相符則替換它。

  如果展開失敗或路徑不以波浪符號（tilde）開頭，則回傳原始路徑，不做任何變更。

  在 3.6 版的變更: 接受一個 path-like object。

  在 3.8 版的變更: 在 Windows 上不再使用 `HOME` 變數。

os.path.expandvars(path)

  输入带有环境变量的路径作为参数，返回展开变量以后的路径。`$name` 或 `${name}` 形式的子字符串被环境变量 name 的值替换。格式错误的变量名称和对不存在变量的引用保持不变。

  在 Windows 上，除了 `$name` 和 `${name}` 外，还可以展开 `%name%`。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.getatime(path)

  返回 path 的最后访问时间。返回值是一个浮点数，为纪元秒数（参见 `time` 模块）。如果该文件不存在或不可访问，则抛出 `OSError` 异常。

os.path.getmtime(path)

  返回 path 的最后修改时间。返回值是一个浮点数，为纪元秒数（参见 `time` 模块）。如果该文件不存在或不可访问，则抛出 `OSError` 异常。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.getctime(path)

  返回 path 在系统中的 ctime，在有些系统（比如 Unix）上，它是元数据的最后修改时间，其他系统（比如 Windows）上，它是 path 的创建时间。返回值是一个数，为纪元秒数（参见 `time` 模块）。如果该文件不存在或不可访问，则抛出 `OSError` 异常。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.getsize(path)

  返回 path 的大小，以字节为单位。如果该文件不存在或不可访问，则抛出 `OSError` 异常。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.isabs(path)

  如果 path 是一个绝对路径，则返回 `True`。在 Unix 上，它就是以斜杠开头，而在 Windows 上，它可以是去掉驱动器号后以斜杠（或反斜杠）开头。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.isfile(path)

  如果 path 是 `现有的` 常规文件，则返回 `True`。本方法会跟踪符号链接，因此，对于同一路径，`islink()` 和 `isfile()` 都可能为 `True`。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.isdir(path)

  如果 path 是 `现有的` 目录，则返回 `True`。本方法会跟踪符号链接，因此，对于同一路径，`islink()` 和 `isdir()` 都可能为 `True`。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.islink(path)

  如果 path 指向的 `现有` 目录条目是一个符号链接，则返回 `True`。如果 Python 运行时不支持符号链接，则总是返回 `False`。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.ismount(path)

  如果路径 path 是 挂载点 （文件系统中挂载其他文件系统的点），则返回 `True`。在 POSIX 上，该函数检查 path 的父目录 `path/..` 是否在与 path 不同的设备上，或者 `path/..` 和 path 是否指向同一设备上的同一 inode（这一检测挂载点的方法适用于所有 Unix 和 POSIX 变体）。本方法不能可靠地检测同一文件系统上的绑定挂载 (bind mount)。在 Windows 上，盘符和共享 UNC 始终是挂载点，对于任何其他路径，将调用 `GetVolumePathName` 来查看它是否与输入的路径不同。

  在 3.4 版新加入: 支持在 Windows 上检测非根挂载点。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.join(path, *paths)

  Join one or more path segments intelligently. The return value is the concatenation of path and all members of *paths, with exactly one directory separator following each non-empty part, except the last. That is, the result will only end in a separator if the last part is either empty or ends in a separator. If a segment is an absolute path (which on Windows requires both a drive and a root), then all previous segments are ignored and joining continues from the absolute path segment.

  On Windows, the drive is not reset when a rooted path segment (e.g., `r'\foo'`) is encountered. If a segment is on a different drive or is an absolute path, all previous segments are ignored and the drive is reset. Note that since there is a current directory for each drive, `os.path.join("c:", "foo")` represents a path relative to the current directory on drive `C:` (`c:foo`), not `c:\foo`.

  在 3.6 版的變更: 接受一个 类路径对象 用于 path 和 paths 。

os.path.normcase(path)

  规范路径的大小写。在 Windows 上，将路径中的所有字符都转换为小写，并将正斜杠转换为反斜杠。在其他操作系统上返回原路径。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.normpath(path)

  > 通过折叠多余的分隔符和对上级目录的引用来标准化路径名，所以 `A//B`、`A/B/`、`A/./B` 和 `A/foo/../B` 都会转换成 `A/B`。这个字符串操作可能会改变带有符号链接的路径的含义。在 Windows 上，本方法将正斜杠转换为反斜杠。要规范大小写，请使用 `normcase()`。

  備註

  > On POSIX systems, in accordance with IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution, if a pathname begins with exactly two slashes, the first component following the leading characters may be interpreted in an implementation-defined manner, although more than two leading characters shall be treated as a single character.

  在 3.6 版的變更: 接受一個 path-like object。

os.path.realpath(path, *, strict=False)

  返回指定文件的规范路径，消除路径中存在的任何符号链接（如果操作系统支持）。

  如果一个路径不存在或是遇到了符号链接循环，并且 strict 为 `True`，则会引发 `OSError`。 如果 strict 为 `False`，则会尽可能地解析路径并添加结果而不检查路径是否存在。

  備註

  这个函数会模拟操作系统生成规范路径的过程，Windows 与 UNIX 的这个过程在处理链接和后续路径组成部分的交互方式上有所差异。

  操作系统 API 会根据需要来规范化路径，因此通常不需要调用此函数。

  在 3.6 版的變更: 接受一個 path-like object。

  在 3.8 版的變更: 在 Windows 上现在可以正确解析符号链接和交接点 (junction point)。

  在 3.10 版的變更: 新增 strict 參數。

os.path.relpath(path, start=os.curdir)

  返回从当前目录或可选的 start 目录至 path 的相对文件路径。 这只是一个路径计算：不会访问文件系统来确认 path 或 start 是否存在或其性质。 在 Windows 上，当 path 和 start 位于不同驱动器时将引发 `ValueError`。

  start defaults to `os.curdir`.

  適用：Unix、Windows。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.samefile(path1, path2)

  如果两个路径都指向相同的文件或目录，则返回 `True`。这由设备号和 inode 号确定，在任一路径上调用 `os.stat()` 失败则抛出异常。

  適用：Unix、Windows。

  在 3.2 版的變更: 新增對 Windows 的支援。

  在 3.4 版的變更: Windows现在使用与其他所有平台相同的实现。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.sameopenfile(fp1, fp2)

  如果文件描述符 fp1 和 fp2 指向相同文件，则返回 `True`。

  適用：Unix、Windows。

  在 3.2 版的變更: 新增對 Windows 的支援。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.samestat(stat1, stat2)

  如果 stat 元组 stat1 和 stat2 指向相同文件，则返回 `True`。这些 stat 元组可能是由 `os.fstat()`、`os.lstat()` 或 `os.stat()` 返回的。本函数实现了 `samefile()` 和 `sameopenfile()` 底层所使用的比较过程。

  適用：Unix、Windows。

  在 3.4 版的變更: 新增對 Windows 的支援。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.split(path)

  将路径 path 拆分为一对，即 `(head, tail)`，其中，tail 是路径的最后一部分，而 head 里是除最后部分外的所有内容。tail 部分不会包含斜杠，如果 path 以斜杠结尾，则 tail 将为空。如果 path 中没有斜杠，head 将为空。如果 path 为空，则 head 和 tail 均为空。head 末尾的斜杠会被去掉，除非它是根目录（即它仅包含一个或多个斜杠）。在所有情况下，`join(head, tail)` 指向的位置都与 path 相同（但字符串可能不同）。另请参见函数 `dirname()` 和 `basename()`。

  在 3.6 版的變更: 接受一個 path-like object。

os.path.splitdrive(path)

  将路径 path 拆分为一对，即 `(drive, tail)`，其中 drive 是挂载点或空字符串。在没有驱动器概念的系统上，drive 将始终为空字符串。在所有情况下，`drive + tail` 都与 path 相同。

  在 Windows 上，本方法将路径拆分为驱动器/UNC 根节点和相对路径。

  如果路径 path 包含盘符，则 drive 将包含冒号之前的所有内容包括冒号本身:

      >>> splitdrive("c:/dir")
      ("c:", "/dir")

  如果路径 path 包含 UNC 路径，则 drive 将包含主机名和 share，直至第四个分隔符但不包括该分隔符:

      >>> splitdrive("//host/computer/dir")
      ("//host/computer", "/dir")

  在 3.6 版的變更: 接受一個 path-like object。

os.path.splitext(path)

  将路径名称 path 拆分为 `(root, ext)` 对使得 `root + ext == path`，并且扩展名 ext 为空或以句点打头并最多只包含一个句点。

  如果路径 path 不包含扩展名，则 ext 将为 `''`:

      >>> splitext('bar')
      ('bar', '')

  如果路径 path 包含扩展名，则 ext 将被设为该扩展名，包括打头的句点。 请注意在其之前的句点将被忽略:

      >>> splitext('foo.bar.exe')
      ('foo.bar', '.exe')
      >>> splitext('/foo/bar.exe')
      ('/foo/bar', '.exe')

  path 中最后一部分如果以点号开头则会被视为 root 的一部分:

      >>> splitext('.cshrc')
      ('.cshrc', '')
      >>> splitext('/foo/....jpg')
      ('/foo/....jpg', '')

  在 3.6 版的變更: 接受一個 path-like object。

os.path.supports_unicode_filenames

  如果（在文件系统限制下）允许将任意 Unicode 字符串用作文件名，则为 `True`。