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

This module implements some useful functions on pathnames. To read or
write files see "open()", and for accessing the filesystem see the
"os" module.

注釈: On Windows, many of these functions do not properly support
  UNC pathnames. "splitunc()" and "ismount()" do handle them
  correctly.

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

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

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

  * "ntpath" Windows パス用

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

  * "os2emxpath" for OS/2 EMX paths

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)

   Return the longest path prefix (taken character-by-character) that
   is a prefix of all paths in  *list*.  If *list* is empty, return
   the empty string ("''"). Note that this may return invalid paths
   because it works a character at a time.

os.path.dirname(path)

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

os.path.exists(path)

   Return "True" if *path* refers to an existing path.  Returns
   "False" for broken symbolic links. On some platforms, this function
   may return "False" if permission is not granted to execute
   "os.stat()" on the requested file, even if the *path* physically
   exists.

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)

   Return the time of last access of *path*.  The return value is a
   number giving the number of seconds since the epoch (see the
   "time" module).  Raise "os.error" if the file does not exist or is
   inaccessible.

   バージョン 1.5.2 で追加.

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

os.path.getmtime(path)

   Return the time of last modification of *path*.  The return value
   is a number giving the number of seconds since the epoch (see the
   "time" module). Raise "os.error" if the file does not exist or is
   inaccessible.

   バージョン 1.5.2 で追加.

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

os.path.getctime(path)

   Return the system’s ctime which, on some systems (like Unix) is the
   time of the last metadata change, and, on others (like Windows), is
   the creation time for *path*. The return value is a number giving
   the number of seconds since the epoch (see the  "time" module).
   Raise "os.error" if the file does not exist or is inaccessible.

   バージョン 2.3 で追加.

os.path.getsize(path)

   Return the size, in bytes, of *path*.  Raise "os.error" if the file
   does not exist or is inaccessible.

   バージョン 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)

   Return "True" if pathname *path* is a *mount point*: a point in a
   file system where a different file system has been mounted.  The
   function checks whether *path*’s parent, "path/..", is on a
   different device than *path*, or whether "path/.." and *path* point
   to the same i-node on the same device — this should detect mount
   points for all Unix and POSIX variants.

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)

   Normalize the case of a pathname.  On Unix and Mac OS X, this
   returns the path unchanged; on case-insensitive filesystems, it
   converts the path to lowercase.  On Windows, it also converts
   forward slashes to backward slashes.

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" です。

   Availability:  Windows, Unix.

   バージョン 2.6 で追加.

os.path.samefile(path1, path2)

   Return "True" if both pathname arguments refer to the same file or
   directory (as indicated by device number and i-node number). Raise
   an exception if an "os.stat()" call on either pathname fails.

   Availability: Unix.

os.path.sameopenfile(fp1, fp2)

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

   Availability: Unix.

os.path.samestat(stat1, stat2)

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

   Availability: 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)

   Split the pathname *path* into a pair "(drive, tail)" where *drive*
   is either a drive specification or the empty string.  On systems
   which do not use drive specifications, *drive* will always be the
   empty string.  In all cases, "drive + tail" will be the same as
   *path*.

   バージョン 1.3 で追加.

os.path.splitext(path)

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

   バージョン 2.6 で変更: Earlier versions could produce an empty root
   when the only period was the first character.

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)

   Calls the function *visit* with arguments "(arg, dirname, names)"
   for each directory in the directory tree rooted at *path*
   (including *path* itself, if it is a directory).  The argument
   *dirname* specifies the visited directory, the argument *names*
   lists the files in the directory (gotten from
   "os.listdir(dirname)"). The *visit* function may modify *names* to
   influence the set of directories visited below *dirname*, e.g. to
   avoid visiting certain parts of the tree.  (The object referred to
   by *names* must be modified in place, using "del" or slice
   assignment.)

   注釈: Symbolic links to directories are not treated as
     subdirectories, and that "walk()" therefore will not visit them.
     To visit linked directories you must identify them with
     "os.path.islink(file)" and "os.path.isdir(file)", and invoke
     "walk()" as necessary.

   注釈: This function is deprecated and has been removed in Python
     3 in favor of "os.walk()".

os.path.supports_unicode_filenames

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

   バージョン 2.3 で追加.
