このモジュールには、パス名を操作する便利な関数が定義されています。ファイルの読み書きに関しては、 open() 、ファイルシステムへのアクセスに関しては、 os モジュールを参照下さい。
ノート
これらの関数の多くは Windows の一律命名規則 (UNCパス名) を正しくサポートしていません。 splitunc() と ismount() は正しく UNC パス名を操作できます。
ノート
OSによって異なるパスの決まりがあるので、標準ライブラリにはこのモジュールの幾つかのバージョンが含まれています。 os.path モジュールは常に現在 Pythonが動作しているOSに適したパスモジュールで、ローカルのパスを扱うのに適しています。各々のモジュールをインポートして 常に 一つのフォーマットを利用することも可能です。これらは全て同じインタフェースを持っています。:
path の標準化された絶対パスを返します。たいていのプラットフォームでは、 normpath(join(os.getcwd(), path)) と同じ結果になります。
バージョン 1.5.2 で追加.
パス名 path の末尾のファイル名を返します。これは split(path) で返されるペアの2番目の要素です。この関数が返す値は Unix の basename とは異なります; Unix の basename は '/foo/bar/' に対して 'bar' を返しますが、 basename() は空文字列 ('') を返します。
パスの list の中の共通する最長のプレフィックスを (パス名の1文字1 文字を判断して) 返します。もし list が空なら、空文字列 ('') を返します。これは一度に1文字を扱うため、不正なパスを返すことがあるかもしれませんので注意して下さい。
パス path のディレクトリ名を返します。これは split(path) で返されるペアの最初の要素です。
path が存在するなら、 True を返します。壊れたシンボリックリンクについては False を返します。いくつかのプラットフォームでは、たとえ path が物理的に存在していたとしても、リクエストされたファイルに対する os.stat() の実行が許可されなければこの関数が False を返すことがあります。
path が存在するパスなら True を返す。壊れたシンボリックリンクについては True を返します。 os.lstat() がない環境では exists() と同じです。
バージョン 2.4 で追加.
Unix 、および、 Windows では、与えられた引数の先頭のパス要素 ~ 、または ~user を、 user のホームディレクトリのパスに置き換えて返します。
Unix では、先頭の ~ は、環境変数 HOME が設定されているならその値に置き換えられます。そうでなければ、現在のユーザのホームディレクトリをビルトインモジュール pwd を使ってパスワードディレクトリから探して置き換えます。先頭の ~user については、直接パスワードディレクトリから探します。
Windows では ~ だけがサポートされ、環境変数 HOME または HOMEDRIVE と HOMEPATH の組み合わせで置き換えられます。
もし置き換えに失敗したり、引数のパスがチルダで始まっていなかったら、パスをそのまま返します。
引数のパスの環境変数を展開して返します。引数の中の $name または ${name} のような形式の文字列は環境変数、 name に置き換えられます。不正な変数名や存在しない変数名の場合には変換されず、そのまま返します。
Windows では、 $name や ${name} の形式に加えて、 %name% の形式もサポートされています。
path に最後にアクセスした時刻を、エポック (time モジュールを参照下さい) からの経過時間を示す秒数で返します。ファイルが存在しなかったりアクセスできない場合は os.error を送出します。
バージョン 2.3 で変更: os.stat_float_times() が True を返す場合、戻り値は浮動小数 点値となります。
バージョン 1.5.2 で追加.
path の最終更新時刻を、エポック (time モジュールを参照下さい) からの経過時間を示す秒数で返します。ファイルが存在しなかったりアクセスできない場合は os.error を送出します。
バージョン 2.3 で変更: os.stat_float_times() が True を返す場合、戻り値は浮動小数点値となります。
バージョン 1.5.2 で追加.
システムによって、ファイルの最終変更時刻 (Unix のようなシステム) や作成時刻 (Windows のようなシステム) をシステムの ctime で返します。戻り値はエポック (time モジュールを参照下さい) からの経過秒数を示す数値です。ファイルが存在しなかったりアクセスできない場合は os.error を送出します。
バージョン 2.3 で追加.
ファイル path のサイズをバイト数で返します。ファイルが存在しなかったりアクセスできない場合は os.error を送出します。
バージョン 1.5.2 で追加.
path が絶対パスなら、 True を返します。すなわち、 Unix ではスラッシュで始まり、 Windows ではドライブレターに続く (バック) スラッシュで始まる場合です。
path が存在する正しいファイルなら、 True を返します。シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して islink() と isfile() の両方が True を返すことがあります。
path が存在するなら、 True を返します。シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して islink() と isdir() の両方が True を返すことがあります。
path がシンボリックリンクなら、 True を返します。シンボリックリンクがサポートされていないプラットフォームでは、常に False を返します。
パス名 path がマウントポイント mount point (ファイルシステムの中で異なるファイルシステムがマウントされているところ) なら、 True を返します: この関数は path の親ディレクトリである path/.. が path と異なるデバイス上にあるか、あるいは path/.. と path が同じデバイス上の同じ i-node を指しているかをチェックします — これによって全ての Unix と POSIX 標準でマウントポイントが検出できます。
1 つあるいはそれ以上のパスの要素をうまく結合します。付け加える要素に絶対パスがあれば、それより前の要素は (Windows ではドライブ名があればそれも含めて) 全て破棄され、以降の要素を結合します。戻り値は path1 と省略可能な path2 以降を結合したもので、 path2 が空文字列でないなら、ディレクトリの区切り文字 (os.sep) が各要素の間に挿入されます。 Windows では各ドライブに対してカレントディレクトリがあるので、 os.path.join("c:", "foo") によって、 c:\foo ではなく、ドライブ C: 上のカレントディレクトリからの相対パス (c:foo) が返されます。
パス名の大文字、小文字をシステムの標準にします。 Unix と Mac OS X ではそのまま返します。大文字、小文字を区別しないファイルシステムではパス名を小文字に変換します。 Windows では、スラッシュをバックスラッシュに変換します。
パス名を標準化します。余分な区切り文字や上位レベル参照を削除し、 A//B 、 A/B/ 、 A/./B 、 A/foo/../B が全て A/B になるようにします。大文字、小文字は標準化しません (それには normcase() を使って下さい) 。 Windows では、スラッシュをバックスラッシュに変換します。パスがシンボリックリンクを含んでいるかによって意味が変わることに注意してください。
パスの中のシンボリックリンク (もしそれが当該オペレーティングシステムでサポートされていれば)を取り除いて、標準化したパスを返します。
バージョン 2.2 で追加.
カレントディレクトリ、または、オプション引数の start から、 path への相対ファイルパスを返します。
start のデフォルト値は os.curdir です。
利用可能: Windows 、 Unix
バージョン 2.6 で追加.
2つの引数であるパス名が同じファイルあるいはディレクトリを指していれば (同じデバイスナンバーと i-node ナンバーで示されていれば) 、 True を返します。どちらかのパス名で os.stat() の呼び出しに失敗した場合には、例外が発生します。
利用可能: Unix
ファイルディスクリプタ fp1 と fp2 が同じファイルを指していたら、 True を返します。利用可能: Unix
stat タプル stat1 と stat2 が同じファイルを指していたら、 True を返します。これらのタプルは fstat() 、 lstat() や stat() で返されたものでかまいません。この関数は、 samefile() と sameopenfile() で使われるのと同様なものを背後に実装しています。
利用可能: Unix
パス名 path を (head, tail) のペアに分割します。 tail はパスの構成要素の末尾で、 head はそれより前の部分です。 tail はスラッシュを含みません; もし path の最後にスラッシュがあれば、 tail は空文字列になります。もし path にスラッシュがなければ、 head は空文字列になります。 path が空文字列なら、 head と tail のどちらも空文字列になります。 head の末尾のスラッシュは、 head がルートディレクトリ (1つ以上のスラッシュのみ) でない限り、取り除かれます。ほとんど全ての場合、 join(head, tail) の結果が path と等しくなります (ただ1つの例外は、複数のスラッシュが head と tail を分けている時です) 。
パス名 path を (drive, tail) のペアに分割します。 drive はドライブ名か、空文字列です。ドライブ名を使用しないシステムでは、 drive は常に空文字列です。全ての場合に drive + tail は path と等しくなります。
バージョン 1.3 で追加.
パス名 path を (root, ext) のペアにします。 root + ext == path になります。 ext は空文字列か1つのピリオドで始まり、多くても1つのピリオドを含みます。ベースネームを導出するピリオドは無視されます。 ; splitext('.cshrc') は、 ('.cshrc', '') を返します。
バージョン 2.6 で変更: 以前のバージョンでは、最初の文字がピリオドであった場合、空の root を生成していました。
パス名 path をペア (unc, rest) に分割します。ここで unc は (r'\\host\mount' のような) UNC マウントポイント、そして rest は (r'\path\file.ext' のような) パスの残りの部分です。ドライブ名を含むパスでは常に unc が空文字列になります。
利用可能: Windows
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() で必要な操作を実行しなければなりません。
ノート
この関数は廃止予定で、 3.0 では削除されました。 os.walk() が残っています。
任意のユニコード文字列を (ファイルシステムの制限内で) ファイルネームに使うことが可能で、 os.listdir() がユニコード文字列の引数に対してユニコードを返すなら、真を返します。
バージョン 2.3 で追加.