通用屬性¶

路徑物件是不可變 (immutable) 且可雜湊 (hashable) 的。相同類型的路徑物件可以被比較和排序。這些屬性遵守該類型的大小寫語意規則：

>>>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>", line1, in<module>TypeError:'<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

運算子¶

斜線運算子 (slash operator) 用於建立子路徑，就像是os.path.join() 函式一樣。如果引數是絕對路徑，則忽略前一個路徑。在 Windows 系統上，當引數是具有根目錄的相對路徑（例如，r'\foo'），磁碟機部分不會被重置：

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

路徑物件可以被用在任何可以接受實作os.PathLike 的物件的地方：

>>>importos>>>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 會得到原始檔案系統路徑的 bytes 物件，就像使用os.fsencode() 編碼過的一樣：

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

對個別組成的存取¶

可以使用下列屬性來存取路徑的個別「組成」(parts, components)：

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¶

若存在則為一個表示磁碟機字母 (drive letter) 或磁碟機名稱 (drive name) 的字串：

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

UNC shares 也被視為磁碟機：

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

PurePath.root¶

若存在則為一個表示（本地或全域）根目錄的字串：

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

UNC shares 都會有一個根目錄：

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

一個不可變的序列，為路徑邏輯上的祖先 (logical ancestors) 提供存取：

>>>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 版的變更:父序列現在支援slices 及負的索引值。

PurePath.parent¶

邏輯上的父路徑：

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

你不能越過一個 anchor 或空路徑：

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

備註

這是一個純粹字句上的 (lexical) 運算，因此會有以下行為：

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

如果你想要沿任意的檔案系統路徑往上走，建議要先呼叫Path.resolve() 來解析符號連結 (symlink) 及去除其中的”..”。

PurePath.name¶

最後的路徑組成 (final path component) 的字串表示，不包含任何磁碟機或根目錄：

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

一個路徑後綴 (suffix) 的串列，通常被稱為檔案副檔名：

>>>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==poruinp.parentsFalse

在 3.9 版被加入.

Deprecated since version 3.12, will be removed in version 3.14:額外引數的傳入已棄用；如果有的話，它們會與other 連接在一起。

PurePath.is_reserved()¶

對PureWindowsPath 來說，當路徑在 Windows 下被視為保留的話會回傳True，否則回傳False。對PurePosixPath 來說，總是回傳False。

在 3.13 版的變更:Windows 路徑名稱中包含冒號或結尾為點或空格會被視為保留。UNC 路徑可能被視為保留。

Deprecated since version 3.13, will be removed in version 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 形式的模式 (glob-style pattern) 做比對。如果比對成功則回傳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

也參考

模式語言 (pattern language) 文件。

像其它方法一樣，是否區分大小寫會遵循平台的預設行為：

>>>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 形式的模式 (glob-style pattern) 做比對。如果比對成功則回傳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>", line1, in<module>  File"pathlib.py", line941, inrelative_toraiseValueError(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>", line1, in<module>  File"pathlib.py", line941, inrelative_toraiseValueError(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 相同）。

Deprecated since version 3.12, will be removed in version 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>", line1, in<module>  File"/home/antoine/cpython/default/Lib/pathlib.py", line751, inwith_nameraiseValueError("%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>", line1, in<module>  File"/home/antoine/cpython/default/Lib/pathlib.py", line861, inwith_stemreturnself.with_name(stem+self.suffix)  File"/home/antoine/cpython/default/Lib/pathlib.py", line851, inwith_nameraiseValueError("%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() 建立衍生路徑。子類別可以覆寫此方法來傳遞資訊給衍生路徑，例如：

frompathlibimportPurePosixPathclassMyPath(PurePosixPath):def__init__(self,*pathsegments,session_id):super().__init__(*pathsegments)self.session_id=session_iddefwith_segments(self,*pathsegments):returntype(self)(*pathsegments,session_id=self.session_id)etc=MyPath('/etc',session_id=42)hosts=etc/'hosts'print(hosts.session_id)# 42

在 3.12 版被加入.

剖析和產生 URI¶

實體路徑物件可以從符合RFC 8089 中的 'file' URI 建立，也可以以該形式來表示。

classmethodPath.from_uri(uri)¶

從剖析 'file' 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()¶

以 'file' 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() 而讓它完全不純粹。

擴展和解析路徑¶

classmethodPath.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 版被加入.

classmethodPath.cwd()¶

回傳一個代表目前目錄的新的路徑物件（像os.getcwd() 回傳的一樣）：

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

Path.absolute()¶

將路徑轉換為絕對路徑，不進行標準化或解析符號連結。回傳一個新的路徑物件：

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

Path.resolve(strict=False)¶

將路徑轉換為絕對路徑，解析所有符號連結。回傳一個新的路徑物件：

>>>p=Path()>>>pPosixPath('.')>>>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。

查詢檔案類型和狀態¶

Path.stat(*,follow_symlinks=True)¶

回傳一個包含該路徑資訊的os.stat_result 物件，像os.stat() 一樣。每次呼叫此方法都會重新查詢結果。

此方法通常會跟隨 (follow) 符號連結；想要取得符號連結的資訊，可以加上引數follow_symlinks=False 或使用lstat()。

>>>p=Path('setup.py')>>>p.stat().st_size956>>>p.stat().st_mtime1327883547.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()¶

如果該路徑指向一個連接點 (junction) 則回傳True，對其他類型的檔案則回傳False。目前只有 Windows 支援連接點。

在 3.12 版被加入.

Path.is_mount()¶

如果路徑是一個mount point（一個檔案系統裡掛載不同檔案系統的存取點）則回傳True。在 POSIX 上，此函式檢查path 的父路徑path/.. 是否和path 在不同的裝置上，或者path/.. 和path 是否指向相同裝置的相同 i-node ── 這對於所有 Unix 和 POSIX 變體來說應該會偵測出掛載點。在 Windows 上，一個掛載點被視為一個根磁碟機字母（例如c:\）、一個 UNC share（例如\\server\share）或是掛載的檔案系統目錄。

在 3.7 版被加入.

在 3.12 版的變更:加入對 Windows 的支援。

Path.is_socket()¶

如果該路徑指向一個 Unix socket（或者是一個指向 Unix socket 的符號連結）則會回傳True，如果指向其他類型的檔案則回傳False。

如果路徑不存在或者是一個斷掉的符號連結則也會回傳False；其他錯誤（例如權限錯誤）則會傳遞出來。

Path.is_fifo()¶

如果該路徑指向一個 FIFO（或者是一個指向 FIFO 的符號連結）則會回傳True，如果指向其他類型的檔案則回傳False。

如果路徑不存在或者是一個斷掉的符號連結則也會回傳False；其他錯誤（例如權限錯誤）則會傳遞出來。

Path.is_block_device()¶

如果該路徑指向一個區塊裝置 (block device)（或者是一個指向區塊裝置的符號連結）則會回傳True，如果指向其他類型的檔案則回傳False。

如果路徑不存在或者是一個斷掉的符號連結則也會回傳False；其他錯誤（例如權限錯誤）則會傳遞出來。

Path.is_char_device()¶

如果該路徑指向一個字元裝置 (character 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')>>>withp.open()asf:...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()¶

當該路徑指向一個目錄，會 yield 目錄裡面的路徑物件：

>>>p=Path('docs')>>>forchildinp.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')

子路徑會以任意順序被 yield，且不會包含特殊項目'.' 和'..'。如果一個檔案在建立這個疊代器之後加到該目錄或從目錄刪除，這個檔案的路徑物件是否會被包含是沒有明定的。

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

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

在該路徑表示的目錄裡，以 glob 方式比對所給定的相對pattern，並 yield 所有比對到的檔案（任意類型）：

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

也參考

模式語言 (pattern language) 文件。

預設情況下，或者當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)¶

遞迴地 glob 給定的相對pattern。這相當於在給定的相對pattern 前面加上 "**/" 並呼叫Path.glob()。

也參考

模式語言 (pattern language) 和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 但不包含 '.' 和 '..' ），此方法會 yield 一個(dirpath,dirnames,filenames) 的三元素元組。

dirpath 是一個目前走訪到的目錄的Path，dirnames 是一個dirpath 裡的子目錄名稱的字串串列（不包含'.' 和'..' ），而filenames 是一個dirpath 裡非目錄檔案名稱的字串串列。要取得在dirpath 裡檔案或目錄的完整路徑（以self 開頭），可以使用dirpath/name。會根據檔案系統來決定串列是否有排序。

如果可選引數top_down 是 true（預設值），一個目錄的三元素元組會在其任何子目錄的三元素元組之前產生（目錄是由上而下走訪）。如果top_down 是 false，一個目錄的三元素元組會在其所有子目錄的三元素元組之後產生（目錄是由下而上走訪）。不論top_down 的值是什麼，子目錄的串列會在走訪該目錄及其子目錄的三元素元組之前取得。

當top_down 是 true，呼叫者可以原地 (in-place) 修改dirnames 串列（例如使用del 或切片賦值 (slice assignment)），且Path.walk() 只會遞迴進名稱依然留在dirnames 裡的子目錄。這可以用來修剪搜尋，或者強加特定順序的瀏覽，或者甚至在繼續Path.walk() 之前，用來告訴Path.walk() 關於呼叫者建立或重新命名的目錄。當top_down 是 false 的時候，修改dirnames 對Path.walk() 的行為沒有影響，因為dirnames 裡的目錄已經在dirnames yield 給呼叫者之前被產生。

預設來自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 適當地移除目錄。

備註

如果follow_symlinks 是 false，和os.walk() 行為不同的是Path.walk() 會將指向目錄的符號連結放在filenames 串列。

這個範例會顯示在每個目錄裡所有檔案使用的位元組數量，同時間忽略__pycache__ 目錄：

frompathlibimportPathforroot,dirs,filesinPath("cpython/Lib/concurrent").walk(on_error=print):print(root,"consumes",sum((root/file).stat().st_sizeforfileinfiles),"bytes in",len(files),"non-directory files")if'__pycache__'indirs:dirs.remove('__pycache__')

下一個範例是shutil.rmtree() 的一個簡單的實作方式。由下而上走訪目錄樹是必要的，因為rmdir() 不允許在目錄為空之前刪除它：

# 刪除可從 "top" 目錄到達的所有東西。# 注意：這是危險的！例如，如果 top == Path('/')，# 它可能會刪除你所有的檔案。forroot,dirs,filesintop.walk(top_down=False):fornameinfiles:(root/name).unlink()fornameindirs:(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 則會結合行程 (process) 的umask 值來決定檔案模式與存取旗標 (access flag)。如果路徑已經存在，會引發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) 動態改變。如果目標存在，則符號連結的類型會被建立來符合其目標。否則如果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_size956>>>p.lstat().st_size8

備註

引數的順序 (link, target) 和os.symlink() 相反。

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

Path.hardlink_to(target)¶

使這個路徑成為與target 相同檔案的一個硬連結 (hard link)。

備註

引數的順序 (link, target) 和os.link() 相反。

在 3.10 版被加入.

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

重新命名和刪除¶

Path.rename(target)¶

將此檔案或目錄重新命名為給定的target ，並回傳一個新的Path 實例指向該target。在 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 例外會被忽略（行為與 POSIXrm-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)¶

修改檔案模式 (file mode) 與權限，像os.chmod() 一樣。

此方法通常會跟隨符號連結。一些 Unix 類型支援修改符號連結本身的權限；在這些平台上你可以加上引數follow_symlinks=False 或使用lchmod()。

>>>p=Path('setup.py')>>>p.stat().st_mode33277>>>p.chmod(0o444)>>>p.stat().st_mode33060

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

Path.lchmod(mode)¶

類似Path.chmod()，但如果該路徑指向一個符號連結，則符號連結的模式 (mode) 會被改變而不是其指向的目標。

對應工具¶

以下是一張表格，對應許多os 函式及其相符於PurePath/Path 的項目。

註腳

os.path.relpath() 會呼叫abspath() 來將路徑變成絕對路徑並移除 ".." 部分，而PurePath.relative_to() 是一個文本上的操作，當它輸入的錨點不同時（例如一個是絕對路徑，另一個則是相對路徑）會引發ValueError。

os.path.expanduser() 會在無法解析家目錄時回傳原始路徑，而Path.expanduser() 則會引發RuntimeError。

os.path.abspath() 將 ".." 組成移除而不解析符號連結，這可能會改變路徑的意義，而Path.absolute() 則會保留路徑中任何 ".." 組成。

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