`pathlib` --- オブジェクト指向のファイルシステムパス¶

Added in version 3.4.

ソースコード: Lib/pathlib/

このモジュールはファイルシステムのパスを表すクラスを提供していて、様々なオペレーティングシステムについての適切な意味論をそれらのクラスに持たせています。 Path クラスは純粋パスと具象パスからなります。純粋パスは I/O を伴わない純粋な計算操作を提供します。具象パスは純粋パスを継承していますが、 I/O 操作も提供しています。

pathlib で利用できるクラスを示す継承図。最も基本的なクラスは PurePath で、直接のサブクラスとして PurePosixPath、PureWindowsPath、Path の 3 つがあります。この 4 クラスに加えて、多重継承を使う 2 つのクラスがあります。 PosixPath は PurePosixPath と Path を、WindowsPath は PureWindowsPath と Path を継承しています。

あなたが今までこのモジュールを使用したことがない場合や、タスクに適しているのがどのクラスかわからない場合は、 Path はきっとあなたに必要なものでしょう。 Path はコードが実行されているプラットフォーム用の具象パスのインスタンスを作成します。

純粋パスは、以下のようないくつかの特殊なケースで有用です:

Unix マシン上で Windows のパスを扱いたいとき (またはその逆)。Unix 上で実行しているときに WindowsPath のインスタンスを作成することはできませんが、PureWindowsPath なら可能になります。
コードが実際には OS にアクセスせず、パスの操作だけを行うことを保証したいとき。この場合、OS にアクセスする操作を持たない純粋パスクラスのインスタンスを使うと役立ちます。

参考

PEP 428: The pathlib module -- オブジェクト指向のファイルシステムパス。

参考

文字列による低水準のパス操作の場合は 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 を継承した例外です。パスオブジェクトがサポートしていない操作を行おうとした時に送出されます。

Added in version 3.13.

純粋パス¶

純粋パスオブジェクトは実際にファイルシステムにアクセスしないパス操作処理を提供します。これらのクラスにアクセスするには 3 つの方法があり、それらを フレーバー と呼んでいます:

class pathlib.PurePath(*pathsegments)¶

システムのパスのフレーバーを表すジェネリッククラスです (インスタンスを作成することで PurePosixPath または PureWindowsPath のどちらかが作成されます):

>>> PurePath('setup.py')      # Unix マシン上で実行
PurePosixPath('setup.py')

pathsegments の各要素は、パスの構成要素を表す文字列か、パスオブジェクトなどの、 os.PathLike インターフェースを実装するオブジェクトである必要があります。 os.PathLike インターフェースでは、 __fspath__() メソッドが文字列を返します:

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

pathsegments が空、または空文字列だけで構成される場合は、カレントディレクトリとみなします。

>>> PurePath(), PurePath('')
(PurePosixPath('.'), 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')

(a naïve approach would make PurePosixPath('foo/../bar') equivalent to PurePosixPath('bar'), which is wrong if foo is a symbolic link to another directory)

純粋パスオブジェクトは 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 のサブクラスです。このパスフレーバー UNC paths を含む Windows ファイルシステムパスを表します:

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

パスオブジェクトの文字列表現はそのシステム自身の Raw ファイルシステムパス (ネイティブの形式、例えば Windows では区切り文字がバックスラッシュ) になり、文字列としてファイルパスを取るあらゆる関数に渡すことができます:

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

同様に、パスオブジェクトを bytes で呼び出すと、Raw ファイルシステムパスを os.fsencode() でエンコードされたバイト列オブジェクトで返します:

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

注釈

bytes での呼び出しは Unix 上での使用のみ推奨します。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')

(ドライブ名とローカルルートは単一要素にまとめられます)

メソッドとプロパティ¶

parent、name、stem、suffix プロパティは、パスの異なる部分を表します。例えば、次のパスを使います。

>>> p = PurePosixPath('/srv/holy/grail.tar.gz')

p = PurePosixPath('/srv/holy/grail.tar.gz') の場合、p.parent は PurePosixPath('/srv/holy')、p.name は 'grail.tar.gz'、p.stem は 'grail.tar'、p.suffix は '.gz' です。

stem は最後の拡張子だけを除きます。この例では .tar が含まれます。

純粋パスは以下のメソッドとプロパティを提供します:

PurePath.parser¶: 低レベルのパスのパースと結合に使用される os.path モジュールの実装。posixpath または ntpath。

Added in version 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 に沿ったものです:

「2 つの連続したスラッシュで始まるパス名は実装で定義した方法で解釈してもよいが、先頭のスラッシュが 3 つ以上の場合は 1 つのスラッシュとして扱わなければならない。」

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'

バージョン 3.14 で変更: 単一のドット (".") を有効な拡張子とみなすようになりました。

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

Added in version 3.9.

バージョン 3.12 で非推奨、バージョン 3.14 で削除: 追加の引数指定は非推奨となりました。指定された場合は other と連結されます。

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('**/*.py')
True
>>> PurePath('/a/b/c.py').full_match('/a/**')
True

上の例のように "/**" で終わるパターンを full_match に渡すと、意外な結果になることがあります。 "**" は 0 個の要素にもマッチしますが、".../**" がマッチするには区切り文字が必要です。そのため、"/a/**" はパス "/a" にマッチしません。 PurePath は末尾のスラッシュを取り除くので、"/a/" にもマッチしません。

>>> PurePath('/a').full_match('/a/**')
False
>>> PurePath('/a/').full_match('/a/**')
False

参考

パターン言語ドキュメント。

他のメソッドと同様に、大文字小文字の区別はプラットフォームの設定に従います:

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

Set case_sensitive to True or False to override this behaviour.

Added in version 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 パラメタが path-like object を受け付けるようになりました。

バージョン 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 部分を変更したパスを返します。オリジナルパスに 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

Added in version 3.9.

PurePath.with_suffix(suffix)¶

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

Added in version 3.12.

具象パス¶

具象パスは純粋パスクラスのサブクラスです。純粋パスが提供する操作に加え、パスオブジェクト上でシステムコールを呼ぶメソッドも提供しています。具象パスのインスタンスを作成するには 3 つの方法があります:

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 から作成でき、'file' URI として表すこともできます。

注釈

ファイルシステムエンコーディングが異なるマシン間では、file URI の移植性はありません。

classmethod Path.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 を送出します。

Added in version 3.13.

バージョン 3.14 で変更: URL の authority がローカルホスト名と一致する場合は、その部分を取り除くようになりました。それ以外で authority が空でも 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 で削除予定: Path ではなく PurePath からこのメソッドを呼び出すこともできますが、非推奨です。このメソッドは os.fsencode() を使うため、厳密には純粋な操作ではありません。

パスの展開と解決¶

classmethod Path.home()¶

ユーザーのホームディレクトリ (os.path.expanduser() での ~ の返り値) を表す新しいパスオブジェクトを返します。ホームディレクトリが解決できない場合は、 RuntimeError を送出します。

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

Added in version 3.5.

Path.expanduser()¶

パス要素 ~ および ~user を os.path.expanduser() が返すように展開した新しいパスオブジェクトを返します。ホームディレクトリが解決できない場合は、 RuntimeError を送出します。

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

Added in version 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 より前の挙動は strict です)。

バージョン 3.13 で変更: シンボリックリンクのループを他のエラーと同様に扱うようになりました。 strict モードでは OSError を送出し、非 strict モードでは例外を送出しません。以前のバージョンでは、strict の値にかかわらず RuntimeError を送出していました。

Path.readlink()¶

( os.readlink() が返す) シンボリックリンクが指すパスを返します:

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

Added in version 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() は、OSレベルで表現不能な文字を含むパスに対して、例外を送出する代わりに False を返すようになりました。

バージョン 3.14 で変更: 上記のメソッドは、オペレーティングシステムからのあらゆる OSError 例外を送出する代わりに、False を返すようになりました。以前のバージョンでは、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('.').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のみジャンクションをサポートしています。

Added in version 3.12.

Path.is_mount()¶: パスがマウントポイント mount point (ファイルシステムの中で異なるファイルシステムがマウントされているところ) なら、 True を返します。POSIX では、この関数は path の親ディレクトリである path/.. が path と異なるデバイス上にあるか、あるいは path/.. と path が同じデバイス上の同じ i-node を指しているかをチェックします --- これによって全ての Unix 系システムと POSIX 標準でマウントポイントが検出できます。Windowsでは、マウントポイントはドライブレターを持つルート(e.g. c:\)、共有 UNC(e.g. \\server\share)またはマウントされたファイルシステムのディレクトリです。

Added in version 3.7.

バージョン 3.12 で変更: Windows のサポートが追加されました。

Path.is_socket()¶: パスが Unix ソケットを指していれば True を返します。パスが不正、アクセス不能、存在しない、またはUnix ソケット以外のものを指している場合は False を返します。これらのケースを区別するには Path.stat() を使ってください。

Path.is_fifo()¶: パスが FIFO を指していれば True を返します。パスが不正、アクセス不能、存在しない、またはFIFO 以外のものを指している場合は False を返します。これらのケースを区別するには Path.stat() を使ってください。

Path.is_block_device()¶: パスがブロックデバイスを指していれば True を返します。パスが不正、アクセス不能、存在しない、またはブロックデバイス以外のものを指している場合は False を返します。これらのケースを区別するには Path.stat() を使ってください。

Path.is_char_device()¶: パスがキャラクタデバイスを指していれば True を返します。パスが不正、アクセス不能、存在しない、またはキャラクタデバイス以外のものを指している場合は False を返します。これらのケースを区別するには Path.stat() を使ってください。

Path.samefile(other_path)¶

このパスが参照するファイルが other_path (Path オブジェクトか文字列) と同じであれば True を、異なるファイルであれば False を返します。意味的には os.path.samefile() および os.path.samestat() と同じです。

なんらかの理由でどちらかのファイルにアクセスできない場合は OSError が送出されます。

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

Added in version 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) で、情報のキャッシュが空の新しいパスオブジェクトを作成できます。

Added in version 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() と同じです。

Added in version 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'

Added in version 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() と同じです。

Added in version 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'

同じ名前のファイルがすでにあれば上書きされます。

Added in version 3.5.

ディレクトリを読む¶

Path.iterdir()¶

パスがディレクトリを指していた場合、ディレクトリの内容のパスオブジェクトを yield します:

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

子の要素は任意の順番で yield されます。特殊なパスの '.' と '..' は含まれません。イテレーターを生成したあとにディレクトリにファイルを削除または追加した場合に、そのファイルのパスオブジェクトが含まれるかは定義されていません。

パスがディレクトリでないかアクセスできない場合は OSError を送出します。

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

現在のパスが表すディレクトリ内で相対 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')]

注釈

パスが返される順序は決まっていません。特定の順序が必要な場合は、結果をソートしてください。

参考

パターン言語ドキュメント。

デフォルトまたは case_sensitive キーワード専用引数に None を指定した場合、このメソッドはパスの一致判定にプラットフォームに依存した大文字小文字のルールを使用します。一般的にPOSIXは大文字と小文字を区別し、Windowsは区別しません。case_sensitive を True または False に設定するとこの動作を上書きします。

デフォルトの場合、またはキーワード専用引数 recurse_symlinks が False の場合、このメソッドは "**" ワイルドカードの展開時を除いてシンボリックリンクをたどります。常にシンボリックリンクをたどるには、recurse_symlinks を True に設定してください。

注釈

ファイルシステムの走査中に発生した OSError 例外はすべて抑制します。これには、読み取り権限のないディレクトリへのアクセスで発生する PermissionError も含まれます。

引数 self, pattern を指定して監査イベント pathlib.Path.glob を送出します。

バージョン 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 で再帰的に Glob します。Path.glob() で pattern の前に "**/" をつけ呼び出した場合と似ています。

注釈

パスが返される順序は決まっていません。特定の順序が必要な場合は、結果をソートしてください。

注釈

ファイルシステムの走査中に発生した OSError 例外はすべて抑制します。これには、読み取り権限のないディレクトリへのアクセスで発生する PermissionError も含まれます。

参考

パターン言語と Path.glob() のドキュメント。

引数 self, pattern を指定して監査イベント pathlib.Path.rglob を送出します。

バージョン 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 は含み、'.' と '..' は除きます) について、このメソッドは 3 要素のタプル (dirpath, dirnames, filenames) を yield します。

dirpath は現在たどっているディレクトリの Path、dirnames は dirpath 内のサブディレクトリ名の文字列のリスト ('.' と '..' を除く)、filenames は dirpath 内のディレクトリ以外のファイル名の文字列のリストです。 dirpath 内のファイルやディレクトリの、self から始まる完全なパスを得るには、dirpath / name とします。リストがソートされているかどうかはファイルシステムによります。

省略可能な引数 top_down が真 (デフォルト) の場合、各ディレクトリの 3 要素タプルは、そのサブディレクトリのタプルより先に生成されます (上から下にたどります)。 top_down が偽の場合、各ディレクトリのタプルは、そのすべてのサブディレクトリのタプルの後に生成されます (下から上にたどります)。 top_down の値にかかわらず、サブディレクトリのリストは、そのディレクトリやサブディレクトリのタプルをたどる前に取得します。

top_down が真の場合、呼び出し側は del やスライス代入などで dirnames リストをその場で変更でき、Path.walk() は dirnames に名前が残っているサブディレクトリだけを再帰的にたどります。これにより、探索対象を絞ったり、たどる順序を指定したり、さらには呼び出し側が Path.walk() を再開する前に作成・改名したディレクトリを Path.walk() に知らせたりできます。 top_down が偽の場合は、dirnames が呼び出し側に yield される時点で、その中のディレクトリはすでに走査済みのため、dirnames を変更しても Path.walk() の動作には影響しません。

デフォルトでは os.scandir() のエラーは無視します。省略可能な引数 on_error を指定する場合は、呼び出し可能オブジェクトでなければなりません。 OSError インスタンスを唯一の引数として呼び出されます。このオブジェクトは、エラーを処理して走査を続けることも、再送出して走査を止めることもできます。ファイル名は例外オブジェクトの filename 属性で取得できます。

デフォルトでは Path.walk() はシンボリックリンクをたどらず、filenames リストに追加します。 follow_symlinks を真にすると、シンボリックリンクを解決し、リンク先に応じて dirnames または filenames に入れます。その結果、サポートされている環境では、シンボリックリンクが指すディレクトリもたどります。

注釈

follow_symlinks に True を指定すると、シンボリックリンクが親ディレクトリを指していた場合に、無限ループになることに注意してください。 Path.walk() はすでにたどったディレクトリを管理したりはしません。

注釈

Path.walk() は、たどるディレクトリが実行中に変更されないことを前提とします。例えば、dirnames 内のディレクトリがシンボリックリンクに置き換えられた場合、follow_symlinks が偽でも Path.walk() はその中をたどろうとします。この動作を防ぐには、必要に応じて dirnames からディレクトリを取り除いてください。

注釈

os.walk() と異なり、Path.walk() は follow_symlinks が偽の場合、ディレクトリへのシンボリックリンクを 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() は空でないディレクトリを削除できないため、ツリーを下から上にたどることが不可欠です。

# ディレクトリ "top" からたどれるものをすべて削除する。
# 注意: 危険な処理です。
# 例えば top == Path('/') なら、すべてのファイルを削除してしまう可能性があります。
for root, dirs, files in top.walk(top_down=False):
    for name in files:
        (root / name).unlink()
    for name in dirs:
        (root / name).rmdir()

Added in version 3.12.

ファイルとディレクトリの作成¶

Path.touch(mode=0o666, exist_ok=True)¶: 与えられたパスにファイルを作成します。mode が与えられた場合、プロセスの umask 値と組み合わせてファイルのモードとアクセスフラグが決定されます。ファイルがすでに存在した場合、exist_ok が真ならばこの関数は正常に終了します (そしてファイルの更新日付が現在の日時に変更されます)。その他の場合は FileExistsError が送出されます。

参考

open()、write_text()、write_bytes() メソッドも、ファイルの作成によく使われます。

Path.mkdir(mode=0o777, parents=False, exist_ok=False, *, parent_mode=None)¶

与えられたパスに新しくディレクトリを作成します。mode が与えられていた場合、プロセスの umask 値と組み合わせてファイルのモードとアクセスフラグを決定します。パスがすでに存在していた場合 FileExistsError が送出されます。

parents の値が真の場合、このパスの親ディレクトリを必要に応じて作成します; それらのアクセス制限はデフォルト値が取られ、mode は使用されません (POSIX の mkdir -p コマンドを真似ています)。

parent_mode が None でない場合、parents が真のときに新しく作成する中間のディレクトリには、この値をモードとして使います。 mode と同様に、プロセスの umask 値と組み合わせます。それ以外の場合、中間のディレクトリはデフォルトのパーミッションで作成します (この場合も umask の影響を受けます)。

parents の値が偽の場合 (デフォルト)、親ディレクトリがないと FileNotFoundError を送出します。

exist_ok の値が (デフォルトの) 偽の場合、対象のディレクトリがすでに存在すると FileExistsError を送出します。

exist_ok が真の場合、指定されたパスがファイルシステムにすでに存在し、かつディレクトリではない場合を除き、FileExistsError は送出しません (POSIX の mkdir -p コマンドと同じ動作です)。

バージョン 3.5 で変更: exist_ok 引数が追加されました。

Added in version 3.15: parent_mode パラメータ。

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

注釈

引数の並び (link, target) は os.symlink() とは逆です。

バージョン 3.13 で変更: os.symlink() が利用できない場合 UnsupportedOperation を送出します。以前のバージョンでは NotImplementedError を送出していました。

Path.hardlink_to(target)¶: このパスを target と同じファイルへのハードリンクにします。

注釈

引数の並び (link, target) は os.link() とは逆です。

Added in version 3.10.

バージョン 3.13 で変更: os.link() が利用できない場合 UnsupportedOperation を送出します。以前のバージョンでは NotImplementedError を送出していました。

コピー、移動、削除¶

Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)¶

このファイルまたはディレクトリツリーを指定された target にコピーし、target を指す新しい Path インスタンスを返します。

コピー元がファイルで、コピー先にもファイルが存在する場合は、コピー先を置き換えます。コピー元がシンボリックリンクで、follow_symlinks が真 (デフォルト) の場合は、リンク先をコピーします。コピー元がシンボリックリンクで follow_symlinks が偽の場合は、コピー先にシンボリックリンクを再作成します。

preserve_metadata が偽 (デフォルト) の場合、コピーされることが保証されるのはディレクトリ構造とファイルのデータだけです。サポートされる環境で、ファイルとディレクトリのパーミッション、フラグ、最終アクセス・更新時刻、拡張属性もコピーするには、preserve_metadata を真に設定してください。 Windows ではファイルのメタデータを常に保持するため、ファイルのコピーでこの引数の効果はありません。

注釈

オペレーティングシステムとファイルシステムがサポートしている場合、このメソッドはデータブロックを変更時にだけコピーする、軽量なコピーを行います。これはコピーオンライトと呼ばれます。

Added in version 3.14.

Path.copy_into(target_dir, *, follow_symlinks=True, preserve_metadata=False)¶: このファイルまたはディレクトリツリーを、既存のディレクトリである target_dir の中にコピーします。他の引数の扱いは Path.copy() と同じです。コピーを指す新しい Path インスタンスを返します。

Added in version 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'

targetパスは絶対または相対で指定できます。相対パスは現在の作業ディレクトリからの相対パスとして解釈し、Path オブジェクトのディレクトリ ではありません。

os.rename() を使って実装されており、同じ保証を提供します。

バージョン 3.8 で変更: 戻り値を追加し、新しい Path インスタンスを返します。

Path.replace(target)¶

現在のファイルまたはディレクトリの名前を target に変更し、 target を指す新しい Path のインスタンスを返します。target が既存のファイルか空のディレクトリを指していた場合、無条件に置き換えられます。

targetパスは絶対または相対で指定できます。相対パスは現在の作業ディレクトリからの相対パスとして解釈し、Path オブジェクトのディレクトリ ではありません。

バージョン 3.8 で変更: 戻り値を追加し、新しい Path インスタンスを返します。

Path.move(target)¶

このファイルまたはディレクトリツリーを指定された target に移動し、target を指す新しい Path インスタンスを返します。

target が存在しなければ作成します。このパスと target がともに既存のファイルである場合は、移動先を上書きします。両パスが同じファイルやディレクトリを指す場合、または target が空でないディレクトリである場合は、OSError を送出します。

両パスが同じファイルシステム上にある場合は、os.replace() で移動します。それ以外の場合は、メタデータとシンボリックリンクを保持してこのパスをコピーし、その後に元のパスを削除します。

Added in version 3.14.

Path.move_into(target_dir)¶: このファイルまたはディレクトリツリーを、既存のディレクトリである target_dir の中に移動します。移動後のパスを指す新しい Path インスタンスを返します。

Added in version 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)¶

ファイルの所有者のユーザー名を返します。ファイルのユーザーID(UID)がシステムのデータベースに見つからない場合 KeyError が送出されます。

このメソッドは通常はシンボリックリンクをたどります。シンボリックリンクの所有者を取得するには follow_symlinks=False 引数を追加してください。

バージョン 3.13 で変更: pwd モジュールが利用できない場合 UnsupportedOperation を送出します。以前のバージョンでは NotImplementedError を送出していました。

バージョン 3.13 で変更: follow_symlinks パラメータが追加されました。

Path.group(*, follow_symlinks=True)¶

ファイルの所有グループ名を返します。ファイルのグループID(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() のパターンでは、次のワイルドカードを使えます:

** (要素全体): 0 個以上の任意の数のファイルやディレクトリの要素にマッチします。 full_match() では "a/**" は "a" にマッチしませんが、glob() はこのパターンに対して "a" を yield することに注意してください。
* (要素全体): 1 つのファイルまたはディレクトリの要素にマッチします。
* (要素の一部): 区切り文字以外の、0 文字以上の任意の数の文字にマッチします。
?: 区切り文字以外の 1 文字にマッチします。
[seq]: 文字の列 seq に含まれる 1 文字にマッチします。範囲の指定もサポートしています。例えば、[a-z] は ASCII の任意の英小文字にマッチします。複数の範囲も組み合わせられ、[a-zA-Z0-9_] は ASCII の任意の英字、数字、アンダースコアにマッチします。
[!seq]: seq に含まれない 1 文字にマッチします。 seq の規則は上記と同じです。

リテラルにマッチさせるには、メタ文字を括弧に入れてください。例えば、"[?]" は文字 "?" にマッチします。

"**" ワイルドカードを使うと再帰的に glob を行えます。いくつか例を示します:

Pattern	意味
"`*/`"	1つ以上の要素がある任意のパス。
"`*/.py`"	最後の要素が "`.py`" で終わる任意のパス。
"`assets/**`"	"`assets/`" で始まる任意のパス。
"`assets/*/`"	"`assets/`" で始まる任意のパス("`assets/`" 自身を除く)。

注釈

"**" ワイルドカードを使った glob は、ツリー内のすべてのディレクトリをたどります。大きなディレクトリツリーでは、検索に長い時間がかかる場合があります。

バージョン 3.13 で変更: "**" で終わるパターンで glob を行うと、ファイルとディレクトリの両方を返すようになりました。以前のバージョンではディレクトリだけを返していました。

Path.glob() と rglob() では、パターンの末尾にスラッシュを付けるとディレクトリだけにマッチします。

バージョン 3.11 で変更: パス要素の区切り文字 (sep または altsep) で終わるパターンを使って glob を行うと、ディレクトリだけを返すようになりました。

`glob` モジュールとの比較¶

Path.glob() と Path.rglob() が受け付けるパターンと生成する結果は、glob モジュールとは少し異なります:

pathlib では、名前がドットで始まるファイルを特別扱いしません。これは glob.glob() に include_hidden=True を渡すのと同様です。
pathlib では、パターンの "**" 要素は常に再帰的です。これは glob.glob() に recursive=True を渡すのと同様です。
pathlib では、パターンの "**" 要素はデフォルトでシンボリックリンクをたどりません。 glob.glob() にこの動作に相当するものはありませんが、Path.glob() に recurse_symlinks=True を渡すと互換性のある動作になります。
すべての PurePath オブジェクトや Path オブジェクトと同様に、Path.glob() と Path.rglob() の返り値には末尾のスラッシュは含まれません。
glob.glob(root_dir=path) の結果と異なり、pathlib の path.glob() と path.rglob() の返り値には path が先頭部分として含まれます。
例えば "**" で glob を行うときのように、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 のパスの正規化が、用途によっては適さない場合があります:

pathlib は Path("my_folder/") を Path("my_folder") に正規化しますが、さまざまなオペレーティングシステムの API やコマンドラインユーティリティに渡すときには、これによってパスの意味が変わります。具体的には、末尾の区切り文字がなくなると、ディレクトリだけでなくファイルとしても解決される場合があります。
pathlib は Path("./my_program") を Path("my_program") に正規化しますが、シェルや子プロセスの起動時などで実行可能ファイルの検索パスとして使うときには、これによってパスの意味が変わります。具体的には、パスに区切り文字がなくなると、カレントディレクトリではなく 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()`

脚注

プロトコル¶

pathlib.types モジュールは静的型チェック用の型を提供します。

Added in version 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 を返します。

`pathlib` --- オブジェクト指向のファイルシステムパス¶

基本的な使い方¶

例外¶

純粋パス¶

全般的な性質¶

演算子¶

個別の構成要素へのアクセス¶

メソッドとプロパティ¶

具象パス¶

URIのパースと生成¶

パスの展開と解決¶

ファイルの種類とステータスを問い合わせる¶

ファイルを読み書きする¶

ディレクトリを読む¶

ファイルとディレクトリの作成¶

コピー、移動、削除¶

パーミッションと所有者¶

パターン言語¶

`glob` モジュールとの比較¶

`os` と `os.path` モジュールの比較¶

対応するツール¶

プロトコル¶

目次

前のトピックへ

次のトピックへ

このページ

pathlib --- オブジェクト指向のファイルシステムパス¶

基本的な使い方¶

例外¶

純粋パス¶

全般的な性質¶

演算子¶

個別の構成要素へのアクセス¶

メソッドとプロパティ¶

具象パス¶

URIのパースと生成¶

パスの展開と解決¶

ファイルの種類とステータスを問い合わせる¶

ファイルを読み書きする¶

ディレクトリを読む¶

ファイルとディレクトリの作成¶

コピー、移動、削除¶

パーミッションと所有者¶

パターン言語¶

glob モジュールとの比較¶

os と os.path モジュールの比較¶

対応するツール¶

プロトコル¶

`pathlib` --- オブジェクト指向のファイルシステムパス¶

`glob` モジュールとの比較¶

`os` と `os.path` モジュールの比較¶