\section{\module{os.path} ---
共通のパス名操作}
\declaremodule{standard}{os.path}

\modulesynopsis{
共通のパス名操作。}

このモジュールには、パス名を操作する便利な関数が定義されています。

\index{path!operations}

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

\begin{funcdesc}{abspath}{path}
\var{path}の標準化された絶対パスを返します。
たいていのプラットフォームでは、
\code{normpath(join(os.getcwd(), \var{path}))}と同じ結果になります。
\versionadded{1.5.2}
\end{funcdesc}

\begin{funcdesc}{basename}{path}
パス名\var{path}の末尾のファイル名を返します。
これは\code{split(\var{path})}で返されるペアの２番目の要素です。
この関数が返す値は\UNIX{}の \program{basename}とは異なります；
\UNIX{}の\program{basename}は\code{'/foo/bar/'}に対して
\code{'bar'}を返しますが、\function{basename()}は空文字列(\code{''})
を返します。
\end{funcdesc}

\begin{funcdesc}{commonprefix}{list}
パスの\var{list}の中の共通する最長のプレフィックスを（パス名の１文字１文
字を判断して）返します。
もし\var{list}が空なら、空文字列(\code{''})を返します。
これは一度に１文字を扱うため、不正なパスを返すことがあるかもしれませんの
で注意して下さい。
\end{funcdesc}

\begin{funcdesc}{dirname}{path}
パス\var{path}のディレクトリ名を返します。
これは\code{split(\var{path})}で返されるペアの最初の要素です。
\end{funcdesc}

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

\begin{funcdesc}{lexists}{path}
\var{path} が存在するパスなら\code{True} を返す。
壊れたシンボリッックリンクについては\code{True}を返します。
\function{os.lstat()}がない環境では\function{exists()}と同じです。
\versionadded{2.4}
\end{funcdesc}


\begin{funcdesc}{expanduser}{path}
\UNIX では、
与えられた引数の先頭のパス要素\samp{\~}または\samp{\~\var{user}}を、
\var{user}のホームディレクトリのパスに置き換えて返します。
先頭の\samp{\~}は、環境変数\envvar{HOME}が設定されているならその値に置き換えられます。
そうでなければ、現在のユーザのホームディレクトリをビルトインモジュール
\refmodule{pwd}\refbimodindex{pwd}を使ってパスワードディレクトリ
から探して置き換えます。
先頭の\samp{\~\var{user}}については、直接パスワードディレクトリから探します。

Windows では\samp{\~}だけがサポートされ、環境変数\envvar{HOME}または
\envvar{HOMEDRIVE}と\envvar{HOMEPATH}の組み合わせで置き換えられます。

もし置き換えに失敗したり、引数のパスがチルダで始まっていなかったら、パス
をそのまま返します。
\end{funcdesc}

\begin{funcdesc}{expandvars}{path}
引数のパスを環境変数に展開して返します。
引数の中の\samp{\$\var{name}}または\samp{\$\{\var{name}\}}の文字列が
環境変数の\var{name}に置き換えられます。
不正な変数名や存在しない変数名の場合には変換されず、そのまま返します。
\end{funcdesc}

\begin{funcdesc}{getatime}{path}
\var{path}に最後にアクセスした時刻を、エポック（\refmodule{time}モジュール
を参照）からの経過時間を示す秒数で返します。
ファイルが存在しなかったりアクセスできない場合は\exception{os.error}を発
生します。
\versionchanged[\function{os.stat_float_times()}がTrueを返す場合、戻り値は
浮動小数点値となります。]{2.3}
\versionadded{1.5.2}
\end{funcdesc}

\begin{funcdesc}{getmtime}{path}
\var{path}の最終更新時刻を、エポック（\refmodule{time}モジュールを参照）
からの経過時間を示す秒数で返します。
ファイルが存在しなかったりアクセスできない場合は\exception{os.error}を発
生します。
\versionchanged[\function{os.stat_float_times()}がTrueを返す場合、戻り値は
浮動小数点値となります。]{2.3}
\versionadded{1.5.2}
\end{funcdesc}

\begin{funcdesc}{getctime}{path}
システムによって、ファイルの最終変更時刻 (\UNIX{} のような システム) や
作成時刻 (Windows のようなシステム) をシステムの ctime で返します。
戻り値はエポック（\refmodule{time}モジュールを参照）からの経過秒数を
示す数値です。
ファイルが存在しなかったりアクセスできない場合は\exception{os.error}を発
生します。
\versionadded{2.3}
\end{funcdesc}


\begin{funcdesc}{getsize}{path}
ファイル\var{path}のサイズをバイト数で返します。
ファイルが存在しなかったりアクセスできない場合は\exception{os.error}を発
生します。
\versionadded{1.5.2}
\end{funcdesc}

\begin{funcdesc}{isabs}{path}
\var{path}が絶対パス（スラッシュで始まる）なら、\code{True}を返します。
\end{funcdesc}

\begin{funcdesc}{isfile}{path}
\var{path}が存在する正しいファイルなら、\var{True}を返します。
シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して
\function{islink()}と\function{isfile()}の両方が\var{True}を返すことがあ
ります。
\end{funcdesc}

\begin{funcdesc}{isdir}{path}
\var{path}が存在するなら、\code{True}を返します。
シンボリックリンクの場合にはその実体をチェックするので、同じパスに対して
\function{islink()}と\function{isfile()}の両方が\var{True}を返すことがあ
ります。
\end{funcdesc}

\begin{funcdesc}{islink}{path}
\var{path}がシンボリックリンクなら、\code{True}を返します。
シンボリックリンクがサポートされていないプラットフォームでは、常に
\code{False}を返します。
\end{funcdesc}

\begin{funcdesc}{ismount}{path}
パス名\var{path}がマウントポイント\dfn{mount point}（ファイルシステムの
中で異なるファイルシステムがマウントされているところ）なら、\code{True}
を返します：
この関数は\var{path}の親ディレクトリである\file{\var{path}/..}が
\var{path}と異なるデバイス上にあるか、あるいは\file{\var{path}/..}と
\var{path}が同じデバイス上の同じi-nodeを指しているかをチェックします---
これによって全ての\UNIX{}と\POSIX{}標準でマウントポイントが検出できま
す。
\end{funcdesc}

\begin{funcdesc}{join}{path1\optional{, path2\optional{, ...}}}
１つあるいはそれ以上のパスの要素をうまく結合します。
付け加える要素に絶対パスがあれば、それより前の要素は(Windows ではドライブ名
があればそれも含めて)全て破棄され、以降の要素を結合します。
戻り値は\var{path1}と省略可能な\var{path2}以降を結合したもので、
\var{path2}が空文字列でないなら、ディレクトリの区切り文字(\code{os.sep})
が各要素の間に挿入されます。
Windowsでは各ドライブに対してカレントディレクトリがあるので、
\function{os.path.join("c:", "foo")}によって、
\file{c:\textbackslash\textbackslash foo}ではなく、ドライブ\file{C:}上の
カレントディレクトリからの相対パス（\file{c:foo}）が返されます。
\end{funcdesc}

\begin{funcdesc}{normcase}{path}
パス名の大文字、小文字をシステムの標準にします。
\UNIX{}ではそのまま返します。大文字、小文字を区別しないファイルシステム
ではパス名を小文字に変換します。
Windowsでは、スラッシュをバックスラッシュに変換します。
\end{funcdesc}

\begin{funcdesc}{normpath}{path}
パス名を標準化します。
余分な区切り文字や上位レベル参照を削除し、\code{A//B}、
\code{A/./B}、\code{A/foo/../B}が全て\code{A/B}になるようにします。
大文字、小文字は標準化しません（それには\function{normcase()}を使って下
さい）。
Windowsでは、スラッシュをバックスラッシュに変換します。
パスがシンボリックリンクを含んでいるかによって意味が変わることに注意し
てください。
\end{funcdesc}

\begin{funcdesc}{realpath}{path}
パスの中のシンボリックリンク(もしそれが当該オペレーティングシステムで
サポートされていれば)を取り除いて、標準化したパスを返します。
\versionadded{2.2}
\end{funcdesc}

\begin{funcdesc}{samefile}{path1, path2}
２つの引数であるパス名が同じファイルあるいはディレクトリを指していれば（
同じデバイスナンバーとi-nodeナンバーで示されていれば）、\code{True}を返
します。
どちらかのパス名で\function{os.stat()}の呼び出しに失敗した場合には、例外
が発生します。
利用可能：Macintosh、\UNIX
\end{funcdesc}

\begin{funcdesc}{sameopenfile}{fp1, fp2}
ファイルディスクリプタ\var{fp1}と\var{fp2}が同じファイルを指していたら、
\code{True}を返します。
利用可能：Macintosh、\UNIX
\end{funcdesc}

\begin{funcdesc}{samestat}{stat1, stat2}
statタプル\var{stat1}と\var{stat2}が同じファイルを指していたら、
\code{True}を返します。
これらのタプルは\function{fstat()}、\function{lstat()}や
\function{stat()}で返されたものでかまいません。
この関数は、\function{samefile()}と\function{sameopenfile()}で使われるの
と同様なものを背後に実装しています。
利用可能：Macintosh、\UNIX
\end{funcdesc}

\begin{funcdesc}{split}{path}
パス名\var{path}を\code{(\var{head}と\var{tail})}のペアに分割します。
\var{tail}はパスの構成要素の末尾で、\var{head}はそれより前の部分です。
\var{tail}はスラッシュを含みません；もし\var{path}の最後にスラッシュがあ
れば、\var{tail}は空文字列になります。
もし\var{path}にスラッシュがなければ、\var{head}は空文字列になります。
\var{path}が空文字列なら、\var{head}と\var{tail}のどちらも空文字列になり
ます。
\var{head}の末尾のスラッシュは、\var{head}がルートディレクトリ（１つ以上
のスラッシュのみ）でない限り、取り除かれます。
ほとんど全ての場合、\code{join(\var{head}, \var{tail})}の結果が
\var{path}と等しくなります（ただ１つの例外は、複数のスラッシュが
\var{head}と\var{tail}を分けている時です）。
\end{funcdesc}

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

\begin{funcdesc}{splitext}{path}
パス名\var{path}を\code{(\var{root}, \var{ext})}のペアにします。
\code{\var{root} + \var{ext} == \var{path}}になります。
\var{ext}は空文字列か１つのピリオドで始まり、多くても１つのピリオドを含
みます。
\end{funcdesc}

\begin{funcdesc}{splitunc}{path}
パス名\var{path}をペア \code{(\var{unc}, \var{rest})} に分割します。
ここで\var{unc}は(\code{r'\e\e host\e mount'}のような)UNCマウントポイント、
そして\var{rest}は(\code{r'\e path\e file.ext'}のような)パスの残りの部分です。
ドライブ名を含むパスでは常に\var{unc}が空文字列になります。
利用可能:  Windows。
\end{funcdesc}

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

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

\note{新たに追加された\function{\refmodule{os}.walk()} ジェネレータを
使用すれば、同じ処理をより簡単に行う事ができます。}
\end{funcdesc}

\begin{datadesc}{supports_unicode_filenames}
任意のユニコード文字列を（ファイルシステムの制限内で）
ファイルネームに使うことが可能で、\function{os.listdir}がユニコード文字列の
引数に対してユニコードを返すなら、真を返します。
\versionadded{2.3}
\end{datadesc}

