11.2. "os.path" --- 共通のパス名操作
************************************

**ソースコード:** Lib/posixpath.py (POSIX), Lib/ntpath.py (Windows
NT), Lib/macpath.py (Mac)

======================================================================

このモジュールには、パス名を操作する便利な関数が実装されています。ファ
イルの読み書きに関しては "open()" を、ファイルシステムへのアクセスに関
しては "os" モジュールを参照してください。パスパラメータは文字列または
バイト列で渡すことができます。アプリケーションは、ファイル名を Unicode
文字列で表すことが推奨されています。残念ながら、Unix では文字列で表す
ことのできないファイル名があるため、Unix 上で任意のファイル名をサポー
トする必要のあるアプリケーションは、そのパス名にバイト列を使用すべきで
す。逆に、バイト列オブジェクトを使用すると Windows (標準の "mbcs" エン
コーディング) 上ではすべてのファイル名を表すことができないため、
Windows アプリケーションはファイルアクセスのために文字列オブジェクトを
使用するべきです。

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

参考: "pathlib" モジュールは高水準のパスオブジェクトを提供します。

注釈:

  以下のすべての関数は、そのパラメータにバイト列のみ、あるいは文字列の
  み受け付けます。パスまたはファイル名を返す場合、返り値は同じ型のオブ
  ジェクトになります。

注釈:

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

  * "posixpath" UNIX スタイルのパス用

  * "ntpath" Windows パス用

  * "macpath" 古いスタイルの MacOS パス用

os.path.abspath(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.basename(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.commonpath(paths)

   シーケンス *paths* 中の各パス名に共通するサブパスのうち、最も長いも
   のを返します。*paths* に絶対パス名と相対パス名の両方が含まれている
   か、*paths* が空の場合、 ValueError を送出します。"commonprefix()"
   とは異なり、有効なパスを返します。

   利用できる環境 : Unix, Windows

   バージョン 3.5 で追加.

   バージョン 3.6 で変更: *path-like objects* のシーケンスを受け入れる
   ようになりました。

os.path.commonprefix(list)

   *list* 内のすべてのパスに共通する接頭辞のうち、最も長いものを (パス
   名の 1 文字 1 文字を判断して) 返します。*list* が空の場合、空文字列
   ("''") を返します。

   注釈:

     この関数は一度に 1 文字ずつ処理するため、不正なパスを返す場合があ
     ります。有効なパスを取得するためには、"commonpath()" を参照してく
     ださい。

        >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
        '/usr/l'

        >>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
        '/usr'

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.dirname(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.exists(path)

   *path* が実在するパスかオープンしているファイル記述子を参照している
   場合 "True" を返します。壊れたシンボリックリンクについては "False"
   を返します。一部のプラットフォームでは、たとえ *path* が物理的に存
   在していたとしても、要求されたファイルに対する "os.stat()" の実行権
   がなければこの関数が "False" を返すことがあります。

   バージョン 3.3 で変更: *path* は整数でも可能になりました: それがオ
   ープンしているファイル記述子なら "True" が返り、それ以外なら
   "False" が返ります。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.lexists(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.expanduser(path)

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

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

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

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.expandvars(path)

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

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.getatime(path)

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

   "os.stat_float_times()" が "True" を返す場合、この関数の返り値は浮
   動小数点数になります。

os.path.getmtime(path)

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

   "os.stat_float_times()" が "True" を返す場合、この関数の返り値は浮
   動小数点数になります。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.getctime(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.getsize(path)

   *path* のサイズをバイト数で返します。ファイルが存在しない、あるいは
   アクセスできなかった場合は "OSError" を送出します。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.isabs(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.isfile(path)

   *path* が "存在する" 一般ファイルなら "True" を返します。 この関数
   はシンボリックリンクの先を辿るので、同じパスに対して "islink()" と
   "isfile()" の両方が真を返すことがあります。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.isdir(path)

   *path* が "存在する" ディレクトリなら "True" を返します。 この関数
   はシンボリックリンクの先を辿るので、同じパスに対して "islink()" と
   "isdir()" の両方が真を返すことがあります。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.islink(path)

   *path* が "存在する" ディレクトリを指すシンボリックリンクなら
   "True" を返します。 Python ランタイムがシンボリックリンクをサポート
   していないプラットフォームでは、常に "False" を返します。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.ismount(path)

   パス名 *path* がマウントポイント *mount point* (ファイルシステムの
   中で異なるファイルシステムがマウントされているところ) なら、 "True"
   を返します。POSIX では、この関数は *path* の親ディレクトリである
   "path/.." が *path* と異なるデバイス上にあるか、あるいは "path/.."
   と *path* が同じデバイス上の同じ i-node を指しているかをチェックし
   ます --- これによって全ての Unix 系システムと POSIX 標準でマウント
   ポイントが検出できます。Windows では、ドライブレターを持つルートと
   共有 UNC は常にマウントポイントであり、また他のパスでは、入力のパス
   が異なるデバイスからのものか見るために "GetVolumePathName" が呼び出
   されます。

   バージョン 3.4 で追加: Windows での、ルートでないマウントポイントの
   検出をサポートするようになっています。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.join(path, *paths)

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

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

   バージョン 3.6 で変更: *path* と *paths* が *path-like object* を受
   け付けるようになりました。

os.path.normcase(path)

   パス名の大文字・小文字を正規化します。Unix および Mac OS X では変更
   せずに返します。大文字と小文字を区別しないファイルシステムでは小文
   字に変換します。Windows では、スラッシュをバックスラッシュに変換し
   ます。*path* が "str" あるいは "bytes" ではない場合、TypeError を送
   出します(直接的または間接的な "os.PathLike" インタフェース)。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.normpath(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.realpath(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.relpath(path, start=os.curdir)

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

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

   利用できる環境 : Unix 、 Windows 。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.samefile(path1, path2)

   引数の両パス名が同じファイルまたはディレクトリを参照している場合、
   "True" を返します。これは、デバイス番号と i-node 番号で決定されます
   。どちらかのパス名への "os.stat()" 呼び出しが失敗した場合、例外が送
   出されます。

   利用できる環境 : Unix 、 Windows 。

   バージョン 3.2 で変更: Windows サポートを追加しました。

   バージョン 3.4 で変更: Windows が他のプラットフォームと同じ実装を使
   用するようになりました。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.sameopenfile(fp1, fp2)

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

   利用できる環境 : Unix 、 Windows 。

   バージョン 3.2 で変更: Windows サポートを追加しました。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.samestat(stat1, stat2)

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

   利用できる環境 : Unix 、 Windows 。

   バージョン 3.4 で変更: Windows サポートを追加しました。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

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()" も参照してください。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.splitdrive(path)

   パス名 *path* を "(drive, tail)" のペアに分割します。*drive* はマウ
   ントポイントか空文字列になります。ドライブ指定をサポートしていない
   システムでは、*drive* は常に空文字になります。どの場合でも、"drive
   + tail" は *path* と等しくなります。

   Windows では、パス名はドライブ名/UNC 共有ポイントと相対パスに分割さ
   れます。

   パスがドライブレターを含む場合、ドライブレターにはコロンまでが含ま
   れます。例えば、"splitdrive("c:/dir")" は "("c:", "/dir")" を返しま
   す。

   パスが UNC パスを含む場合、ドライブレターにはホスト名と共有名までが
   含まれますが、共有名の後の区切り文字は含まれません。例えば、
   "splitdrive("//host/computer/dir")" は "("//host/computer",
   "/dir")" を返します。

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.splitext(path)

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

   バージョン 3.6 で変更: *path-like object* を受け入れるようになりま
   した。

os.path.splitunc(path)

   バージョン 3.1 で非推奨: 代わりに *splitdrive* を使ってください。

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

   利用できる環境: Windows。

os.path.supports_unicode_filenames

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