pathlib — 面向物件的⽂件系統路徑

3.4 版本新增。

原始碼: Lib/pathlib/

---

此模組提供了表示檔案系統路徑的類，這些類具有適用於不同作業系統的語義。路徑類分為純路徑（提供純計算操作，不涉及 I/O）和具體路徑（繼承自純路徑，但也提供 I/O 操作）。

如果您以前從未使用過此模組，或者不確定哪個類適合您的任務，那麼 Path 很可能是您所需要的。它會為程式碼執行的平臺例項化一個具體路徑。

純路徑在某些特殊情況下很有用；例如

1. 如果您想在 Unix 機器上操作 Windows 路徑（或反之亦然）。在 Unix 上執行時，您無法例項化 WindowsPath，但可以例項化 PureWindowsPath。

2. 您想確保您的程式碼僅操作路徑，而不實際訪問作業系統。在這種情況下，例項化純類之一可能很有用，因為這些類根本沒有任何作業系統訪問操作。

另請參閱

PEP 428： pathlib 模組 – 面向物件的⽂件系統路徑。

另請參閱

對於字串上的底層路徑操作，您還可以使用 os.path 模組。

基本用法

匯入主類

>>> from pathlib import Path

列出子目錄

>>> 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'

異常

exception pathlib.UnsupportedOperation

當在路徑物件上呼叫不支援的操作時，引發的繼承 NotImplementedError 的異常。

3.13 版本新增。

純路徑

純路徑物件提供路徑處理操作，而這些操作實際上不會訪問檔案系統。有三種方式可以訪問這些類，我們也將它們稱為風味

class pathlib.PurePath(*pathsegments)

一個通用類，表示系統的路徑風味（例項化它會建立一個 PurePosixPath 或一個 PureWindowsPath）

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

pathsegments 的每個元素都可以是表示路徑段的字串，或實現 os.PathLike 介面的物件，其中 __fspath__() 方法返回字串，例如另一個路徑物件

>>> 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 上，當遇到根相對路徑段（例如，r'\foo'）時，不會重置驅動器

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

多餘的斜槓和單點會被摺疊，但雙點 ('..') 和前導雙斜槓 ('//') 則不會，因為這會由於各種原因（例如，符號連結、UNC 路徑）而改變路徑的含義

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> 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 介面的支援。

class pathlib.PurePosixPath(*pathsegments)

作為 PurePath 的子類，此路徑風味表示非 Windows 檔案系統路徑

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

pathsegments 的指定方式類似於 PurePath。

class pathlib.PureWindowsPath(*pathsegments)

作為 PurePath 的子類，此路徑風味表示 Windows 檔案系統路徑，包括 UNC 路徑

>>> PureWindowsPath('c:/', 'Users', 'Ximénez')
PureWindowsPath('c:/Users/Ximénez')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

pathsegments 的指定方式類似於 PurePath。

無論您在哪個系統上執行，都可以例項化所有這些類，因為它們不提供任何執行系統呼叫的操作。

通用屬性

路徑是不可變的和可雜湊的。相同風味的路徑是可比較和可排序的。這些屬性尊重風味的大小寫摺疊語義

>>> 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'

運算子

斜槓運算子有助於建立子路徑，如 os.path.join()。如果引數是絕對路徑，則忽略先前的路徑。在 Windows 上，當引數是根相對路徑時（例如，r'\foo'），不會重置驅動器

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')
>>> p / '/an_absolute_path'
PurePosixPath('/an_absolute_path')
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

路徑物件可以在任何接受實現 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'

注意

僅建議在 Unix 下呼叫 bytes。在 Windows 下，Unicode 形式是檔案系統路徑的規範表示形式。

訪問各個部分

要訪問路徑的各個“部分”（元件），請使用以下屬性

PurePath.parts

一個元組，用於訪問路徑的各個元件

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

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

（注意驅動器和本地根目錄是如何在一個部分中重新組合的）

方法和屬性

純路徑提供以下方法和屬性

PurePath.parser

用於底層路徑解析和連線的 os.path 模組的實現：要麼是 posixpath，要麼是 ntpath。

3.13 版本新增。

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
'\\'

如果路徑以兩個以上的連續斜槓開頭，則 PurePosixPath 會將其摺疊起來

>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'

注意

此行為符合*The Open Group Base Specifications Issue 6*，段落 4.11 路徑名解析

“以兩個連續斜槓開頭的路徑名可以以實現定義的方式解釋，儘管兩個以上的開頭斜槓應被視為單個斜槓。”

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:/')

在 3.10 版本中更改: 父序列現在支援 切片 和負索引值。

PurePath.parent

路徑的邏輯父級

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

您不能超過錨點或空路徑

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

注意

這是一個純粹的詞法操作，因此有以下行為

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

如果您想向上遍歷任意檔案系統路徑，建議首先呼叫 Path.resolve() 以解析符號連結並消除 ".." 元件。

PurePath.name

一個字串，表示最終路徑元件，不包括驅動器和根目錄（如果有）

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

不考慮 UNC 驅動器名稱

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

PurePath.suffix

最終元件的最後一個以點分隔的部分（如果有）

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

這通常稱為副檔名。

PurePath.suffixes

路徑的字尾列表，通常稱為副檔名

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

PurePath.stem

最終路徑元件，不帶其後綴

>>> 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.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_relative_to(other)

返回此路徑是否相對於 *other* 路徑。

>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False

此方法基於字串；它既不訪問檔案系統，也不特別處理“..”段。以下程式碼等效

>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False

在 3.9 版本中新增。

自 3.12 版本起棄用，將在 3.14 版本中刪除: 傳遞附加引數已棄用；如果提供，它們將與 *other* 連線。

PurePath.is_reserved()

使用 PureWindowsPath，如果路徑在 Windows 下被認為是保留的，則返回 True，否則返回 False。使用 PurePosixPath，始終返回 False。

在 3.13 版本中更改: 包含冒號或以點或空格結尾的 Windows 路徑名被認為是保留的。UNC 路徑可能是保留的。

自 3.13 版本起棄用，將在 3.15 版本中刪除: 此方法已棄用；使用 os.path.isreserved() 檢測 Windows 上保留的路徑。

PurePath.joinpath(*pathsegments)

呼叫此方法等效於依次將路徑與給定的每個 *pathsegments* 組合

>>> 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.full_match(pattern, *, case_sensitive=None)

將此路徑與提供的 glob 樣式模式進行匹配。如果匹配成功，則返回 True，否則返回 False。例如

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

另請參閱

模式語言 文件。

與其他方法一樣，大小寫敏感性遵循平臺預設值

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

將 *case_sensitive* 設定為 True 或 False 以覆蓋此行為。

3.13 版本新增。

PurePath.match(pattern, *, case_sensitive=None)

將此路徑與提供的非遞迴 glob 風格模式進行匹配。如果匹配成功，則返回 True，否則返回 False。

此方法類似於 full_match()，但不允許使用空模式（會引發 ValueError），不支援遞迴萬用字元“**”（它的作用類似於非遞迴的“*”），並且如果提供了相對模式，則匹配將從右側開始。

>>> 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

在 3.12 版本中變更: pattern 引數接受一個 路徑類物件。

在 3.12 版本中變更: 添加了 case_sensitive 引數。

PurePath.relative_to(other, walk_up=False)

計算此路徑相對於 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 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other is absolute.

當 walk_up 為 false（預設值）時，路徑必須以 other 開頭。當此引數為 true 時，可以新增 .. 條目以形成相對路徑。在所有其他情況下，例如路徑引用不同的驅動器，則會引發 ValueError。

>>> p.relative_to('/usr', walk_up=True)
PurePosixPath('../etc/passwd')
>>> p.relative_to('foo', walk_up=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not on the same drive as 'foo' OR one path is relative and the other is absolute.

警告

此函式是 PurePath 的一部分，並且可以處理字串。它不會檢查或訪問底層檔案結構。這會影響 walk_up 選項，因為它假設路徑中不存在符號連結；如有必要，請先呼叫 resolve() 來解析符號連結。

在 3.12 版本中變更: 添加了 walk_up 引數（舊行為與 walk_up=False 相同）。

自 3.12 版本起棄用，將在 3.14 版本中移除: 傳遞額外的 positional 引數已棄用；如果提供，它們將與 other 連線。

PurePath.with_name(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_stem(stem)

返回一個 stem 已更改的新路徑。如果原始路徑沒有 name，則會引發 ValueError。

>>> p = PureWindowsPath('c:/Downloads/draft.txt')
>>> p.with_stem('final')
PureWindowsPath('c:/Downloads/final.txt')
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_stem('lib')
PureWindowsPath('c:/Downloads/lib.gz')
>>> p = PureWindowsPath('c:/')
>>> p.with_stem('')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
    return self.with_name(stem + self.suffix)
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

在 3.9 版本中新增。

PurePath.with_suffix(suffix)

返回一個 suffix 已更改的新路徑。如果原始路徑沒有後綴，則會追加新的 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')

PurePath.with_segments(*pathsegments)

透過組合給定的 pathsegments 建立相同型別的新路徑物件。每當建立派生路徑時，都會呼叫此方法，例如從 parent 和 relative_to()。子類可以重寫此方法以將資訊傳遞給派生路徑，例如

from pathlib import PurePosixPath

class MyPath(PurePosixPath):
    def __init__(self, *pathsegments, session_id):
        super().__init__(*pathsegments)
        self.session_id = session_id

    def with_segments(self, *pathsegments):
        return type(self)(*pathsegments, session_id=self.session_id)

etc = MyPath('/etc', session_id=42)
hosts = etc / 'hosts'
print(hosts.session_id)  # 42

在 3.12 版本中新增。

具體路徑

具體路徑是純路徑類的子類。除了後者提供的操作外，它們還提供了對路徑物件執行系統呼叫的方法。例項化具體路徑有三種方法：

class pathlib.Path(*pathsegments)

作為 PurePath 的子類，此類表示系統路徑風格的具體路徑（例項化它會建立一個 PosixPath 或 WindowsPath）。

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

pathsegments 的指定方式類似於 PurePath。

class pathlib.PosixPath(*pathsegments)

作為 Path 和 PurePosixPath 的子類，此類表示具體的非 Windows 檔案系統路徑。

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

pathsegments 的指定方式類似於 PurePath。

在 3.13 版本中變更: 在 Windows 上引發 UnsupportedOperation。在以前的版本中，則會引發 NotImplementedError。

class pathlib.WindowsPath(*pathsegments)

作為 Path 和 PureWindowsPath 的子類，此類表示具體的 Windows 檔案系統路徑。

>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')

pathsegments 的指定方式類似於 PurePath。

在 3.13 版本中變更: 在非 Windows 平臺上引發 UnsupportedOperation。在以前的版本中，則會引發 NotImplementedError。

您只能例項化與您的系統對應的類風格（允許對不相容的路徑風格進行系統呼叫可能會導致應用程式中出現錯誤或失敗）。

>>> 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__,))
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system

如果系統呼叫失敗（例如，因為路徑不存在），一些具體路徑方法可能會引發 OSError。

解析和生成 URI

具體路徑物件可以從符合 RFC 8089 的“檔案”URI 建立，並表示為“檔案”URI。

注意

檔案 URI 在具有不同 檔案系統編碼 的機器之間不可移植。

classmethod Path.from_uri(uri)

從解析“檔案”URI 返回一個新的路徑物件。例如

>>> p = Path.from_uri('file:///etc/hosts')
PosixPath('/etc/hosts')

在 Windows 上，可以從 URI 解析 DOS 裝置和 UNC 路徑。

>>> p = Path.from_uri('file:///c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file://server/share')
WindowsPath('//server/share')

支援幾種變體形式。

>>> p = Path.from_uri('file:////server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file://///server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file:c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file:/c|/windows')
WindowsPath('c:/windows')

如果 URI 不是以 file: 開頭，或者解析的路徑不是絕對路徑，則會引發 ValueError。

3.13 版本新增。

Path.as_uri()

將路徑表示為“檔案”URI。如果路徑不是絕對路徑，則會引發 ValueError。

>>> p = PosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = WindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

出於歷史原因，此方法也可從 PurePath 物件訪問。但是，它對 os.fsencode() 的使用使其成為嚴格意義上的不純方法。

展開和解析路徑

classmethod Path.home()

返回一個新的路徑物件，表示使用者的主目錄（由 os.path.expanduser() 使用 ~ 構造返回）。如果無法解析主目錄，則會引發 RuntimeError。

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

3.5 版本新增。

Path.expanduser()

返回一個新的路徑，其中 ~ 和 ~user 構造已展開，由 os.path.expanduser() 返回。如果無法解析主目錄，則會引發 RuntimeError。

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

3.5 版本新增。

classmethod Path.cwd()

返回一個新的路徑物件，表示當前目錄（由 os.getcwd() 返回）

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

Path.absolute()

使路徑成為絕對路徑，不進行規範化或解析符號連結。返回一個新的路徑物件

>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')

Path.resolve(strict=False)

使路徑成為絕對路徑，並解析所有符號連結。返回一個新的路徑物件

>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')

“..” 元件也會被消除（這是唯一執行此操作的方法）

>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')

如果路徑不存在或遇到符號連結迴圈，並且 strict 為 True，則會引發 OSError。如果 strict 為 False，則會盡可能解析路徑，並將任何剩餘部分附加到路徑末尾，而不檢查其是否存在。

在 3.6 版本中更改: 添加了 strict 引數（3.6 之前的行為是嚴格的）。

在 3.13 版本中更改: 符號連結迴圈被視為其他錯誤：在嚴格模式下會引發 OSError，而在非嚴格模式下不會引發異常。在之前的版本中，無論 strict 的值如何，都會引發 RuntimeError。

Path.readlink()

返回符號連結指向的路徑（由 os.readlink() 返回）

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')

在 3.9 版本中新增。

在 3.13 版本中更改: 如果 os.readlink() 不可用，則引發 UnsupportedOperation。在之前的版本中，會引發 NotImplementedError。

查詢檔案型別和狀態

在 3.8 版本中更改: exists()、is_dir()、is_file()、is_mount()、is_symlink()、is_block_device()、is_char_device()、is_fifo()、is_socket() 現在對於包含在作業系統級別無法表示的字元的路徑，返回 False 而不是引發異常。

Path.stat(*, follow_symlinks=True)

返回一個 os.stat_result 物件，其中包含有關此路徑的資訊，例如 os.stat()。每次呼叫此方法時都會查詢結果。

此方法通常會跟隨符號連結；要統計符號連結，請新增引數 follow_symlinks=False，或使用 lstat()。

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

在 3.10 版本中更改: 添加了 follow_symlinks 引數。

Path.lstat()

類似於 Path.stat()，但如果路徑指向符號連結，則返回符號連結的資訊，而不是其目標的資訊。

Path.exists(*, follow_symlinks=True)

如果路徑指向現有檔案或目錄，則返回 True。

此方法通常會跟隨符號連結；要檢查符號連結是否存在，請新增引數 follow_symlinks=False。

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

在 3.12 版本中更改: 添加了 follow_symlinks 引數。

Path.is_file(*, follow_symlinks=True)

如果路徑指向常規檔案，則返回 True，如果路徑指向另一種型別的檔案，則返回 False。

如果路徑不存在或是斷開的符號連結，也會返回 False；其他錯誤（例如許可權錯誤）會傳播。

此方法通常會跟隨符號連結；要排除符號連結，請新增引數 follow_symlinks=False。

在 3.13 版本中更改: 添加了 follow_symlinks 引數。

Path.is_dir(*, follow_symlinks=True)

如果路徑指向目錄，則返回 True，如果路徑指向另一種型別的檔案，則返回 False。

如果路徑不存在或是斷開的符號連結，也會返回 False；其他錯誤（例如許可權錯誤）會傳播。

此方法通常會跟隨符號連結；要排除指向目錄的符號連結，請新增引數 follow_symlinks=False。

在 3.13 版本中更改: 添加了 follow_symlinks 引數。

Path.is_symlink()

如果路徑指向符號連結，則返回 True，否則返回 False。

如果路徑不存在，也會返回 False；其他錯誤（例如許可權錯誤）會傳播。

Path.is_junction()

如果路徑指向連線點，則返回 True，對於任何其他型別的檔案，則返回 False。目前只有 Windows 支援連線點。

在 3.12 版本中新增。

Path.is_mount()

如果路徑是掛載點，則返回 True：檔案系統中掛載了不同檔案系統的點。在 POSIX 系統上，此函式檢查 *path* 的父目錄，即 path/..，是否與 *path* 位於不同的裝置上，或者 path/.. 和 *path* 是否指向同一裝置上的相同 i-node——這應該可以檢測所有 Unix 和 POSIX 變體的掛載點。在 Windows 系統上，掛載點被視為驅動器磁碟機代號根目錄（例如 c:\）、UNC 共享（例如 \\server\share）或已掛載的檔案系統目錄。

在 3.7 版本中新增。

在 3.12 版本中更改: 添加了 Windows 支援。

Path.is_socket()

如果路徑指向 Unix 套接字（或指向 Unix 套接字的符號連結），則返回 True，如果指向其他型別的檔案，則返回 False。

如果路徑不存在或是斷開的符號連結，也會返回 False；其他錯誤（例如許可權錯誤）會傳播。

Path.is_fifo()

如果路徑指向 FIFO（或指向 FIFO 的符號連結），則返回 True，如果指向其他型別的檔案，則返回 False。

如果路徑不存在或是斷開的符號連結，也會返回 False；其他錯誤（例如許可權錯誤）會傳播。

Path.is_block_device()

如果路徑指向塊裝置（或指向塊裝置的符號連結），則返回 True，如果指向其他型別的檔案，則返回 False。

如果路徑不存在或是斷開的符號連結，也會返回 False；其他錯誤（例如許可權錯誤）會傳播。

Path.is_char_device()

如果路徑指向字元裝置（或指向字元裝置的符號連結），則返回 True，如果指向其他型別的檔案，則返回 False。

如果路徑不存在或是斷開的符號連結，也會返回 False；其他錯誤（例如許可權錯誤）會傳播。

Path.samefile(other_path)

返回此路徑是否指向與 *other_path* 相同的檔案，其中 *other_path* 可以是 Path 物件或字串。語義類似於 os.path.samefile() 和 os.path.samestat()。

如果由於某種原因無法訪問任何檔案，則可能引發 OSError。

>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True

3.5 版本新增。

讀取和寫入檔案

Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)

開啟路徑指向的檔案，就像內建的 open() 函式一樣

>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'

Path.read_text(encoding=None, errors=None, newline=None)

返回指向檔案的解碼內容，作為字串

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

檔案被開啟，然後關閉。可選引數的含義與 open() 中的相同。

3.5 版本新增。

在 3.13 版本中更改: 添加了 *newline* 引數。

Path.read_bytes()

返回指向檔案的二進位制內容，作為位元組物件

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

3.5 版本新增。

Path.write_text(data, encoding=None, errors=None, newline=None)

以文字模式開啟指向的檔案，將 *data* 寫入其中，然後關閉該檔案

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

將覆蓋同名的現有檔案。可選引數的含義與 open() 中的相同。

3.5 版本新增。

在 3.10 版本中更改: 添加了 *newline* 引數。

Path.write_bytes(data)

以位元組模式開啟指向的檔案，將 *data* 寫入其中，然後關閉該檔案

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

將覆蓋同名的現有檔案。

3.5 版本新增。

讀取目錄

Path.iterdir()

當路徑指向目錄時，生成目錄內容的路徑物件

>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')

子項以任意順序生成，並且不包括特殊條目 '.' 和 '..'。如果在建立迭代器後從目錄中刪除或新增檔案，則未指定是否包含該檔案的路徑物件。

如果路徑不是目錄或無法訪問，則會引發 OSError。

Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False)

在由此路徑表示的目錄中，使用給定的相對 *pattern* 進行 glob 匹配，生成所有匹配的檔案（任何型別的）

>>> 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')]

另請參閱

模式語言 文件。

預設情況下，或者當僅關鍵字引數 *case_sensitive* 設定為 None 時，此方法使用平臺特定的區分大小寫規則匹配路徑：通常在 POSIX 上區分大小寫，在 Windows 上不區分大小寫。將 *case_sensitive* 設定為 True 或 False 可覆蓋此行為。

預設情況下，或者當僅關鍵字引數 *recurse_symlinks* 設定為 False 時，此方法遵循符號連結，但在展開“**”萬用字元時除外。將 *recurse_symlinks* 設定為 True 可始終遵循符號連結。

使用引數 self、pattern 引發 稽核事件 pathlib.Path.glob。

在 3.12 版本中變更: 添加了 case_sensitive 引數。

在 3.13 版本中更改: 添加了 *recurse_symlinks* 引數。

在 3.13 版本中更改: *pattern* 引數接受 類路徑物件。

在 3.13 版本中變更: 掃描檔案系統時引發的任何 OSError 異常都會被抑制。在之前的版本中，此類異常在許多情況下會被抑制，但並非所有情況都如此。

Path.rglob(pattern, *, case_sensitive=None, recurse_symlinks=False)

遞迴地匹配給定的相對 pattern 模式。 這類似於呼叫 Path.glob() 並在 pattern 前面新增 “**/”。

另請參閱

模式語言 和 Path.glob() 文件。

引發一個帶有引數 self, pattern 的 審計事件 pathlib.Path.rglob。

在 3.12 版本中變更: 添加了 case_sensitive 引數。

在 3.13 版本中更改: 添加了 *recurse_symlinks* 引數。

在 3.13 版本中更改: *pattern* 引數接受 類路徑物件。

Path.walk(top_down=True, on_error=None, follow_symlinks=False)

透過自頂向下或自底向上遍歷目錄樹，生成目錄樹中的檔名。

對於以 self 為根的目錄樹中的每個目錄（包括 self 但不包括 ‘.’ 和 ‘..’），該方法會生成一個 3 元組 (dirpath, dirnames, filenames)。

dirpath 是指向當前正在遍歷的目錄的 Path， dirnames 是 dirpath 中子目錄名稱的字串列表（不包括 '.' 和 '..'），而 filenames 是 dirpath 中非目錄檔案的名稱的字串列表。要獲取 dirpath 中檔案或目錄的完整路徑（以 self 開頭），請執行 dirpath / name。列表是否排序取決於檔案系統。

如果可選引數 top_down 為 true（預設值），則在生成任何子目錄的三元組之前，會先生成目錄的三元組（目錄會自頂向下遍歷）。 如果 top_down 為 false，則會在生成所有子目錄的三元組之後生成目錄的三元組（目錄會自底向上遍歷）。 無論 top_down 的值如何，都會在遍歷目錄及其子目錄的三元組之前檢索子目錄的列表。

當 top_down 為 true 時，呼叫者可以就地修改 dirnames 列表（例如，使用 del 或切片賦值），並且 Path.walk() 只會遞迴進入 dirnames 中保留名稱的子目錄。 這可用於修剪搜尋範圍、強制執行特定的訪問順序，甚至可以通知 Path.walk() 呼叫者在它再次恢復 Path.walk() 之前建立或重新命名的目錄。當 top_down 為 false 時修改 dirnames 對 Path.walk() 的行為沒有影響，因為 dirnames 中的目錄在 dirnames 被返回給呼叫者時已經生成。

預設情況下，來自 os.scandir() 的錯誤會被忽略。 如果指定了可選引數 on_error，則它應該是一個可呼叫物件； 它將使用一個引數（OSError 例項）進行呼叫。 該可呼叫物件可以處理錯誤以繼續遍歷或重新引發錯誤以停止遍歷。 請注意，檔名可用作異常物件的 filename 屬性。

預設情況下，Path.walk() 不會跟隨符號連結，而是將其新增到 filenames 列表中。 將 follow_symlinks 設定為 true 以解析符號連結並將它們放在 dirnames 和 filenames 中，使其與其目標相適應，並因此訪問符號連結指向的目錄（如果支援）。

注意

請注意，如果連結指向其自身的父目錄，則將 follow_symlinks 設定為 true 可能會導致無限遞迴。 Path.walk() 不會跟蹤它已訪問過的目錄。

注意

Path.walk() 假設它遍歷的目錄在執行期間不會被修改。 例如，如果 dirnames 中的一個目錄已被符號連結替換並且 follow_symlinks 為 false，則 Path.walk() 仍將嘗試進入該目錄。 要防止此類行為，請根據需要從 dirnames 中刪除目錄。

注意

與 os.walk() 不同，如果 follow_symlinks 為 false，則 Path.walk() 會在 filenames 中列出指向目錄的符號連結。

以下示例顯示每個目錄中所有檔案使用的位元組數，同時忽略 __pycache__ 目錄

from pathlib import Path
for root, dirs, files in Path("cpython/Lib/concurrent").walk(on_error=print):
  print(
      root,
      "consumes",
      sum((root / file).stat().st_size for file in files),
      "bytes in",
      len(files),
      "non-directory files"
  )
  if '__pycache__' in dirs:
        dirs.remove('__pycache__')

下一個示例是 shutil.rmtree() 的簡單實現。 自底向上遍歷樹至關重要，因為 rmdir() 不允許在目錄為空之前刪除目錄

# Delete everything reachable from the directory "top".
# CAUTION:  This is dangerous! For example, if top == Path('/'),
# it could delete all of your files.
for root, dirs, files in top.walk(top_down=False):
    for name in files:
        (root / name).unlink()
    for name in dirs:
        (root / name).rmdir()

在 3.12 版本中新增。

建立檔案和目錄

Path.touch(mode=0o666, exist_ok=True)

在此給定路徑下建立一個檔案。 如果給定了 mode，它會與程序的 umask 值組合，以確定檔案模式和訪問標誌。 如果檔案已存在，當 exist_ok 為 true 時，該函式會成功（並且其修改時間會更新為當前時間），否則會引發 FileExistsError。

另請參閱

open()、write_text() 和 write_bytes() 方法通常用於建立檔案。

Path.mkdir(mode=0o777, parents=False, exist_ok=False)

在此給定路徑下建立一個新目錄。 如果給定了 mode，它會與程序的 umask 值組合，以確定檔案模式和訪問標誌。 如果路徑已存在，則會引發 FileExistsError。

如果 parents 為 true，則會根據需要建立此路徑的任何缺失的父級； 它們會使用預設許可權建立，而不考慮 mode（模擬 POSIX mkdir -p 命令）。

如果 parents 為 false（預設值），則缺失的父級會引發 FileNotFoundError。

如果 exist_ok 為 false (預設值)，如果目標目錄已存在，則會引發 FileExistsError 異常。

如果 exist_ok 為 true，則不會引發 FileExistsError 異常，除非給定的路徑在檔案系統中已存在且不是目錄（行為與 POSIX mkdir -p 命令相同）。

在 3.5 版本中更改: 添加了 exist_ok 引數。

Path.symlink_to(target, target_is_directory=False)

將此路徑建立為指向 target 的符號連結。

在 Windows 上，符號連結表示檔案或目錄，不會動態更改為目標。如果目標存在，則將建立與目標型別匹配的符號連結。否則，如果 target_is_directory 為 true，則符號連結將被建立為目錄，否則（預設）建立為檔案符號連結。在非 Windows 平臺上，target_is_directory 會被忽略。

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
>>> p.stat().st_size
956
>>> p.lstat().st_size
8

注意

引數的順序（連結，目標）與 os.symlink() 的順序相反。

在 3.13 版本中更改: 如果 os.symlink() 不可用，則引發 UnsupportedOperation。在之前的版本中，會引發 NotImplementedError。

Path.hardlink_to(target)

將此路徑建立為與 target 檔案相同的硬連結。

注意

引數的順序（連結，目標）與 os.link() 的順序相反。

在 3.10 版本中新增。

在 3.13 版本中更改: 如果 os.link() 不可用，則引發 UnsupportedOperation。在之前的版本中，會引發 NotImplementedError。

重新命名和刪除

Path.rename(target)

將此檔案或目錄重新命名為給定的 target，並返回指向 target 的新的 Path 例項。在 Unix 上，如果 target 存在並且是一個檔案，如果使用者有許可權，它將被靜默替換。在 Windows 上，如果 target 存在，將引發 FileExistsError 異常。 target 可以是字串或另一個路徑物件。

>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
PosixPath('bar')
>>> target.open().read()
'some text'

目標路徑可以是絕對路徑或相對路徑。相對路徑是相對於當前工作目錄解釋的，而不是 Path 物件的目錄。

它是根據 os.rename() 實現的，並提供相同的保證。

在 3.8 版本中更改: 添加了返回值，返回新的 Path 例項。

Path.replace(target)

將此檔案或目錄重新命名為給定的 target，並返回指向 target 的新的 Path 例項。如果 target 指向現有檔案或空目錄，它將被無條件替換。

目標路徑可以是絕對路徑或相對路徑。相對路徑是相對於當前工作目錄解釋的，而不是 Path 物件的目錄。

在 3.8 版本中更改: 添加了返回值，返回新的 Path 例項。

Path.unlink(missing_ok=False)

刪除此檔案或符號連結。如果路徑指向目錄，請改用 Path.rmdir()。

如果 missing_ok 為 false（預設值），如果路徑不存在，則會引發 FileNotFoundError 異常。

如果 missing_ok 為 true，則 FileNotFoundError 異常將被忽略（行為與 POSIX rm -f 命令相同）。

在 3.8 版本中更改: 添加了 missing_ok 引數。

Path.rmdir()

刪除此目錄。該目錄必須為空。

許可權和所有權

Path.owner(*, follow_symlinks=True)

返回擁有該檔案的使用者的名稱。如果在系統資料庫中找不到該檔案的使用者標識 (UID)，則會引發 KeyError 異常。

此方法通常遵循符號連結；要獲取符號連結的所有者，請新增引數 follow_symlinks=False。

在 3.13 版本中更改: 如果 pwd 模組不可用，則會引發 UnsupportedOperation。在早期版本中，會引發 NotImplementedError。

在 3.13 版本中更改: 添加了 follow_symlinks 引數。

Path.group(*, follow_symlinks=True)

返回擁有該檔案的組的名稱。如果在系統資料庫中找不到該檔案的組標識 (GID)，則會引發 KeyError 異常。

此方法通常遵循符號連結；要獲取符號連結的組，請新增引數 follow_symlinks=False。

在 3.13 版本中更改: 如果 grp 模組不可用，則會引發 UnsupportedOperation。在早期版本中，會引發 NotImplementedError。

在 3.13 版本中更改: 添加了 follow_symlinks 引數。

Path.chmod(mode, *, follow_symlinks=True)

更改檔案模式和許可權，類似於 os.chmod()。

此方法通常遵循符號連結。某些 Unix 風格支援更改符號連結本身的許可權；在這些平臺上，你可以新增引數 follow_symlinks=False，或者使用 lchmod()。

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

在 3.10 版本中更改: 添加了 follow_symlinks 引數。

Path.lchmod(mode)

類似於 Path.chmod()，但是如果路徑指向符號連結，則更改符號連結的模式，而不是其目標的模式。

模式語言

以下萬用字元在 full_match()、glob() 和 rglob() 的模式中受支援

** (整個段)

匹配任意數量的檔案或目錄段，包括零個。

* (整個段)

匹配一個檔案或目錄段。

* (段的一部分)

匹配任意數量的非分隔符字元，包括零個。

?

匹配一個非分隔符字元。

[seq]

匹配 seq 中的一個字元。

[!seq]

匹配不在 seq 中的一個字元。

對於字面匹配，請將元字元放在方括號中。例如，"[?]" 匹配字元 "?"。

“**” 萬用字元啟用遞迴 globbing。以下是一些示例：

模式	含義
“**/*”	至少包含一個段的任何路徑。
“**/*.py”	最後一個段以 “.py” 結尾的任何路徑。
“assets/**”	以 “assets/” 開頭的任何路徑。
“assets/**/*”	以 “assets/” 開頭的任何路徑，但不包括 “assets/” 本身。

注意

使用 “**” 萬用字元進行 globbing 會訪問樹中的每個目錄。大型目錄樹可能需要很長時間才能搜尋。

3.13 版本更改: 使用以 “**” 結尾的模式進行 globbing 會同時返回檔案和目錄。在之前的版本中，只返回目錄。

在 Path.glob() 和 rglob() 中，可以在模式末尾新增斜槓，以便僅匹配目錄。

3.11 版本更改: 使用以路徑名元件分隔符 (sep 或 altsep) 結尾的模式進行 globbing 只會返回目錄。

與 glob 模組的比較

Path.glob() 和 Path.rglob() 接受的模式和生成的結果與 glob 模組略有不同。

1. 在 pathlib 中，以點開頭的檔案不是特殊的。這類似於向 glob.glob() 傳遞 include_hidden=True。

2. “**” 模式元件在 pathlib 中始終是遞迴的。這類似於向 glob.glob() 傳遞 recursive=True。

3. 預設情況下，pathlib 中的 “**” 模式元件不遵循符號連結。此行為在 glob.glob() 中沒有等效項，但您可以向 Path.glob() 傳遞 recurse_symlinks=True 以獲得相容的行為。

4. 與所有 PurePath 和 Path 物件一樣，從 Path.glob() 和 Path.rglob() 返回的值不包含尾部斜槓。

5. 與 glob.glob(root_dir=path) 的結果不同，pathlib 的 path.glob() 和 path.rglob() 返回的值包含 *path* 作為字首。

6. pathlib 的 path.glob() 和 path.rglob() 返回的值可能包含 *path* 本身，例如在 globbing “**” 時，而 glob.glob(root_dir=path) 的結果永遠不包含對應於 *path* 的空字串。

與 os 和 os.path 模組的比較

pathlib 使用 PurePath 和 Path 物件實現路徑操作，因此被稱為是*面向物件*的。另一方面，os 和 os.path 模組提供使用底層 str 和 bytes 物件工作的函式，這是一種更*過程化*的方法。一些使用者認為面向物件風格更具可讀性。

os 和 os.path 中的許多函式都支援 bytes 路徑和 相對於目錄描述符的路徑。這些功能在 pathlib 中不可用。

Python 的 str 和 bytes 型別以及 os 和 os.path 模組的部分是用 C 編寫的，速度非常快。 pathlib 是用純 Python 編寫的，通常速度較慢，但很少慢到需要關注。

pathlib 的路徑規範化比 os.path 稍微更主觀和一致。例如，os.path.abspath() 從路徑中刪除 “..” 段，如果涉及符號連結，可能會改變其含義，而 Path.absolute() 保留這些段以提高安全性。

pathlib 的路徑規範化可能使其不適用於某些應用程式。

1. pathlib 將 Path("my_folder/") 規範化為 Path("my_folder")，當提供給各種作業系統 API 和命令列實用程式時，這會改變路徑的含義。具體來說，缺少尾部分隔符可能會允許將路徑解析為檔案或目錄，而不僅僅是目錄。

2. pathlib 將 Path("./my_program") 規範化為 Path("my_program")，當用作可執行搜尋路徑（例如在 shell 中或生成子程序時）時，這會改變路徑的含義。具體來說，路徑中缺少分隔符可能會強制在 PATH 中查詢它，而不是在當前目錄中查詢。

由於這些差異，pathlib 不能直接替代 os.path。

相應的工具

下面是一個表，將各種 os 函式對映到它們對應的 PurePath/Path 等效項。

os 和 os.path	pathlib
os.path.dirname()	PurePath.parent
os.path.basename()	PurePath.name
os.path.splitext()	PurePath.stem, PurePath.suffix
os.path.join()	PurePath.joinpath()
os.path.isabs()	PurePath.is_absolute()
os.path.relpath()	PurePath.relative_to() [1]
os.path.expanduser()	Path.expanduser() [2]
os.path.realpath()	Path.resolve()
os.path.abspath()	Path.absolute() [3]
os.path.exists()	Path.exists()
os.path.isfile()	Path.is_file()
os.path.isdir()	Path.is_dir()
os.path.islink()	Path.is_symlink()
os.path.isjunction()	Path.is_junction()
os.path.ismount()	Path.is_mount()
os.path.samefile()	Path.samefile()
os.getcwd()	Path.cwd()
os.stat()	Path.stat()
os.lstat()	Path.lstat()
os.listdir()	Path.iterdir()
os.walk()	Path.walk() [4]
os.mkdir(), os.makedirs()	Path.mkdir()
os.link()	Path.hardlink_to()
os.symlink()	Path.symlink_to()
os.readlink()	Path.readlink()
os.rename()	Path.rename()
os.replace()	Path.replace()
os.remove(), os.unlink()	Path.unlink()
os.rmdir()	Path.rmdir()
os.chmod()	Path.chmod()
os.lchmod()	Path.lchmod()

腳註

[1]

os.path.relpath() 呼叫 abspath() 將路徑轉換為絕對路徑並移除 “..” 部分，而 PurePath.relative_to() 是一個詞法操作，當其輸入的錨點不同時（例如，如果一個路徑是絕對路徑而另一個路徑是相對路徑），會引發 ValueError。

[2]

如果無法解析主目錄，os.path.expanduser() 將返回未更改的路徑，而 Path.expanduser() 會引發 RuntimeError。

[3]

os.path.abspath() 會移除 “..” 元件，而不解析符號連結，這可能會改變路徑的含義，而 Path.absolute() 會在路徑中保留任何 “..” 元件。

[4]

在將路徑分類為 dirnames 和 filenames 時，os.walk() 總是會跟隨符號連結，而當 follow_symlinks 為 false （預設）時，Path.walk() 會將所有符號連結分類為 filenames。