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* を返すことがあります。

os.path.islink(path)

   *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 で追加.
