os.path
- 常见路径名操作¶
源代码: Lib/genericpath.py、Lib/posixpath.py(适用于 POSIX)和 Lib/ntpath.py(适用于 Windows)。
此模块实现了路径名上的一些有用函数。要读取或写入文件,请参阅 open()
,要访问文件系统,请参阅 os
模块。路径参数可以作为字符串、字节或任何实现 os.PathLike
协议的对象传递。
与 Unix shell 不同,Python 不会进行任何*自动*路径扩展。当应用程序需要类似 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 版更改: 接受 类路径对象。
- os.path.basename(path)¶
返回路径名 *path* 的基本名称。这是将 *path* 传递给函数
split()
返回的元组的第二个元素。请注意,此函数的结果与 Unix basename 程序不同;basename 对于'/foo/bar/'
返回'bar'
,而basename()
函数返回一个空字符串 (''
)。在 3.6 版更改: 接受 类路径对象。
- os.path.commonpath(paths)¶
返回序列 *paths* 中每个路径名的最长公共子路径。如果 *paths* 包含绝对路径名和相对路径名,则引发
ValueError
,如果 *paths* 位于不同的驱动器上或 *paths* 为空,则也会引发此异常。与commonprefix()
不同,这将返回一个有效的路径。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 版更改: 接受 类路径对象。
- os.path.exists(path)¶
如果 *path* 指的是现有路径或打开的文件描述符,则返回
True
。对于断开的符号链接,返回False
。在某些平台上,如果未授予对请求的文件执行os.stat()
的权限,则此函数可能会返回False
,即使 *path* 物理存在也是如此。3.3 版更改: path 现在可以是一个整数:如果是打开的文件描述符,则返回
True
,否则返回False
。在 3.6 版更改: 接受 类路径对象。
- os.path.lexists(path)¶
如果 path 指向一个现有的路径,包括断开的符号链接,则返回
True
。在缺少os.lstat()
的平台上,等效于exists()
。在 3.6 版更改: 接受 类路径对象。
- os.path.expanduser(path)¶
在 Unix 和 Windows 上,返回以
~
或~user
开头的参数,并将其替换为该 user 的家目录。在 Unix 上,如果设置了环境变量
HOME
,则初始的~
将被替换为该变量的值;否则,将通过内置模块pwd
在密码目录中查找当前用户的主目录。初始的~user
将直接在密码目录中查找。在 Windows 上,如果设置了
USERPROFILE
,则将使用该变量;否则,将使用HOMEPATH
和HOMEDRIVE
的组合。初始的~user
将通过检查当前用户主目录的最后一个目录组件是否与USERNAME
匹配来处理,如果匹配则替换。如果扩展失败,或者路径不是以波浪号开头,则路径将保持不变。
在 3.6 版更改: 接受 类路径对象。
3.8 版更改: 不再在 Windows 上使用
HOME
。
- os.path.expandvars(path)¶
返回展开环境变量后的参数。形式为
$name
或${name}
的子字符串将被环境变量 name 的值替换。格式错误的变量名和对不存在变量的引用将保持不变。在 Windows 上,除了
$name
和${name}
之外,还支持%name%
扩展。在 3.6 版更改: 接受 类路径对象。
- os.path.getmtime(path)¶
返回 path 上次修改的时间。返回值是一个浮点数,表示自纪元以来的秒数(请参阅
time
模块)。如果文件不存在或无法访问,则引发OSError
。在 3.6 版更改: 接受 类路径对象。
- os.path.getctime(path)¶
返回系统的 ctime,在某些系统(如 Unix)上,它是最后一次元数据更改的时间,而在其他系统(如 Windows)上,它是 path 的创建时间。返回值是一个数字,表示自纪元以来的秒数(请参阅
time
模块)。如果文件不存在或无法访问,则引发OSError
。在 3.6 版更改: 接受 类路径对象。
- os.path.isabs(path)¶
如果 path 是绝对路径名,则返回
True
。在 Unix 上,这意味着它以斜杠开头;在 Windows 上,这意味着它在删除可能的驱动器号后以(反)斜杠开头。在 3.6 版更改: 接受 类路径对象。
- os.path.isfile(path)¶
如果 path 是一个
现有
的常规文件,则返回True
。这将跟随符号链接,因此islink()
和isfile()
对于同一路径都可能为真。在 3.6 版更改: 接受 类路径对象。
- os.path.isdir(path)¶
如果 path 是一个
现有
的目录,则返回True
。这将跟随符号链接,因此islink()
和isdir()
对于同一路径都可能为真。在 3.6 版更改: 接受 类路径对象。
- os.path.isjunction(path)¶
如果 path 引用的是一个
已存在的
目录项,并且该目录项是一个连接点,则返回True
。如果当前平台不支持连接点,则始终返回False
。3.12 版本新增。
- os.path.islink(path)¶
如果 path 引用的是一个
已存在的
目录项,并且该目录项是一个符号链接,则返回True
。如果 Python 运行时不支持符号链接,则始终返回False
。在 3.6 版更改: 接受 类路径对象。
- os.path.ismount(path)¶
如果路径名 path 是一个挂载点(文件系统中已挂载不同文件系统的点),则返回
True
。在 POSIX 系统上,该函数会检查 path 的父目录path/..
是否与 path 位于不同的设备上,或者path/..
和 path 是否指向同一设备上的同一个 i-node,这应该可以检测所有 Unix 和 POSIX 变体的挂载点。它无法可靠地检测同一文件系统上的绑定挂载。在 Windows 上,驱动器盘符根目录和共享 UNC 路径始终是挂载点,对于任何其他路径,将调用GetVolumePathName
来查看它是否与输入路径不同。在 3.4 版本发生变化: 添加了对检测 Windows 上非根目录挂载点的支持。
在 3.6 版更改: 接受 类路径对象。
- os.path.isdevdrive(path)¶
如果路径名 path 位于 Windows 开发驱动器上,则返回
True
。开发驱动器针对开发人员场景进行了优化,可提供更快的文件读写性能。建议将其用于源代码、临时构建目录、包缓存和其他 I/O 密集型操作。对于无效路径(例如,没有可识别驱动器的路径),可能会引发错误,但在不支持开发驱动器的平台上返回
False
。有关启用和创建开发驱动器的信息,请参阅Windows 文档。可用性:Windows。
3.12 版本新增。
- os.path.join(path, *paths)¶
智能地连接一个或多个路径段。返回值是 path 和 *paths 所有成员的串联,每个非空部分后跟一个目录分隔符,最后一个部分除外。也就是说,只有当最后一部分为空或以分隔符结尾时,结果才会以分隔符结尾。如果某个段是绝对路径(在 Windows 上,这要求同时具有驱动器和根目录),则将忽略所有之前的段,并从该绝对路径段继续连接。
在 Windows 上,当遇到根路径段(例如,
r'\foo'
)时,不会重置驱动器。如果某个段位于不同的驱动器上或是一个绝对路径,则将忽略所有之前的段,并重置驱动器。请注意,由于每个驱动器都有一个当前目录,因此os.path.join("c:", "foo")
表示相对于驱动器C:
上当前目录的路径 (c:foo
),而不是c:\foo
。在 3.6 版本发生变化: 接受 path 和 paths 的类路径对象。
- os.path.normcase(path)¶
规范化路径名的大小写。在 Windows 上,将路径名中的所有字符转换为小写,并将正斜杠转换为反斜杠。在其他操作系统上,将原样返回路径。
在 3.6 版更改: 接受 类路径对象。
- os.path.normpath(path)¶
通过折叠冗余分隔符和上级引用来规范化路径名,以便
A//B
、A/B/
、A/./B
和A/foo/../B
都变为A/B
。此字符串操作可能会更改包含符号链接的路径的含义。在 Windows 上,它会将正斜杠转换为反斜杠。要规范化大小写,请使用normcase()
。注意
在 POSIX 系统上,根据 IEEE Std 1003.1 2013 版;4.13 路径名解析,如果路径名以两个斜杠开头,则开头字符后的第一个组件可以按实现定义的方式解释,但超过两个开头字符应视为单个字符。
在 3.6 版更改: 接受 类路径对象。
- os.path.realpath(path, *, strict=False)¶
返回指定文件名的规范路径,消除路径中遇到的任何符号链接(如果操作系统支持)。
如果路径不存在或遇到符号链接循环,并且 strict 为
True
,则会引发OSError
。如果 strict 为False
,则会尽可能解析路径,并在不检查是否存在的情况下追加任何剩余部分。注意
此函数模拟操作系统的路径规范化过程,该过程在 Windows 和 UNIX 之间略有不同,具体取决于链接和后续路径组件的交互方式。
操作系统 API 会根据需要将路径规范化,因此通常不需要调用此函数。
在 3.6 版更改: 接受 类路径对象。
在 3.8 版本发生变化: 现在可以在 Windows 上解析符号链接和连接点。
3.10 版更改: 添加了 strict 参数。
- os.path.relpath(path, start=os.curdir)¶
返回从当前目录或可选的 start 目录到 path 的相对文件路径。这是一个路径计算:不访问文件系统以确认 path 或 start 的存在或性质。在 Windows 上,当 path 和 start 位于不同的驱动器上时,会引发
ValueError
。start 默认为
os.curdir
。在 3.6 版更改: 接受 类路径对象。
- os.path.samefile(path1, path2)¶
如果两个路径名参数都指向同一个文件或目录,则返回
True
。这由设备号和 i-node 号确定,如果对任一路径名的os.stat()
调用失败,则会引发异常。3.2 版更改: 添加了 Windows 支持。
3.4 版更改: Windows 现在使用与所有其他平台相同的实现。
在 3.6 版更改: 接受 类路径对象。
- os.path.sameopenfile(fp1, fp2)¶
如果文件描述符 fp1 和 fp2 指向同一个文件,则返回
True
。3.2 版更改: 添加了 Windows 支持。
在 3.6 版更改: 接受 类路径对象。
- os.path.samestat(stat1, stat2)¶
如果 stat 元组 stat1 和 stat2 指向同一个文件,则返回
True
。这些结构可能已由os.fstat()
、os.lstat()
或os.stat()
返回。此函数实现了samefile()
和sameopenfile()
使用的底层比较。3.4 版更改: 添加了 Windows 支持。
在 3.6 版更改: 接受 类路径对象。
- 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 版更改: 接受 类路径对象。
- os.path.splitdrive(path)¶
将路径名 path 拆分为一对
(drive, tail)
,其中 drive 是挂载点或空字符串。在不使用驱动器规范的系统上,drive 将始终为空字符串。在所有情况下,drive + tail
将与 path 相同。在 Windows 上,将路径名拆分为驱动器/UNC 共享点和相对路径。
如果路径包含驱动器号,则 drive 将包含直到并包括冒号的所有内容
>>> splitdrive("c:/dir") ("c:", "/dir")
如果路径包含 UNC 路径,则 drive 将包含主机名和共享名
>>> splitdrive("//host/computer/dir") ("//host/computer", "/dir")
在 3.6 版更改: 接受 类路径对象。
- os.path.splitroot(path)¶
将路径名 path 拆分为一个包含 3 个项目的元组
(drive, root, tail)
,其中 drive 是设备名称或挂载点,root 是驱动器后的分隔符字符串,tail 是根目录后的所有内容。这些项目中的任何一个都可能是空字符串。在所有情况下,drive + root + tail
将与 path 相同。在 POSIX 系统上,drive 始终为空。root 可以为空(如果 path 是相对路径)、单个正斜杠(如果 path 是绝对路径)或两个正斜杠(根据 IEEE Std 1003.1-2017; 4.13 路径名解析 定义的实现。)例如
>>> splitroot('/home/sam') ('', '/', 'home/sam') >>> splitroot('//home/sam') ('', '//', 'home/sam') >>> splitroot('///home/sam') ('', '/', '//home/sam')
在 Windows 上,drive 可以为空、驱动器号、UNC 共享或设备名称。root 可以为空、正斜杠或反斜杠。例如
>>> splitroot('C:/Users/Sam') ('C:', '/', 'Users/Sam') >>> splitroot('//Server/Share/Users/Sam') ('//Server/Share', '/', 'Users/Sam')
3.12 版本新增。
- os.path.splitext(path)¶
将路径名 path 拆分为一对
(root, ext)
,以便root + ext == path
,并且扩展名 ext 为空或以句点开头,并且最多包含一个句点。如果路径不包含扩展名,则 ext 将为
''
>>> splitext('bar') ('bar', '')
如果路径包含扩展名,则 ext 将设置为该扩展名,包括前导句点。请注意,之前的句点将被忽略
>>> splitext('foo.bar.exe') ('foo.bar', '.exe') >>> splitext('/foo/bar.exe') ('/foo/bar', '.exe')
路径最后一个组件的前导句点被视为 root 的一部分
>>> splitext('.cshrc') ('.cshrc', '') >>> splitext('/foo/....jpg') ('/foo/....jpg', '')
在 3.6 版更改: 接受 类路径对象。
- os.path.supports_unicode_filenames¶
如果可以使用任意 Unicode 字符串作为文件名(在文件系统施加的限制内),则为
True
。