pathlib —面向对象的文件系统路径

3.4 版的新Function。

源代码： Lib/pathlib.py

该模块提供了具有适用于不同 os 的语义的表示文件系统路径的类。路径类分为pure paths和concrete paths，它们分别提供纯计算操作而没有 I/O，而concrete paths从纯路径继承而来，但也提供 I/O 操作。

../_images/pathlib-inheritance.png

如果您以前从未使用过此模块，或者不确定不确定哪个类适合您的任务，则很可能需要Path。它为运行代码的平台实例化一个concrete path。

在某些特殊情况下，纯路径很有用。例如：

如果要在 Unix 计算机上操作 Windows 路径(反之亦然)。在 Unix 上运行时，不能实例化WindowsPath，但是可以实例化PureWindowsPath。
您要确保您的代码仅操纵路径而没有实际访问 os。在这种情况下，实例化纯类之一可能会很有用，因为它们根本没有任何 OS 访问操作。

Basic use

导入主类：

>>> from pathlib import Path

Listing subdirectories:

>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]

在此目录树中列出 Python 源文件：

>>> list(p.glob('**/*.py'))
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
 PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
 PosixPath('build/lib/pathlib.py')]

在目录树中导航：

>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')

查询路径属性：

>>> q.exists()
True
>>> q.is_dir()
False

打开文件：

>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'

Pure paths

纯路径对象提供了实际上不访问文件系统的路径处理操作。有三种访问这些类的方式，我们也将这些方式称为* flavors *：

类别 pathlib. PurePath(*路径段)
- 表示系统路径风格的通用类(实例化它会创建PurePosixPath或PureWindowsPath)：

>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')

pathsegments *的每个元素可以是代表路径段的字符串，实现返回字符串的os.PathLike接口的对象或另一个路径对象：

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

当* pathsegments *为空时，假定当前目录为：

>>> PurePath()
PurePosixPath('.')

当给出几个绝对路径时，最后一个被当作锚点(模仿os.path.join()的行为)：

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

但是，在 Windows 路径中，更改本地根目录不会放弃先前的驱动器设置：

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

虚斜线和单点折叠，但双点('..')没有折叠，因为这会改变符号链接中路径的含义：

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

(幼稚的方法会使PurePosixPath('foo/../bar')等效于PurePosixPath('bar')，如果foo是到另一个目录的符号链接，这是错误的)

纯路径对象实现os.PathLike接口，从而允许在接受该接口的任何地方使用它们。

在 3.6 版中进行了更改：添加了对os.PathLike界面的支持。

类别 pathlib. PurePosixPath(*路径段)
- PurePath的子类，此路径包含非 Windows 文件系统路径：

>>> PurePosixPath('/etc')
PurePosixPath('/etc')

pathsegments *的指定方式类似于PurePath。

类别 pathlib. PureWindowsPath(*路径段)
- PurePath的子类，此路径表示 Windows 文件系统路径：

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')

pathsegments *的指定方式类似于PurePath。

不管运行的系统是什么，都可以实例化所有这些类，因为它们不提供任何执行系统调用的操作。

General properties

路径是不可变且可哈希的。具有相同风味的路径是可比较且可排序的。这些属性遵循该风味的大小写折叠语义：

>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True

不同口味的路径比较不相等，无法排序：

>>> PureWindowsPath('foo') == PurePosixPath('foo')
False
>>> PureWindowsPath('foo') < PurePosixPath('foo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

Operators

斜杠运算符可帮助创建子路径，类似于os.path.join()：

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')

路径对象可以在接受实现os.PathLike的对象的任何地方使用：

>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'

路径的字符串表示形式是原始文件系统路径本身(本机格式，例如 Windows 下的反斜杠)，您可以将其传递给以文件路径为字符串的任何函数：

>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'

类似地，在路径上调用bytes会将原始文件系统路径作为字节对象，由os.fsencode()编码：

>>> bytes(p)
b'/etc'

Note

仅在 Unix 下建议调用bytes。在 Windows 下，unicode 形式是文件系统路径的规范表示。

访问各个部分

要访问路径的各个“部分”(组件)，请使用以下属性：

PurePath. parts
- 一个 Tuples，可以访问路径的各个组成部分：

>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')

(请注意如何将驱动器和本地根重组为单个部分)

方法和属性

纯路径提供以下方法和属性：

PurePath. drive
- 代表驱动器号或名称的字符串(如果有)：

>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
''
>>> PurePosixPath('/etc').drive
''

UNC 共享也被认为是驱动器：

>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'

PurePath. root
- 代表(本地或全局)根的字符串(如果有)：

>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
''
>>> PurePosixPath('/etc').root
'/'

UNC 共享始终具有根：

>>> PureWindowsPath('//host/share').root
'\\'

PurePath. anchor
- 驱动器和根目录的串联：

>>> PureWindowsPath('c:/Program Files/').anchor
'c:\\'
>>> PureWindowsPath('c:Program Files/').anchor
'c:'
>>> PurePosixPath('/etc').anchor
'/'
>>> PureWindowsPath('//host/share').anchor
'\\\\host\\share\\'

PurePath. parents
- 提供访问路径的逻辑祖先的不可变序列：

>>> p = PureWindowsPath('c:/foo/bar/setup.py')
>>> p.parents[0]
PureWindowsPath('c:/foo/bar')
>>> p.parents[1]
PureWindowsPath('c:/foo')
>>> p.parents[2]
PureWindowsPath('c:/')

PurePath. parent
- 路径的逻辑父级：

>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')

您不能越过锚点或空路径：

>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')

Note

这是纯粹的词汇操作，因此具有以下行为：

>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')

如果要向上走任意文件系统路径，建议先调用Path.resolve()以便解析符号链接并消除“ ..”组件。

PurePath. name
- 代表finally路径组件的字符串，不包括驱动器和根目录(如果有)：

>>> PurePosixPath('my/library/setup.py').name
'setup.py'

不考虑 UNC 驱动器名称：

>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
''

PurePath. suffix
- finally组件的文件 extensions(如果有)：

>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
''

PurePath. suffixes
- 路径的文件 extensions 列表：

>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]

PurePath. stem
- finally路径组件，不带后缀：

>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'

PurePath. as_posix ( )
- 返回带有正斜杠(/)的路径的字符串表示形式：

>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'

PurePath. as_uri ( )
- 将路径表示为file URI。如果路径不是绝对的，则引发ValueError。

>>> p = PurePosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = PureWindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

PurePath. is_absolute ( )
- 返回路径是否为绝对路径。如果路径既有根又有驱动器(如果允许的话)，则视为绝对路径：

>>> PurePosixPath('/a/b').is_absolute()
True
>>> PurePosixPath('a/b').is_absolute()
False

>>> PureWindowsPath('c:/a/b').is_absolute()
True
>>> PureWindowsPath('/a/b').is_absolute()
False
>>> PureWindowsPath('c:').is_absolute()
False
>>> PureWindowsPath('//some/share').is_absolute()
True

PurePath. is_reserved ( )
- 使用PureWindowsPath，如果该路径在 Windows 下被认为是保留的，则返回True，否则返回False。对于PurePosixPath，总是返回False。

>>> PureWindowsPath('nul').is_reserved()
True
>>> PurePosixPath('nul').is_reserved()
False

保留路径上的文件系统调用可能会神秘地失败或产生意想不到的影响。

PurePath. joinpath(** other *)
- 调用此方法等效于依次将路径与每个* other *参数组合在一起：

>>> PurePosixPath('/etc').joinpath('passwd')
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
PurePosixPath('/etc/init.d/apache2')
>>> PureWindowsPath('c:').joinpath('/Program Files')
PureWindowsPath('c:/Program Files')

PurePath. match(模式)
- 将此路径与提供的 glob 样式模式匹配。如果匹配成功，则返回True，否则返回False。

如果* pattern *是相对的，则路径可以是相对的或绝对的，并且从右侧进行匹配：

>>> PurePath('a/b.py').match('*.py')
True
>>> PurePath('/a/b/c.py').match('b/*.py')
True
>>> PurePath('/a/b/c.py').match('a/*.py')
False

如果* pattern *是绝对的，则路径必须是绝对的，并且整个路径必须匹配：

>>> PurePath('/a.py').match('/*.py')
True
>>> PurePath('a/b.py').match('/*.py')
False

与其他方法一样，区分大小写遵循平台默认值：

>>> PurePosixPath('b.py').match('*.PY')
False
>>> PureWindowsPath('b.py').match('*.PY')
True

PurePath. relative_to(** other *)
- 相对于* other *表示的路径，计算此路径的版本。如果不可能，则引发 ValueError：

>>> p = PurePosixPath('/etc/passwd')
>>> p.relative_to('/')
PurePosixPath('etc/passwd')
>>> p.relative_to('/etc')
PurePosixPath('passwd')
>>> p.relative_to('/usr')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 694, in relative_to
    .format(str(self), str(formatted)))
ValueError: '/etc/passwd' does not start with '/usr'

PurePath. with_name(* name *)
- 返回更改为name的新路径。如果原始路径没有名称，则会引发 ValueError：

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

PurePath. with_suffix(后缀)
- 返回更改为suffix的新路径。如果原始路径没有后缀，则会附加新的后缀。如果后缀为空字符串，则将删除原始后缀：

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_suffix('.bz2')
PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
>>> p = PureWindowsPath('README')
>>> p.with_suffix('.txt')
PureWindowsPath('README.txt')
>>> p = PureWindowsPath('README.txt')
>>> p.with_suffix('')
PureWindowsPath('README')

Concrete paths

具体路径是纯路径类的子类。除了后者提供的操作外，它们还提供对路径对象进行系统调用的方法。有三种方法可以实例化具体路径：

类别 pathlib. Path(*路径段)
- PurePath的子类，该类表示系统路径风格的具体路径(实例化它创建PosixPath或WindowsPath)：

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments *的指定方式类似于PurePath。

类别 pathlib. PosixPath(*路径段)
- Path和PurePosixPath的子类，该类表示具体的非 Windows 文件系统路径：

>>> PosixPath('/etc')
PosixPath('/etc')

pathsegments *的指定方式类似于PurePath。

类别 pathlib. WindowsPath(*路径段)
- Path和PureWindowsPath的子类，该类表示 Windows 文件系统的具体路径：

>>> WindowsPath('c:/Program Files/')
WindowsPath('c:/Program Files')

pathsegments *的指定方式类似于PurePath。

您只能实例化与您的系统相对应的类风味(允许系统调用不兼容的路径风味可能会导致应用程序中的错误或失败)：

>>> import os
>>> os.name
'posix'
>>> Path('setup.py')
PosixPath('setup.py')
>>> PosixPath('setup.py')
PosixPath('setup.py')
>>> WindowsPath('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 798, in __new__
    % (cls.__name__,))
NotImplementedError: cannot instantiate 'WindowsPath' on your system

Methods

除了纯路径方法外，具体路径还提供以下方法。如果系统调用失败(例如，因为路径不存在)，那么许多方法都可以引发OSError。

在 3.8 版中进行了更改：exists()，is_dir()，is_file()，is_mount()，is_symlink()，is_block_device()，is_char_device()，is_fifo()，is_socket()现在返回False，而不是为包含在 OS 级别无法表示的字符的路径引发异常。

分类方法 Path. cwd()
- 返回代表当前目录的新路径对象(由os.getcwd()返回)：

>>> Path.cwd()
PosixPath('/home/antoine/pathlib')

分类方法 Path. home()
- 返回一个表示用户主目录的新路径对象(由os.path.expanduser()使用~构造返回)：

>>> Path.home()
PosixPath('/home/antoine')

3.5 版中的新Function。

Path. stat ( )
- 返回包含有关此路径的信息的os.stat_result对象，例如os.stat()。在每次调用此方法时都会查询结果。

>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554

Path. chmod(模式)
- 更改文件模式和权限，例如os.chmod()：

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060

Path. exists ( )
- 路径是否指向现有文件或目录：

>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False

Note

如果路径指向符号链接，则exists()返回符号链接是否指向现有文件或目录。

Path. expanduser ( )
- 返回具有扩展的~和~user结构的新路径，如os.path.expanduser()返回：

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')

3.5 版中的新Function。

Path. glob(模式)
- 在此路径表示的目录中显示给定的相对* pattern *，产生所有匹配的文件(任何类型)：

>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]

“ **”模式表示“此目录和所有子目录(递归)”。换句话说，它启用了递归遍历：

>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

Note

在大型目录树中使用“ **”模式可能会花费过多时间。

Path. group ( )
- 返回拥有该文件的组的名称。如果在系统数据库中找不到文件的 gid，则引发KeyError。
Path. is_dir ( )
- 如果路径指向目录(或指向目录的符号链接)，则返回True；如果路径指向另一种文件，则返回False。