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 Pathname Resolution 段

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

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 版本發生變更: parents 序列現在支援 切片 和負索引值。

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

這通常被稱為副檔名。

3.14 版本發生變更: 單個點（”.”）被視為有效字尾。

PurePath.suffixes

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

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

3.14 版本發生變更: 單個點（”.”）被視為有效字尾。

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 版本中已移除: 傳遞額外的定位引數已棄用；如果提供，它們將與 other 連線。

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

返回一個 stem 已更改的新路徑。如果原始路徑沒有名稱，則引發 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')

3.14 版本發生變更: 單個點（”.”）被視為有效字尾。在之前的版本中，如果提供了單個點，則會引發 ValueError。

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 的“file”URI 建立並表示。

備註

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

classmethod Path.from_uri(uri)

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

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

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

>>> 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 版本加入。

3.14 版本發生變更: 如果 URL 授權與本地主機名匹配，則將其丟棄。否則，如果授權不為空或 localhost，則在 Windows 上返回 UNC 路徑（與以前相同），在其他平臺上引發 ValueError。

Path.as_uri()

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

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

從 3.14 版本開始棄用，將在 3.19 版本中移除: 從 PurePath 而不是 Path 呼叫此方法是可能的，但已棄用。該方法使用 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，而不是因為路徑包含作業系統無法表示的字元而引發異常。

3.14 版本發生變更: 上述方法現在返回 False，而不是從作業系統引發任何 OSError 異常。在之前的版本中，會引發某些型別的 OSError 異常，而其他型別的則被抑制。新行為與 os.path.exists()、os.path.isdir() 等一致。使用 stat() 來檢索檔案狀態而不抑制異常。

Path.stat(*, follow_symlinks=True)

返回一個 os.stat_result 物件，其中包含此路徑的資訊，類似於 os.stat()。結果在每次呼叫此方法時查詢。

此方法通常遵循符號連結；要對符號連結進行 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。False 將在路徑無效、不可訪問或缺失時返回。使用 Path.stat() 來區分這些情況。

此方法通常遵循符號連結；要檢查符號連結是否存在，請新增引數 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 將在路徑無效、不可訪問或缺失，或者它指向的不是普通檔案時返回。使用 Path.stat() 來區分這些情況。

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

3.13 版本發生變更: 添加了 follow_symlinks 引數。

Path.is_dir(*, follow_symlinks=True)

如果路徑指向一個目錄，則返回 True。False 將在路徑無效、不可訪問或缺失，或者它指向的不是目錄時返回。使用 Path.stat() 來區分這些情況。

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

3.13 版本發生變更: 添加了 follow_symlinks 引數。

Path.is_symlink()

如果路徑指向符號連結，即使該符號連結已損壞，也返回 True。False 將在路徑無效、不可訪問或缺失，或者它指向的不是符號連結時返回。使用 Path.stat() 來區分這些情況。

Path.is_junction()

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

3.12 新版功能.

Path.is_mount()

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

在 3.7 版本加入。

3.12 版本發生變更: 增加了 Windows 支援。

Path.is_socket()

如果路徑指向 Unix 套接字，則返回 True。False 將在路徑無效、不可訪問或缺失，或者它指向的不是 Unix 套接字時返回。使用 Path.stat() 來區分這些情況。

Path.is_fifo()

如果路徑指向 FIFO，則返回 True。False 將在路徑無效、不可訪問或缺失，或者它指向的不是 FIFO 時返回。使用 Path.stat() 來區分這些情況。

Path.is_block_device()

如果路徑指向塊裝置，則返回 True。False 將在路徑無效、不可訪問或缺失，或者它指向的不是塊裝置時返回。使用 Path.stat() 來區分這些情況。

Path.is_char_device()

如果路徑指向字元裝置，則返回 True。False 將在路徑無效、不可訪問或缺失，或者它指向的不是字元裝置時返回。使用 Path.stat() 來區分這些情況。

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

一個 PathInfo 物件，支援查詢檔案型別資訊。該物件公開了快取其結果的方法，這有助於在根據檔案型別進行切換時減少所需的系統呼叫次數。例如

>>> p = Path('src')
>>> if p.info.is_symlink():
...     print('symlink')
... elif p.info.is_dir():
...     print('directory')
... elif p.info.exists():
...     print('something else')
... else:
...     print('not found')
...
directory

如果路徑是由 Path.iterdir() 生成的，則此屬性會使用從掃描父目錄中獲取的一些檔案型別資訊進行初始化。僅僅訪問 Path.info 不會執行任何檔案系統查詢。

要獲取最新資訊，最好呼叫 Path.is_dir()、is_file() 和 is_symlink()，而不是此屬性的方法。沒有辦法重置快取；相反，您可以透過 p = Path(p) 建立一個帶有空資訊快取的新路徑物件。

在 3.14 版本加入。

讀寫檔案

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 以始終遵循符號連結。

會引發一個 審計事件 pathlib.Path.glob，帶引數 self 和 pattern。

3.12 版本發生變更: 增加了 case_sensitive 引數。

3.13 版本中的變化: 增加了 recurse_symlinks 引數。

3.13 版本中的變化: pattern 引數接受 path-like object。

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

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

遞迴地全域性匹配給定的相對 pattern。這就像在 pattern 前面加上 “**/” 來呼叫 Path.glob()。

參見

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

會引發一個 審計事件 pathlib.Path.rglob，帶引數 self 和 pattern。

3.12 版本發生變更: 增加了 case_sensitive 引數。

3.13 版本中的變化: 增加了 recurse_symlinks 引數。

3.13 版本中的變化: pattern 引數接受 path-like object。

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

透過自上而下或自下而上地遍歷目錄樹來生成目錄樹中的檔名。

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

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

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

當 top_down 為真時，呼叫者可以就地修改 dirnames 列表（例如，使用 del 或切片賦值），而 Path.walk() 將只遞迴到 dirnames 中保留名稱的子目錄。這可以用於修剪搜尋，或施加特定的訪問順序，甚至可以告知 Path.walk() 呼叫者在再次恢復 Path.walk() 之前建立或重新命名的目錄。當 top_down 為假時，修改 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 為真，則根據需要建立此路徑的任何缺失父目錄；它們以預設許可權建立，不考慮 mode（模仿 POSIX mkdir -p 命令）。

如果 parents 為假（預設值），則缺少父目錄會引發 FileNotFoundError。

如果 exist_ok 為假（預設值），則如果目標目錄已存在，則會引發 FileExistsError。

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

3.5 版本中的變化: 添加了 exist_ok 引數。

Path.symlink_to(target, target_is_directory=False)

使此路徑成為指向 target 的符號連結。

在 Windows 上，符號連結表示檔案或目錄，並且不會動態地轉換為目標。如果目標存在，則將建立與目標型別匹配的符號連結。否則，如果 target_is_directory 為真，則將符號連結建立為目錄，否則建立為檔案符號連結（預設）。在非 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.copy(target, *, follow_symlinks=True, preserve_metadata=False)

將此檔案或目錄樹複製到給定的 target，並返回一個指向 target 的新 Path 例項。

如果源是一個檔案，則如果目標是現有檔案，它將被替換。如果源是符號連結且 follow_symlinks 為 true (預設)，則複製符號連結的目標。否則，將在目標位置重新建立符號連結。

如果 preserve_metadata 為假（預設值），則只保證複製目錄結構和檔案資料。將 preserve_metadata 設定為真以確保在支援的情況下複製檔案和目錄許可權、標誌、上次訪問和修改時間以及擴充套件屬性。此引數在 Windows 上覆制檔案時無效（元資料總是被保留）。

備註

在作業系統和檔案系統支援的情況下，此方法執行輕量級複製，其中資料塊僅在修改時才複製。這被稱為寫時複製。

在 3.14 版本加入。

Path.copy_into(target_dir, *, follow_symlinks=True, preserve_metadata=False)

將此檔案或目錄樹複製到給定的 target_dir 中，target_dir 應該是一個現有目錄。其他引數的處理方式與 Path.copy() 相同。返回一個指向副本的新 Path 例項。

在 3.14 版本加入。

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.move(target)

將此檔案或目錄樹移動到給定 target，並返回指向 target 的新 Path 例項。

如果 target 不存在，則將建立它。如果此路徑和 target 都是現有檔案，則 target 將被覆蓋。如果兩個路徑指向相同的檔案或目錄，或者 target 是非空目錄，則會引發 OSError。

如果兩個路徑都在同一個檔案系統上，則使用 os.replace() 執行移動。否則，此路徑將被複制（保留元資料和符號連結），然後刪除。

在 3.14 版本加入。

Path.move_into(target_dir)

將此檔案或目錄樹移動到給定的 target_dir 中，target_dir 應該是一個現有目錄。返回一個指向移動路徑的新 Path 例項。

在 3.14 版本加入。

Path.unlink(missing_ok=False)

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

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

如果 missing_ok 為真，則會忽略 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 是一系列字元。支援範圍表示式；例如，[a-z] 匹配任何小寫 ASCII 字母。可以組合多個範圍：[a-zA-Z0-9_] 匹配任何 ASCII 字母、數字或下劃線。

[!seq]

匹配 seq 中不存在的一個字元，其中 seq 遵循上述規則。

對於字面量匹配，將元字元用方括號括起來。例如，"[?]" 匹配字元 "?"。

“**” 萬用字元啟用遞迴全域性匹配。一些示例

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

備註

使用 “**” 萬用字元進行全域性匹配會遍歷樹中的每個目錄。大型目錄樹可能需要很長時間才能搜尋。

3.13 版本中的變化: 以 “**” 結尾的模式進行全域性匹配會返回檔案和目錄。在以前的版本中，只返回目錄。

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

3.11 版本中的變化: 以路徑名元件分隔符（sep 或 altsep）結尾的模式進行全域性匹配只返回目錄。

與 glob 模組的比較

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

1. 在 pathlib 中，以點開頭的檔案沒有特殊之處。這就像將 include_hidden=True 傳遞給 glob.glob()。

2. 在 pathlib 中，“**” 模式元件始終是遞迴的。這就像將 recursive=True 傳遞給 glob.glob()。

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

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

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

6. pathlib 的 path.glob() 和 path.rglob() 返回的值可能包含 path 本身，例如在全域性匹配 “**” 時，而 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]

os.walk() 在將路徑分類為 dirnames 和 filenames 時總是遵循符號連結，而 Path.walk() 在 follow_symlinks 為假（預設值）時將所有符號連結分類到 filenames 中。

協議

pathlib.types 模組提供用於靜態型別檢查的型別。

在 3.14 版本加入。

class pathlib.types.PathInfo

一個描述 Path.info 屬性的 typing.Protocol。實現可以從它們的方法返回快取結果。

exists(*, follow_symlinks=True)

如果路徑是現有檔案或目錄，或任何其他型別的檔案，則返回 True；如果路徑不存在，則返回 False。

如果 follow_symlinks 為 False，則對於符號連結返回 True，而不檢查其目標是否存在。

is_dir(*, follow_symlinks=True)

如果路徑是目錄，或者指向目錄的符號連結，則返回 True；如果路徑是（或指向）任何其他型別的檔案，或者它不存在，則返回 False。

如果 follow_symlinks 為 False，則僅當路徑是目錄時才返回 True（不跟隨符號連結）；如果路徑是任何其他型別的檔案，或者它不存在，則返回 False。

is_file(*, follow_symlinks=True)

如果路徑是檔案，或者指向檔案的符號連結，則返回 True；如果路徑是（或指向）目錄或其他非檔案，或者它不存在，則返回 False。

如果 follow_symlinks 為 False，則僅當路徑是檔案時才返回 True（不跟隨符號連結）；如果路徑是目錄或其他非檔案，或者它不存在，則返回 False。

is_symlink()

如果路徑是符號連結（即使已損壞），則返回 True；如果路徑是目錄或任何型別的檔案，或者它不存在，則返回 False。