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

バージョン 3.4 で追加.

ソースコード: Lib/pathlib.py

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

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

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

Unix マシン上で Windows のパスを扱いたいとき (またはその逆)。Unix 上で実行しているときに WindowsPath のインスタンスを作成することはできませんが、PureWindowsPath なら可能になります。
実際に OS にアクセスすることなしにパスを操作するだけのコードを確認したいとき。この場合、純粋クラスのインスタンスを一つ作成すれば、それが OS にアクセスすることはないので便利です。

参考

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

参考

文字列による低水準のパス操作の場合は os.path も使用できます。

11.1.1. 基本的な使い方¶

メインクラスをインポートします:

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

11.1.2. 純粋パス¶

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

class pathlib.PurePath(*pathsegments)¶

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

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

pathsegments の各要素は、部分パスの文字列表現か、文字列を返す os.PathLike インターフェイスを実装しているオブジェクトか、その他の path オブジェクトです。

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

pathsegments が空のとき、現在のディレクトリとみなされます:

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

絶対パスが複数与えられた場合、最後の要素がアンカーとして取られます (os.path.join() の挙動を真似ています):

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

ただし、Windows のパスでは、ローカルルートを変更してもそれまでのドライブ設定は破棄されません:

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

誤ったスラッシュおよび単一ドットは無視されますが、2 個のドット ('..') は、シンボリックリンクのときにパスの意味の変更を意味するため受け付けれられます:

>>> 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')
PurePosixPath('/etc')

pathsegments の指定は PurePath と同じです。

class pathlib.PureWindowsPath(*pathsegments)¶

PurePath のサブクラスです。このパスフレーバーは Windows ファイルシステムパスを表します:

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

pathsegments の指定は PurePath と同じです。

これらクラスはあらゆるシステムコールを行わないため、起動しているシステムにかかわらずインスタンスを作成できます。

11.1.2.1. 全般的な性質¶

パスオブジェクトはイミュータブルでハッシュ可能です。同じフレーバーのパスオブジェクトは比較ならびに順序付け可能です。これらのプロパティは、フレーバーのケースフォールディング (訳注: 比較のために正規化すること、例えば全て大文字にする) のセマンティクスに従います。

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

11.1.2.2. 演算子¶

演算子スラッシュ "/" はパスの追加を行います。os.path.join() と似ています:

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

os.PathLike を実装したオブジェクトが受理できる箇所ならどこでも、パスオブジェクトが使用できます:

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

パスオブジェクトの文字列表現はそのシステム自身の 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 形式が標準的なファイルシステムパス表現になります。

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

パスの個別の "構成要素" へアクセスするには、以下のプロパティを使用します:

PurePath.parts¶

パスのさまざまな構成要素へのアクセス手段を提供するタプルになります:

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

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

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

11.1.2.4. メソッドとプロパティ¶

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

PurePath.drive¶

ドライブ文字または名前を表す文字列があればそれになります:

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

UNC 共有名もドライブとみなされます:

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

PurePath.root¶

ローカルまたはグローバルルートを表す文字列があればそれになります:

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

UNC 共有名は常にルートを持ちます:

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

PurePath.anchor¶

ドライブとルートを結合した文字列になります:

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

PurePath.parents¶

パスの論理的な上位パスにアクセスできるイミュータブルなシーケンスになります:

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

PurePath.parent¶

パスの論理的な上位パスになります:

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

アンカーの位置を超えることや空のパスになる位置には対応していません:

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

注釈

これは純粋な字句操作であるため、以下のような挙動になります:

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

任意のファイルシステムパスを上位方向に移動したい場合、シンボリックリンクの解決や ".." 要素の除去のため、最初に Path.resolve() を呼ぶことを推奨します。

PurePath.name¶

パス要素の末尾を表す文字列があればそれになります。ドライブやルートは含まれません:

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

UNC ドライブ名は考慮されません:

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

PurePath.suffix¶

末尾の要素に拡張子があればそれになります:

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

PurePath.suffixes¶

パスのファイル拡張子のリストになります:

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

PurePath.stem¶

パス要素の末尾から拡張子を除いたものになります:

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

PurePath.as_posix()¶

フォワードスラッシュ (/) を使用したパスを表す文字列を返します:

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

PurePath.as_uri()¶

file URI で表したパスを返します。絶対パスではない場合に ValueError を送出します。

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

PurePath.is_absolute()¶

パスが絶対パスかどうかを返します。パスが絶対パスとみなされるのは、ルートと (フレーバーが許す場合) ドライブとの両方が含まれる場合です:

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

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

PurePath.is_reserved()¶

PureWindowsPath の場合はパスが Windows 上で予約されていれば True を返し、そうでなければ False を返します。PurePosixPath の場合は常に False を返します。

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

ファイルシステムで予約されたパスを呼び出すと、原因不明で失敗したり、予期せぬ結果になります。

PurePath.joinpath(*other)¶

このメソッドの呼び出しは引数 other を順々に繋げることと等価になります:

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

PurePath.match(pattern)¶

現在のパスが glob 形式で与えられたパターンと一致したら True を、一致しなければ False を返します。

pattern が相対表記であればパスは相対および絶対パスを取ることができ、右から一致を調べます:

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

pattern が絶対表記であれば、パスは絶対パスでなければならず、パス全体が一致しなければなりません:

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

他のメソッドと同様に、大文字小文字の区別はフレーバーに依存します:

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

PurePath.relative_to(*other)¶

other で表されたパスから現在のパスへの相対パスを返します。それが不可能だった場合は ValueError が送出されます:

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

PurePath.with_name(name)¶

現在のパスの name 部分を変更したパスを返します。オリジナルパスに name 部分がない場合は ValueError が送出されます:

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

PurePath.with_suffix(suffix)¶

現在のパスの 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')

11.1.3. 具象パス¶

具象パスは純粋パスクラスのサブクラスです。純粋パスが提供する操作に加え、パスオブジェクト上でシステムコールを呼ぶメソッドも提供しています。具象パスのインスタンスを作成するには 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')
PosixPath('/etc')

pathsegments の指定は PurePath と同じです。

class pathlib.WindowsPath(*pathsegments)¶

Path および PureWindowsPath のサブクラスで、Windows ファイルシステムの具象パスを表します:

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

pathsegments の指定は PurePath と同じです。

インスタンスを作成できるのはシステムと一致するフレーバーのみです (互換性のないパスフレーバーでのシステムコールの許可はバグやアプリケーションの異常終了の原因になります):

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

11.1.3.1. メソッド¶

具象パスは純粋パスに加え、以下のメソッドを提供します。これらメソッドの多くはシステムコールが失敗すると OSError を送出します (例えばパスが存在しない場合):

classmethod Path.cwd()¶

(os.getcwd() が返す) 現在のディレクトリを表す新しいパスオブジェクトを返します:

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

classmethod Path.home()¶

ユーザーのホームディレクトリ (os.path.expanduser() での ~ の返り値) を表す新しいパスオブジェクトを返します:

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

バージョン 3.5 で追加.

Path.stat()¶

(os.stat() と同様の) 現在のパスに関する情報を返します。値はそれぞれのメソッドを呼び出した時点のものになります。

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

Path.chmod(mode)¶

os.chmod() のようにファイルのモードとアクセス権限を変更します:

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

Path.exists()¶

パスが既存のファイルかディレクトリを指しているかどうかを返します:

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

注釈

パスがシンボリックリンクを指している場合、exists() はシンボリックリンクが既存のファイルかディレクトリを指しているかどうかを返します。

Path.expanduser()¶

パス要素 ~ および ~user を os.path.expanduser() が返すように展開した新しいパスオブジェクトを返します:

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

バージョン 3.5 で追加.

Path.glob(pattern)¶

現在のパスが表すディレクトリ内で pattern に一致する (あらゆる種類の) すべてのファイルを yield します:

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

パターン "**" は "このディレクトリおよびすべてのサブディレクトリを再帰的に走査" を意味します。言い換えれば、再帰的な Glob 走査が可能という意味です:

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

注釈

パターン "**" を大きなディレクトリツリーで使用するととてつもなく時間がかかるかもしれません。

Path.group()¶: ファイルを所有するグループ名を返します。ファイルの GID がシステムのデータベースに見つからなかった場合は KeyError が送出されます。

Path.is_dir()¶

パスがディレクトリ (またはディレクトリへのシンボリックリンク) を指していた場合 True を返し、その他の種類のファイルだった場合 False を返します。