10.1. os.path --- 共通のパス名操作

このモジュールには、パス名を操作する便利な関数が定義されています。ファイルの読み書きに関しては、 open() 、ファイルシステムへのアクセスに関しては、 os モジュールを参照下さい。

注釈

これらの関数の多くは Windows の一律命名規則 (UNC パス名 ) を正しくサポートしていません。 splitunc() と ismount() は正しく UNC パス名を操作できます。

Unix シェルとは異なり、Python はあらゆるパス展開を 自動的には 行いません。アプリケーションがシェルのようなパス展開を必要とした場合は、 expanduser() や expandvars() といった関数を明示的に呼び出すことで行えます。(glob モジュールも参照してください)

注釈

OS によって異なるパス名の決まりがあるため、標準ライブラリにはこのモジュールのいくつかのバージョンが含まれています。 os.path モジュールは常に現在 Python が動作している OS に適したパスモジュールであるため、ローカルのパスを扱うのに適しています。各々のモジュールをインポートして 常に 一つのフォーマットを利用することも可能です。これらはすべて同じインタフェースを持っています:

  • posixpath UNIX スタイルのパス用

  • ntpath Windows パス用

  • macpath 古いスタイルの MacOS パス用

  • os2emxpath OS/2 EMX パス用

os.path.abspath(path)

パス名 path の正規化された絶対パスを返します。ほとんどのプラットフォームでは、これは関数 normpath() を次のように呼び出した時と等価です: normpath(join(os.getcwd(), path))。

バージョン 1.5.2 で追加.

os.path.basename(path)

パス名 path の末尾のファイル名部分を返します。これは関数 split() に path を渡した時に返されるペアの 2 番めの要素です。この関数が返すのは Unix の basename とは異なります; Unix の basename は '/foo/bar/' に対して 'bar' を返しますが、関数 basename() は空文字列 ('') を返します。

os.path.commonprefix(list)

パスの list の中に共通する最長の接頭辞を (パス名の 1 文字 1 文字を判断して) 返します。もし list が空なら、空文字列 ('') を返します。これは一度に 1 文字を扱うため、不正なパスを返すことがあるかもしれないので注意して下さい。

os.path.dirname(path)

パス名 path のディレクトリ名を返します。これは関数 split() に path を渡した時に返されるペアの 1 番めの要素です。

os.path.exists(path)

path が存在するなら、 True を返します。壊れたシンボリックリンクについては False を返します。いくつかのプラットフォームでは、たとえ path が物理的に存在していたとしても、リクエストされたファイルに対する os.stat() の実行が許可されなければこの関数が False を返すことがあります。

os.path.lexists(path)

path が実在するパスなら True を返します。壊れたシンボリックリンクについては True を返します。 os.lstat() がない環境では exists() と等価です。

バージョン 2.4 で追加.

os.path.expanduser(path)

Unix および Windows では、与えられた引数の先頭のパス要素 ~ 、または ~user を、 user のホームディレクトリのパスに置き換えて返します。

Unix では、先頭の ~ は、環境変数 HOME が設定されているならその値に置き換えられます。設定されていない場合は、現在のユーザのホームディレクトリをビルトインモジュール pwd を使ってパスワードディレクトリから探して置き換えます。先頭の ~user については、直接パスワードディレクトリから探します。

Windows では、 HOME と USERPROFILE が設定されていればそれを使用します。設定されていない場合は、環境変数 HOMEPATH と HOMEDRIVE の組み合わせで置き換えられます。先頭の ~user は ~ で得られるユーザパスの最後のディレクトリ要素を除去したものを利用します。

置き換えに失敗したり、引数のパスがチルダで始まっていなかった場合は、パスをそのまま返します。

os.path.expandvars(path)

引数のパスの環境変数を展開して返します。引数の中の $name または ${name} のような形式の文字列は環境変数、 name の値に置き換えられます。不正な変数名や存在しない変数名の場合には変換されず、そのまま返します。

Windows では、 $name や ${name} の形式に加えて、 %name% の形式もサポートされています。

os.path.getatime(path)

path に最後にアクセスした時刻を、エポック (time モジュールを参照下さい ) からの経過時間を示す秒数で返します。ファイルが存在しなかったりアクセスできない場合は os.error を送出します。

バージョン 1.5.2 で追加.

バージョン 2.3 で変更: os.stat_float_times() が True を返す場合、この関数の返り値は浮動小数点数になります。

os.path.getmtime(path)

path の最終更新時刻を、エポック (time モジュールを参照下さい ) からの経過時間を示す秒数で返します。ファイルが存在しなかったりアクセスできない場合は os.error を送出します。

バージョン 1.5.2 で追加.

バージョン 2.3 で変更: os.stat_float_times() が True を返す場合、この関数の返り値は浮動小数点数になります。

os.path.getctime(path)

システムの ctime、Unix系など一部のシステムでは最後にメタデータが変更された時刻、Windows などその他のシステムでは path の作成時刻を返します。返り値はエポック (time モジュールを参照) からの経過時間を示す秒数になります。ファイルが存在しない、あるいはアクセスできなかった場合は os.error を送出します。

バージョン 2.3 で追加.

os.path.getsize(path)

ファイル path のサイズをバイト数で返します。ファイルが存在しなかったりアクセスできない場合は os.error を送出します。

バージョン 1.5.2 で追加.

os.path.isabs(path)

path が絶対パスなら True を返します。すなわち、 Unix ではスラッシュで始まり、 Windows ではドライブレターに続く (バック) スラッシュで始まる場合です。

os.path.isfile(path)

path が実在する一般ファイルなら True を返します。シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して islink() と isfile() の両方が True を返すことがあります。

os.path.isdir(path)

path が実在するディレクトリなら True を返します。シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して islink() と isdir() の両方が True を返すことがあります。

path がシンボリックリンクなら True を返します。Python ランタイムでシンボリックリンクがサポートされていないプラットフォームでは、常に False を返します。

os.path.ismount(path)

パス名 path がマウントポイント mount point (ファイルシステムの中で異なるファイルシステムがマウントされているところ) なら True を返します。この関数は path の親ディレクトリである path/.. が path と異なるデバイス上にあるか、あるいは path/.. と path が同じデバイス上の同じ i-node を指しているかをチェックします --- これによってすべての Unix と POSIX 系システムでマウントポイントが検出できます。

os.path.join(path, *paths)

1 つあるいはそれ以上のパスの要素を賢く結合します。戻り値は path、ディレクトリの区切り文字 (os.sep) を *paths の各パートの(末尾でない場合の空文字列を除いて)頭に付けたもの、これらの結合になります。最後の部分が空文字列の場合に限り区切り文字で終わる文字列になります。付け加える要素に絶対パスがあれば、それより前の要素は全て破棄され、以降の要素を結合します。

Windows の場合は、絶対パスの要素 (たとえば r'\foo') が見つかった場合はドライブレターはリセットされません。要素にドライブレターが含まれていれば、それより前の要素は全て破棄され、ドライブレターがリセットされます。各ドライブに対してカレントディレクトリがあるので、 os.path.join("c:", "foo") によって、 c:\foo ではなく、ドライブ C: 上のカレントディレクトリからの相対パス(c:foo) が返されることに注意してください。

os.path.normcase(path)

パス名の大文字、小文字をシステムの標準にします。 Unix と Mac OS X ではそのまま返します。大文字、小文字を区別しないファイルシステムではパス名を小文字に変換します。 Windows では、スラッシュをバックスラッシュに変換します。

os.path.normpath(path)

パスを正規化します。余分な区切り文字や上位レベル参照を除去し、A//B、A/B/、A/./B や A/foo/../B などはすべて A/B になります。この文字列操作は、シンボリックリンクを含むパスの意味を変えてしまう場合があります。Windows では、スラッシュをバックスラッシュに変換します。大文字小文字の正規化には normcase() を使用してください。

os.path.realpath(path)

パスの中のシンボリックリンク (もしそれが当該オペレーティングシステムでサポートされていれば) を取り除いて、指定されたファイル名を正規化したパスを返します。

バージョン 2.2 で追加.

os.path.relpath(path[, start])

カレントディレクトリあるいはオプションの start ディレクトリからの path への相対パスを返します。これは経路計算で行っており、ファイルシステムにアクセスして path や start の存在や性質を確認することはありません。

start のデフォルト値は os.curdir です。

利用できる環境 : Windows 、 Unix

バージョン 2.6 で追加.

os.path.samefile(path1, path2)

2 つの引数であるパス名が同じファイルあるいはディレクトリを指していれば (同じデバイスナンバーと i-node ナンバーで示されていれば ) 、 True を返します。どちらかのパス名で os.stat() の呼び出しに失敗した場合には、例外が発生します。

利用できる環境: Unix。

os.path.sameopenfile(fp1, fp2)

ファイル記述子 fp1 と fp2 が同じファイルを参照していたら True を返します。

利用できる環境: Unix。

os.path.samestat(stat1, stat2)

stat タプル stat1 と stat2 が同じファイルを参照していれば True を返します。これらのタプルは os.fstat() 、 os.lstat() あるいは os.stat() の返り値で構いません。この関数は samefile() と sameopenfile() を使用した比較に基いて実装しています。

利用できる環境: Unix。

os.path.split(path)

パス名 path を (head, tail) のペアに分割します。 tail はパス名の構成要素の末尾で、 head はそれより前の部分です。 tail はスラッシュを含みません; もし path がスラッシュで終わっていれば tail は空文字列になります。もし path にスラッシュがなければ、 head は空文字になります。 path が空文字なら、 head と tail の両方が空文字になります。 head の末尾のスラッシュは head がルートディレクトリ (または 1 個以上のスラッシュだけ) でない限り取り除かれます。 join(head, tail) は常に path と同じ場所を返しますが、文字列としては異なるかもしれません。関数 dirname(), basename() も参照してください。

os.path.splitdrive(path)

パス名 path を (drive, tail) のペアに分割します。 drive はドライブ名か、空文字列です。ドライブ名を使用しないシステムでは、 drive は常に空文字列です。全ての場合に drive + tail は path と等しくなります。

バージョン 1.3 で追加.

os.path.splitext(path)

パス名 path を (root, ext) のペアに分割します。 root + ext == path になります。 ext は空文字列か 1 つのピリオドで始まり、多くても 1 つのピリオドを含みます。ベースネームを導出するピリオドは無視されます; splitext('.cshrc') は ('.cshrc', '') を返します。

バージョン 2.6 で変更: 以前のバージョンでは、最初の文字がピリオドであった場合、空の root を生成していました。

os.path.splitunc(path)

パス名 path をペア (unc, rest) に分割します。ここで unc は (r'\\host\mount' のような) UNC マウントポイント、そして rest は (r'\path\file.ext' のような) パスの残りの部分です。ドライブレターを含むパスでは常に unc が空文字列になります。

利用できる環境: Windows。

os.path.walk(path, visit, arg)

path をルートとする各ディレクトリに対して (もし path がディレクトリなら path も含みます) 、 (arg, dirname, names) を引数として関数 visit を呼び出します。引数 dirname は訪れたディレクトリを示し、引数 names はそのディレクトリ内のファイルのリスト (os.listdir(dirname) で得られる) です。関数 visit によって names を変更して、 dirname 以下の対象となるディレクトリのセットを変更することもできます。例えば、あるディレクトリツリーだけ関数を適用しないなど。 (names で参照されるオブジェクトは、 del あるいはスライスを使って正しく変更しなければなりません。 )

注釈

ディレクトリへのシンボリックリンクはサブディレクトリとして扱われないので、 walk() による操作対象とはされません。ディレクトリへのシンボリックリンクを操作対象とするには、 os.path.islink(file) と os.path.isdir(file) で識別して、 walk() で必要な操作を実行しなければなりません。

注釈

この関数は廃止予定で、 Python 3 では os.walk() を採用し、こちらは削除されます。

os.path.supports_unicode_filenames

ファイル名に任意の Unicode 文字列を (システムの制限内で) 使用できる場合は True になります。

バージョン 2.3 で追加.