"shutil" --- 高水準のファイル操作
*********************************

**ソースコード:** Lib/shutil.py

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

"shutil" モジュールは、ファイルやファイルの集合に対するさまざまな高水
準の操作を提供します。 特に、ファイルのコピーや削除を行う関数が用意さ
れています。 個々のファイルを操作する場合は "os" モジュールも参照して
ください。

警告:

  高水準のファイルコピー関数 ("shutil.copy()", "shutil.copy2()") でも
  、ファイルのメタデータの全てをコピーすることはできません。POSIXプラ
  ットフォームでは、これはACLやファイルのオーナー、グループが失われる
  ことを意味しています。 Mac OSでは、リソースフォーク(resource fork)や
  その他のメタデータが利用されません。これは、リソースが失われ、ファイ
  ルタイプや生成者コード(creator code)が正しくなくなることを意味してい
  ます。 Windowsでは、ファイルオーナー、ACL、代替データストリームがコ
  ピーされません。


ディレクトリとファイルの操作
============================

shutil.copyfileobj(fsrc, fdst[, length])

   *file-like object* *fsrc* の内容を *fdst* へコピーします。 整数値
   *length* は与えられた場合バッファサイズを表します。 特に *length*
   が負の場合、コピー元のデータをチャンク単位で繰り返し読み込むことな
   く、一度にコピーします。 デフォルトでは、制御不能なメモリ消費を避け
   るためにデータはチャンク単位で読み込まれます。 *fsrc* オブジェクト
   の現在のファイル位置が0でない場合、現在の位置からファイル終端までの
   内容のみがコピーされることに注意してください。

   "copyfileobj()" は、コピー完了時にコピー先のストリームがフラッシュ
   されていることを保証 *しません*。 コピー直後にコピー先を読み込みた
   い場合 (例えば HTTP ストリームからコピーした一時ファイルの内容を読
   み込む場合) は、読み込む前にファイルに似たオブジェクトの "flush()"
   または "close()" を必ず呼び出してください。

shutil.copyfile(src, dst, *, follow_symlinks=True)

   *src* という名前のファイルの内容 (メタデータを含まない) を *dst* と
   いう名前のファイルに、できるだけ効率的な方法でコピーし、*dst* を返
   します。 *src* と *dst* は *path-like object* または文字列でパス名
   を指定します。

   *dst* は完全な対象ファイル名でなければなりません。対象としてディレ
   クトリ名を指定したい場合は "copy()" を参照してください。 *src* と
   *dst* が同じファイルだった場合、 "SameFileError" を送出します。

   *dst* は書き込み可能でなければなりません。そうでない場合、
   "OSError" 例外を送出します。 *dst* がすでに存在する場合、そのファイ
   ルは置き換えられます。キャラクタデバイスやブロックデバイスなどの特
   殊なファイルとパイプをこの関数でコピーすることはできません。

   *follow_symlinks* が偽で *src* がシンボリックリンクの場合、 *src*
   のリンク先をコピーする代わりに新しいシンボリックリンクを作成します
   。

   引数 "src", "dst" を指定して 監査イベント "shutil.copyfile" を送出
   します。

   バージョン 3.3 で変更: 以前は "OSError" の代わりに "IOError" が送出
   されていました。 *follow_symlinks* 引数が追加されました。 *dst* を
   返すようになりました。

   バージョン 3.4 で変更: "Error" の代わりに "SameFileError" を送出し
   ます。後者は前者のサブクラスなのでこの変更は後方互換です。

   バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラ
   ットフォーム特有の高速なコピーを行うシステムコールが利用されること
   があります。 プラットフォーム依存の効率的なコピー操作 を参照してく
   ださい。

exception shutil.SpecialFileError

   "copyfile()" または "copytree()" が名前付きパイプをコピーしようとし
   たときに送出される例外です。

   Added in version 2.7.

exception shutil.SameFileError

   "copyfile()" のコピー元と先が同じファイルの場合送出されます。

   Added in version 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)

   パーミッションを *src* から *dst* にコピーします。ファイルの内容、
   オーナー、グループには影響しません。 *src* と *dst* は *path-like
   object* または文字列でファイルのパス名を指定します。
   *follow_symlinks* が偽で、*src* および *dst* がシンボリックリンクの
   場合、 "copymode()" は (リンク先ではなく)  *dst* 自体のモードを変更
   します。この機能は全てのプラットフォームで使えるわけではありません
   。詳しくは "copystat()" を参照してください。シンボリックリンクの変
   更をしようとした時、 "copymode()" がローカルのプラットフォームでシ
   ンボリックリンクを変更できない場合は何もしません。

   引数 "src", "dst" を指定して 監査イベント "shutil.copymode" を送出
   します。

   バージョン 3.3 で変更: *follow_symlinks* 引数が追加されました。

shutil.copystat(src, dst, *, follow_symlinks=True)

   パーミッション、最終アクセス時間、最終変更時間、その他のフラグを
   *src* から *dst* にコピーします。 Linux では、 "copystat()" は可能
   なら "拡張属性" もコピーします。ファイルの内容、オーナー、グループ
   には影響しません。 *src* と *dst* は *path-like object* または文字
   列でファイルのパス名を指定します。

   *follow_symlinks* が偽の場合、 *src* と *dst* の両方がシンボリック
   リンクであれば、 "copystat()" はリンク先ではなくてシンボリックリン
   ク自体を操作します。 *src* からシンボリックリンクの情報を読み込み、
   *dst* のシンボリックリンクにその情報を書き込みます。

   注釈:

     すべてのプラットフォームでシンボリックリンクの検査と変更ができる
     わけではありません。 Python はその機能が利用かどうかを調べる方法
     を用意しています。

     * "os.chmod in os.supports_follow_symlinks" が "True" の場合
       "copystat()" はシンボリックリンクのパーミッションを変更できます
       。

     * "os.utime in os.supports_follow_symlinks" が "True" の場合
       "copystat()" はシンボリックリンクの最終アクセス時間と最終変更時
       間を変更できます。

     * "os.chflags in os.supports_follow_symlinks" が "True" の場合
       "copystat()" はシンボリックリンクのフラグを変更できます。
       ("os.chflags" がないプラットフォームもあります。)

     機能の幾つか、もしくは全てが利用できないプラットフォームでシンボ
     リックリンクを変更しようとした場合、 "copystat()" は可能な限り全
     てをコピーします。"copystat()" が失敗を返すことはありません。より
     詳しい情報は "os.supports_follow_symlinks" を参照して下さい。

   引数 "src", "dst" を指定して 監査イベント "shutil.copystat" を送出
   します。

   バージョン 3.3 で変更: *follow_symlinks* 引数と Linux の拡張属性が
   サポートされました。

shutil.copy(src, dst, *, follow_symlinks=True)

   ファイル *src* をファイルまたはディレクトリ *dst* にコピーします。
   *src* と *dst* は両方共 *path-like object* または文字列でなければな
   りません。 *dst* がディレクトリを指定している場合、ファイルは *dst*
   の中に、 *src* のベースファイル名を使ってコピーされます。*dst* が既
   に存在するファイルを指定している場合、それは置き換えられます。新し
   く作成したファイルのパスを返します。

   *follow_symlinks* が偽で、 *src* がシンボリックリンクの場合、 *dst*
   はシンボリックリンクとして作成されます。 *follow_symlinks* が真で
   *src* がシンボリックリンクの場合、 *dst* には *src* のリンク先のフ
   ァイルがコピーされます。

   "copy()" はファイルのデータとパーミッションをコピーします。
   ("os.chmod()" を参照) その他の、ファイルの作成時間や変更時間などの
   メタデータはコピーしません。 コピー元のファイルのメタデータを保存し
   たい場合は、 "copy2()" を利用してください。

   引数 "src", "dst" を指定して 監査イベント "shutil.copyfile" を送出
   します。

   引数 "src", "dst" を指定して 監査イベント "shutil.copymode" を送出
   します。

   バージョン 3.3 で変更: *follow_symlinks* 引数が追加されました。新し
   く作成されたファイルのパスを返すようになりました。

   バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラ
   ットフォーム特有の高速なコピーを行うシステムコールが利用されること
   があります。 プラットフォーム依存の効率的なコピー操作 を参照してく
   ださい。

shutil.copy2(src, dst, *, follow_symlinks=True)

   "copy2()" はファイルのメタデータを保持しようとすることを除けば
   "copy()" と等価です。

   *follow_symlinks* が偽でかつ *src* がシンボリックリンクの場合、
   "copy2()" は *src* シンボリックリンク全てのメタデータを新たに作成さ
   れる *dst* シンボリックリンクにコピーしようとします。しかし、この機
   能は全てのプラットフォームで利用可能なわけではありません。この機能
   の全部または一部が利用可能でないプラットフォームにおいては、
   "copy2()" は可能な限りのメタデータを保存しようとしますが、一方で
   "copy2()"　はメタデータを保存できないことを理由とする例外を送出しま
   せん。

   "copy2()" はファイルのメタデータをコピーするために "copystat()" を
   利用します。シンボリックリンクのメタデータを変更するためのプラット
   フォームサポートについては "copystat()" を参照して下さい。

   引数 "src", "dst" を指定して 監査イベント "shutil.copyfile" を送出
   します。

   引数 "src", "dst" を指定して 監査イベント "shutil.copystat" を送出
   します。

   バージョン 3.3 で変更: *follow_symlinks* 引数が追加されました。 拡
   張ファイルシステム属性もコピーしようと試みます (現在は Linux のみ)
   。新しく作成されたファイルへのパスを返すようになりました。

   バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラ
   ットフォーム特有の高速なコピーを行うシステムコールが利用されること
   があります。 プラットフォーム依存の効率的なコピー操作 を参照してく
   ださい。

shutil.ignore_patterns(*patterns)

   このファクトリ関数は、 "copytree()" 関数の *ignore* 引数に渡すため
   の呼び出し可能オブジェクトを作成します。 glob形式の *patterns* にマ
   ッチするファイルやディレクトリが無視されます。下の例を参照してくだ
   さい。

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

   *src* をルートとするディレクトリツリー全体を *dst* というディレクト
   リに再帰的にコピーし、コピー先のディレクトリを返します。 デフォルト
   では、*dst* を作成するために必要な途中のディレクトリもすべて作成し
   ます。

   各ディレクトリのパーミッション、最終アクセス時間、最終変更時間は
   "copystat()" でコピーされます。それぞれのファイルは "copy2()" でコ
   ピーされます。

   *symlinks* が真の場合、ソースツリー内のシンボリックリンクは新しいツ
   リーでもシンボリックになり、元のシンボリックリンクのメタデータはプ
   ラットフォームが許す限りコピーされます。偽の場合や省略された場合、
   リンク先のファイルの内容とメタデータが新しいツリーにコピーされます
   。

   *symlinks* が偽の場合、リンク先のファイルが存在しなければ、コピー処
   理終了時に送出される "Error" 例外のエラーリストに例外が追加されます
   。オプションの *ignore_dangling_symlinks* フラグを真に設定してこの
   エラーを送出させないこともできます。このオプションは "os.symlink()"
   をサポートしていないプラットフォーム上では効果がないことに注意して
   ください。

   *ignore* は "copytree()" が走査しているディレクトリと
   "os.listdir()" が返すその内容のリストを引数として受け取ることのでき
   る呼び出し可能オブジェクトでなければなりません。 "copytree()" は再
   帰的に呼び出されるので、 *ignore* はコピーされる各ディレクトリ毎に
   呼び出されます。 *ignore* の戻り値はカレントディレクトリに相対的な
   ディレクトリ名およびファイル名のシーケンス（すなわち第二引数の項目
   のサブセット）でなければなりません。それらの名前はコピー中に無視さ
   れます。 "ignore_patterns()" を用いて glob 形式のパターンによって無
   視する呼び出し可能オブジェクトを作成することが出来ます。

   例外が発生した場合、理由のリストとともに "Error" を送出します。

   *copy_function* は各ファイルをコピーするために利用される呼び出し可
   能オブジェクトでなければなりません。 *copy_function* はコピー元のパ
   スとコピー先のパスを引数に呼び出されます。 デフォルトでは "copy2()"
   が利用されますが、同じシグネチャを持つ関数 ("copy()" など) ならどれ
   でも利用可能です。

   *dirs_exist_ok* が偽 (デフォルト) で *dst* がすでに存在する場合は、
   "FileExistsError" を送出します。 *dirs_exist_ok* が真の場合は、既存
   のディレクトリがあってもコピーを続行し、*dst* ツリー内のファイルを
   *src* ツリー内の対応するファイルで上書きします。

   引数 "src", "dst" を指定して 監査イベント "shutil.copytree" を送出
   します。

   バージョン 3.2 で変更: 独自のコピー関数を指定できるよう、
   *copy_function* 引数が追加されました。 *symlinks* が偽の場合にリン
   ク切れのシンボリックリンクによるエラーを抑制できるよう、
   *ignore_dangling_symlinks* 引数が追加されました。

   バージョン 3.3 で変更: *symlinks* が偽の場合メタデータをコピーしま
   す。 *dst* を返すようになりました。

   バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラ
   ットフォーム特有の高速なコピーを行うシステムコールが利用されること
   があります。 プラットフォーム依存の効率的なコピー操作 を参照してく
   ださい。

   バージョン 3.8 で変更: 引数 *dirs_exist_ok* が追加されました。

shutil.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)

   ディレクトリツリー全体を削除します。 *path* はディレクトリを指して
   いなければならず、ディレクトリへのシンボリックリンクは指定できませ
   ん。 *ignore_errors* が真の場合、削除の失敗によるエラーは無視します
   。 偽または省略された場合は、*onexc* または *onerror* で指定したハ
   ンドラーを呼び出してエラーを処理します。 両方とも省略した場合は例外
   を呼び出し元に伝播させます。

   *path* がディレクトリへのシンボリックリンクで、末尾にパス区切り文字
   が付いている場合 (例えば "'link/'")、OS がリンクを解決するため、
   "rmtree()" はリンク先のディレクトリの内容を削除した後、*path* 自体
   の削除に失敗します。 "pathlib.Path" は末尾の区切り文字を取り除くた
   め、"rmtree(Path('link/'))" は通常どおりリンクを拒否します。

   この関数は ディレクトリ記述子への相対パス をサポートしています。

   注釈:

     必要な fd ベースの関数をサポートしているプラットフォームでは、 シ
     ンボリックリンク攻撃に耐性のあるバージョンの "rmtree()" がデフォ
     ルトで利用されます。それ以外のプラットフォームでは、 "rmtree()"
     の実装はシンボリックリンク攻撃の影響を受けます。適当なタイミング
     と環境で攻撃者はファイルシステム上のシンボリックリンクを操作して
     、それ以外の方法ではアクセス不可能なファイルを削除することが出来
     ます。アプリケーションは、どちらのバージョンの "rmtree()" が利用
     されているかを知るために関数のデータ属性
     "rmtree.avoids_symlink_attacks" を利用することができます。

   *onexc* を指定する場合、 *function*, *path*, *excinfo* の3つの引数
   を受け取る呼び出し可能オブジェクトでなければなりません。

   最初の引数 *function* は例外を送出した関数で、プラットフォームや実
   装によって異なります。 二つ目の引数 *path* は *function* に渡された
   パス名です。 三つ目の引数 *excinfo* は送出された例外です。 *onexc*
   が送出した例外は捕捉しません。

   非推奨の *onerror* は *onexc* と似ていますが、三つ目の引数として
   "sys.exc_info()" の戻り値であるタプルを受け取ります。

   参考: 読み取り専用ファイルを含むディレクトリツリーを削除する例は、
       rmtree の例 を参照してください。

   引数 "path", "dir_fd" を指定して 監査イベント "shutil.rmtree" を送
   出します。

   バージョン 3.3 で変更: プラットフォームが fd ベースの関数をサポート
   する場合に自動的に使用されるシンボリックリンク攻撃に耐性のあるバー
   ジョンが追加されました。

   バージョン 3.8 で変更: Windows では、ディレクトリへのジャンクション
   を削除する際にリンク先ディレクトリにあるファイルを削除しなくなりま
   した。

   バージョン 3.11 で変更: 引数 *dir_fd* を追加しました。

   バージョン 3.12 で変更: *onexc* 引数が追加され、*onerror* は非推奨
   になりました。

   バージョン 3.13 で変更: "rmtree()" は最上位のパスを除き、
   "FileNotFoundError" 例外を無視するようになりました。 "OSError" と
   "OSError" のサブクラス以外の例外は、常に呼び出し元に伝播するように
   なりました。

   rmtree.avoids_symlink_attacks

      プラットフォームと実装がシンボリックリンク攻撃に耐性のあるバージ
      ョンの "rmtree()" を提供しているかどうかを示します。現在のところ
      、この属性は fd ベースのディレクトリアクセス関数をサポートしてい
      るプラットフォームでのみ真になります。

      Added in version 3.3.

shutil.move(src, dst, copy_function=copy2)

   ファイルまたはディレクトリ (*src*) を再帰的に別の場所に移動して、移
   動先を返します。

   *dst* が既存のディレクトリまたはディレクトリへのシンボリックリンク
   の場合、*src* はそのディレクトリ内に移動されます。 そのディレクトリ
   内の移動先パスは、あらかじめ存在していてはいけません。

   *dst* がすでに存在し、ディレクトリではない場合、"os.rename()" の動
   作に応じて上書きされることがあります。

   *src* と移動先が同じファイルシステム上にある場合、内部では優先的に
   "os.rename()" を使います。 "os.rename()" が "OSError" で失敗した場
   合 (例えば、ユーザーに移動先ファイルへの書き込み権限はあるものの、
   その親ディレクトリへの書き込み権限がない場合) は、*copy_function*
   を使う方法に切り替えます。 その場合は *copy_function* で *src* を移
   動先にコピーしてから削除します。

   シンボリックリンクの場合、*src* と同じリンク先を指す新しいシンボリ
   ックリンクを移動先の中、または移動先そのものとして作成し、*src* を
   削除します。

   *copy_function* を指定する場合は、*src* と移動先の二つの引数を受け
   取る呼び出し可能オブジェクトでなければなりません。 "os.rename()" を
   使えない場合に、*src* を移動先にコピーするために使われます。 移動元
   がディレクトリなら、*copy_function* を渡して "copytree()" を呼び出
   します。 デフォルトの *copy_function* は "copy2()" です。
   *copy_function* に "copy()" を指定すると、メタデータもコピーするこ
   とが不可能な場合でも、メタデータのコピーを省いて移動を成功させられ
   ます。

   引数 "src", "dst" を指定して 監査イベント "shutil.move" を送出しま
   す。

   バージョン 3.3 で変更: 異なるファイルシステムに対する明示的なシンボ
   リックリンク処理が追加されました。これにより GNU **mv** の振る舞い
   に適応するようになります。 *dst* を返すようになりました。

   バージョン 3.5 で変更: キーワード引数 *copy_function* が追加されま
   した。

   バージョン 3.8 で変更: ファイルのコピーをより効率的に行うため、プラ
   ットフォーム特有の高速なコピーを行うシステムコールが利用されること
   があります。 プラットフォーム依存の効率的なコピー操作 を参照してく
   ださい。

   バージョン 3.9 で変更: *src* と *dst* が両方とも *path-like object*
   を受け付けるようになりました。

shutil.disk_usage(path)

   指定されたパスについて、ディスクの利用状況を、名前付きタプル
   (*named tuple*) で返します。このタプルには *total*, *used*, *free*
   という属性があり、それぞれトータル、使用中、空きの容量をバイト単位
   で示します。 *path* はファイルまたはディレクトリです。

   注釈:

     Unix ファイルシステムでは、*path* は **マウントされた** ファイル
     システムのパーティション内のパスを指していなければなりません。 こ
     れらのプラットフォームでは、CPython はマウントされていないファイ
     ルシステムのディスク使用量を取得しようとしません。

   Added in version 3.3.

   バージョン 3.8 で変更: Windowsにおいても *path* にディレクトリだけ
   でなくファイルを指定できるようになりました。

   利用可能な環境: Unix, Windows.

shutil.chown(path, user=None, group=None, *, dir_fd=None, follow_symlinks=True)

   指定された *path* のオーナー *user* と/または *group* を変更します
   。

   *user* はシステムのユーザー名か uid です。 *group* も同じです。少な
   くともどちらかの引数を指定する必要があります。

   内部で利用している "os.chown()" も参照してください。

   引数 "path", "user", "group" を指定して 監査イベント "shutil.chown"
   を送出します。

   利用可能な環境: Unix.

   Added in version 3.3.

   バージョン 3.13 で変更: 引数 *dir_fd* および *follow_symlinks* が追
   加されました。

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

   *cmd* を実行しようとした時に実行される実行ファイルのパスを返します
   。 *cmd* を呼び出せない場合は "None" を返します。

   *mode* は "os.access()" に渡すパーミッションマスクで、デフォルトで
   はファイルが存在して実行可能であることを確認します。

   *path* は検索するディレクトリを "os.pathsep" で区切って指定する「
   "PATH" 文字列」です。 *path* を指定しない場合は "os.environ" から環
   境変数 "PATH" を読み取り、それも設定されていなければ "os.defpath"
   を使います。

   *cmd* にディレクトリ部分が含まれている場合、"which()" は指定された
   パスだけを直接調べ、*path* やシステムの "PATH" 環境変数に列挙された
   ディレクトリは検索しません。

   Windows では、*mode* に "os.X_OK" が含まれていない場合、カレントデ
   ィレクトリを *path* の先頭に追加します。 *mode* に "os.X_OK" が含ま
   れている場合は、Windows API の "NeedCurrentDirectoryForExePathW" に
   問い合わせて、カレントディレクトリを *path* の先頭に追加するかどう
   か決めます。 実行ファイルを探す際にカレントディレクトリを調べないよ
   うにするには、環境変数 "NoDefaultCurrentDirectoryInExePath" を設定
   してください。

   Windows ではさらに、拡張子が指定されていないコマンドを解決するため
   に "PATHEXT" 環境変数を使います。 例えば "shutil.which("python")"
   を呼び出すと、"which()" は "PATHEXT" を調べて、*path* 内のディレク
   トリで "python.exe" を探すべきだと判断します。 Windows での例を示し
   ます。

      >>> shutil.which("python")
      'C:\\Python33\\python.EXE'

   *cmd* がディレクトリ部分を含むパスである場合にも、この処理が適用さ
   れます。

      >>> shutil.which("C:\\Python33\\python")
      'C:\\Python33\\python.EXE'

   Added in version 3.3.

   バージョン 3.8 で変更: "bytes" 型も使用できるようになりました。
   *cmd* が "bytes" 型の場合、戻り値も "bytes" 型です。

   バージョン 3.12 で変更: Windows では、*mode* に "os.X_OK" が含まれ
   、WinAPI の "NeedCurrentDirectoryForExePathW(cmd)" が偽の場合、カレ
   ントディレクトリを検索パスの先頭に追加しなくなりました。 それ以外の
   場合は、カレントディレクトリがすでに検索パスに含まれていても先頭に
   追加します。 *cmd* にディレクトリ部分が含まれている場合や、
   "PATHEXT" に含まれる拡張子で終わる場合にも "PATHEXT" を使うようにな
   りました。 また、拡張子のないファイル名も見つけられるようになりまし
   た。

exception shutil.Error

   複数ファイルの操作中に発生した例外をまとめる "OSError" のサブクラス
   です。 "copytree()" の場合、例外の引数は 3 要素のタプル (*srcname*
   、*dstname*、*exception*) のリストです。


プラットフォーム依存の効率的なコピー操作
----------------------------------------

Python 3.8 から、ファイルのコピーを伴う全ての関数 ("copyfile()",
"copy()", "copy2()", "copytree()", および "move()") はより効率的なファ
イルのコピーのためにプラットフォーム特有の "高速なコピー" を行うことが
あります (bpo-33671 を参照してください). ここで "高速なコピー" とは、
""outfd.write(infd.read())"" のようにPython が管理するユーザー空間のバ
ッファを利用することを避け、コピー操作がカーネル空間内で行われることを
意味します。

macOS では fcopyfile がファイルの内容（メタデータを除く）をコピーする
ために利用されます。

Linux では "os.copy_file_range()" または "os.sendfile()" が利用されま
す。

Solaris では "os.sendfile()" が利用されます。

Windows では "shutil.copyfile()" のデフォルトのバッファサイズを大きく
して (64 KiB ではなく 1 MiB)、"memoryview()" を使う
"shutil.copyfileobj()" の変種を利用します。 この方法でも読み書きはルー
プで行います。 Windows の "shutil.copy2()" はネイティブの "CopyFile2"
呼び出しを使います。 これは最も効率的な方法で、コピーオンライトに対応
し、メタデータも保持します。

高速なコピー操作が失敗し、コピー先ファイルにまだデータを書き込んでいな
い場合、shutil は内部で、通知せずに効率の劣る "copyfileobj()" 関数へ切
り替えます。

バージョン 3.8 で変更.

バージョン 3.14 で変更: Solaris では "os.sendfile()" を使うようになり
ました。

バージョン 3.14 で変更: 対応する Linux ファイルシステムでは、
"os.copy_file_range()" を介してコピーオンライトやサーバー側のコピーが
内部で使われる場合があります。


copytree の例
-------------

"ignore_patterns()" ヘルパ関数を利用する例です:

   from shutil import copytree, ignore_patterns

   copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

この例では、 ".pyc" ファイルと、 "tmp" で始まる全てのファイルやディレ
クトリを除いて、全てをコピーします。

*ignore* 引数にロギングさせる別の例です。

   from shutil import copytree
   import logging

   def _logpath(path, names):
       logging.info('Working in %s', path)
       return []   # 何も無視しない

   copytree(source, destination, ignore=_logpath)


rmtree の例
-----------

この例は、Windows で読み取り専用ビットが設定されたファイルを含むディレ
クトリツリーを削除する方法を示します。 "onexc" コールバックで読み取り
専用ビットを解除し、削除を再試行します。 その後に発生したエラーは呼び
出し元に伝播します。

   import os, stat
   import shutil

   def remove_readonly(func, path, _):
       "読み取り専用ビットを解除して削除を再試行する"
       os.chmod(path, stat.S_IWRITE)
       func(path)

   shutil.rmtree(directory, onexc=remove_readonly)


アーカイブ化操作
================

Added in version 3.2.

バージョン 3.5 で変更: *xztar* 形式のサポートが追加されました。

圧縮とアーカイブ化されているファイルの読み書きの高水準なユーティリティ
も提供されています。これらは "zipfile" 、 "tarfile" モジュールに依拠し
ています。

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

   アーカイブファイル (zip や tar) を作成してその名前を返します。

   *base_name* は、作成するファイルの名前をパスを含めて指定する文字列
   または *path-like object* です。 形式固有の拡張子は含めません。

   *format* はアーカイブ形式で、"zip" ("zlib" モジュールを利用できる場
   合)、"tar"、"gztar" ("zlib" モジュールを利用できる場合)、"bztar"
   ("bz2" モジュールを利用できる場合)、"xztar" ("lzma" モジュールを利
   用できる場合)、"zstdtar" ("compression.zstd" モジュールを利用できる
   場合) のいずれかです。

   *root_dir* は、アーカイブのルートディレクトリを指定する文字列または
   *path-like object* です。 アーカイブ内のすべてのパスはこのディレク
   トリからの相対パスになります。 例えば、通常はアーカイブの作成前に
   *root_dir* に移動します。

   *base_dir* は、アーカイブ化を開始するディレクトリを指定する文字列ま
   たは *path-like object* です。 つまり、アーカイブ内のすべてのファイ
   ルやディレクトリのパスに共通する先頭部分になります。 *base_dir* は
   *root_dir* からの相対パスで指定しなければなりません。 両者を組み合
   わせる方法は base_dir を使ったアーカイブ化の例 を参照してください。

   *root_dir* と *base_dir* のどちらも、デフォルトはカレントディレクト
   リです。

   *dry_run* が真の場合、アーカイブは作成されませんが実行される操作は
   *logger* に記録されます。

   *owner* と *group* は、tar アーカイブを作成するときに使われます。デ
   フォルトでは、カレントのオーナーとグループを使います。

   *logger* は **PEP 282** に互換なオブジェクトでなければなりません。
   これは普通は "logging.Logger" のインスタンスです。

   *verbose* 引数は使用されず、非推奨です。

   引数 "base_name", "format", "root_dir", "base_dir" を指定して 監査
   イベント "shutil.make_archive" を送出します。

   注釈:

     "register_archive_format()" で登録した独自のアーカイバーが
     *root_dir* 引数に対応していない場合、この関数はスレッドセーフでは
     ありません。 その場合、アーカイブ化のためにプロセスのカレントディ
     レクトリを一時的に *root_dir* に変更します。

   バージョン 3.8 で変更: "format="tar"" で作成されたアーカイブでは、
   レガシーなGNU形式に代わってモダンな pax (POSIX.1-2001) 形式が使われ
   ます。

   バージョン 3.10.6 で変更: 標準の ".zip" アーカイブと tar アーカイブ
   を作成する場合、この関数はスレッドセーフになりました。

   バージョン 3.15 で変更: *base_name*、*root_dir*、*base_dir* が
   *path-like object* を受け付けるようになりました。

shutil.get_archive_formats()

   アーカイブ化をサポートしているフォーマットのリストを返します。返さ
   れるシーケンスのそれぞれの要素は、タプル "(name, description)" です
   。

   デフォルトで "shutil" は以下の形式を提供します。

   * *zip*: ZIP ファイル ("zlib" モジュールが利用可能な場合)。

   * *tar*: 非圧縮の tar ファイル。 POSIX.1-2001 pax 形式が使われます
     。

   * *gztar*: gzip で圧縮された tar ファイル ("zlib" モジュールが利用
     可能な場合)。

   * *bztar*: bzip2 で圧縮された tar ファイル ("bz2" モジュールが利用
     可能な場合)。

   * *xztar*: xz で圧縮された tar ファイル ("lzma" モジュールが利用可
     能な場合)。

   * *zstdtar*: Zstandard で圧縮された tar ファイル
     ("compression.zstd" モジュールが利用可能な場合)。

   "register_archive_format()" を使って、新しいフォーマットを登録した
   り、既存のフォーマットに独自のアーカイバを提供したりできます。

shutil.register_archive_format(name, function[, extra_args[, description]])

   アーカイバをフォーマット *name* に登録します。

   *function* はアーカイブの作成に使う呼び出し可能オブジェクトです。
   作成するファイルの *base_name* と、アーカイブ化を開始する
   *base_dir* (デフォルトは "os.curdir") を順に受け取ります。 さらに、
   "make_archive()" に渡された *owner*、*group*、*dry_run*、*logger*
   がキーワード引数として渡されます。

   *function* の独自の属性 "function.supports_root_dir" が "True" の場
   合、*root_dir* 引数がキーワード引数として渡されます。 それ以外の場
   合は、*function* を呼び出す前にプロセスのカレントディレクトリを一時
   的に *root_dir* に変更します。 この場合、"make_archive()" はスレッ
   ドセーフではありません。

   *extra_args* は、与えられた場合、 "(name, value)" の対のシーケンス
   で、アーカイバ呼び出し可能オブジェクトが使われるときに追加のキーワ
   ード引数として使われます。

   *description* は、アーカイバのリストを返す "get_archive_formats()"
   で使われます。デフォルトでは空の文字列です。

   バージョン 3.12 で変更: *root_dir* 引数を受け取る関数への対応が追加
   されました。

shutil.unregister_archive_format(name)

   アーカイブフォーマット *name* を、サポートされているフォーマットの
   リストから取り除きます。

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

   アーカイブをアンパックします。 *filename* はアーカイブのフルパスで
   す。

   *extract_dir* はアーカイブをアンパックする先のディレクトリ名です。
   指定されなかった場合は現在の作業ディレクトリを利用します。

   *format* はアーカイブフォーマットで、 "zip", "tar", "gztar",
   "bztar", "xztar", "zstdtar" あるいは "register_unpack_format()" で
   登録したその他のフォーマットのどれかです。 指定されなかった場合、
   "unpack_archive()" はアーカイブファイル名の拡張子に対して登録された
   アンパッカーを利用します。 アンパッカーが見つからなかった場合、
   "ValueError" を発生させます。

   キーワード専用引数 *filter* は、内部で使う展開関数に渡されます。
   zip ファイルでは *filter* を指定できません。 tar ファイルでは、tar
   や Unix 系ファイルシステムに固有の機能を使う場合を除き、"'data'"
   (Python 3.14 以降のデフォルト) を使うことをお勧めします (詳細は 展
   開フィルター を参照)。

   引数 "filename", "extract_dir", "format" を指定して 監査イベント
   "shutil.unpack_archive" を送出します。

   警告:

     信頼できない提供元のアーカイブは、事前に内容を調べずに展開しない
     でください。 例えば、絶対パスのファイル名や ".." を含むファイル名
     のメンバーがあると、*extract_dir* 引数で指定したパスの外にファイ
     ルが作成される可能性があります。Python 3.14 以降、組み込みの両形
     式 (zip ファイルと tar ファイル) のデフォルト設定は、この種のセキ
     ュリティ問題のうち最も危険なものを防ぎますが、意図しない動作を *
     すべて* 防ぐわけではありません。 tar 固有の詳細は 追加の検証のヒ
     ント 節を参照してください。

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

   バージョン 3.12 で変更: *filter* 引数が追加されました。

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

   アンパック用のフォーマットを登録します。 *name* はフォーマット名で
   、 *extensions* はそのフォーマットに対応する拡張子 (例えば Zip ファ
   イルに対して ".zip") のリストです。

   *function* はアーカイブの展開に使う呼び出し可能オブジェクトです。
   以下の引数を受け取ります。

   * アーカイブのパス (位置引数)。

   * アーカイブの展開先ディレクトリ (位置引数)。

   * "unpack_archive()" に指定されていれば、*filter* キーワード引数。

   * *extra_args* に "(name, value)" タプルのシーケンスとして指定され
     た追加のキーワード引数。

   フォーマットの説明として *description* を指定することができます。こ
   れは "get_unpack_formats()" 関数によって返されます。

shutil.unregister_unpack_format(name)

   アンパックフォーマットを登録解除します。 *name* はフォーマットの名
   前です。

shutil.get_unpack_formats()

   登録されているすべてのアンパックフォーマットをリストで返します。戻
   り値のリストの各要素は "(name, extensions, description)" の形のタプ
   ルです。

   デフォルトで "shutil" は以下の形式を提供します。

   * *zip*: ZIP ファイル (対応するモジュールが利用可能な場合にのみ圧縮
     ファイルはアンパックされます)。

   * *tar*: 圧縮されていない tar ファイル。

   * *gztar*: gzip で圧縮された tar ファイル ("zlib" モジュールが利用
     可能な場合)。

   * *bztar*: bzip2 で圧縮された tar ファイル ("bz2" モジュールが利用
     可能な場合)。

   * *xztar*: xz で圧縮された tar ファイル ("lzma" モジュールが利用可
     能な場合)。

   * *zstdtar*: Zstandard で圧縮された tar ファイル
     ("compression.zstd" モジュールが利用可能な場合)。

   "register_unpack_format()" を使って新しいフォーマットや既存のフォー
   マットに対する別のアンパッカーを登録することができます。


アーカイブ化の例
----------------

この例では、ユーザの ".ssh" ディレクトリにあるすべてのファイルを含む、
gzip された tar ファイルアーカイブを作成します:

   >>> from shutil import make_archive
   >>> import os
   >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
   >>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
   >>> make_archive(archive_name, 'gztar', root_dir)
   '/Users/tarek/myarchive.tar.gz'

結果のアーカイブは、以下のものを含みます:

   $ tar -tzvf /Users/tarek/myarchive.tar.gz
   drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
   -rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
   -rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
   -rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
   -rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
   -rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
   -rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
   -rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts


*base_dir* を使ったアーカイブ化の例
-----------------------------------

この例では、 上記の例 と同じく "make_archive()" の使い方を示しますが、
ここでは特に *base_dir* の使い方を説明します。以下のようなディレクトリ
構造があるとします。

   $ tree tmp
   tmp
   └── root
       └── structure
           ├── content
               └── please_add.txt
           └── do_not_add.txt

作成するアーカイブには "please_add.txt" が含まれますが、いっぽう
"do_not_add.txt" は含まないようにします。 この場合以下のようにします。

   >>> from shutil import make_archive
   >>> import os
   >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
   >>> make_archive(
   ...     archive_name,
   ...     'tar',
   ...     root_dir='tmp/root',
   ...     base_dir='structure/content',
   ... )
   '/Users/tarek/myarchive.tar'

アーカイブに含まれるファイルをリストすると、以下のようになります。

   $ python -m tarfile -l /Users/tarek/myarchive.tar
   structure/content/
   structure/content/please_add.txt


出力ターミナルのサイズの取得
============================

shutil.get_terminal_size(fallback=(columns, lines))

   ターミナルウィンドウのサイズを取得します。

   幅と高さについて、それぞれ "COLUMNS" と "LINES" という環境変数をチ
   ェックします。その変数が定義されていて値が正の整数であればそれを利
   用します。

   典型的な "COLUMNS" や "LINES" が定義されていない場合には、
   "sys.__stdout__" に接続されているターミナルに
   "os.get_terminal_size()" を呼び出して問い合わせます。

   システムが対応していない場合やターミナルに接続していないなどの理由
   でターミナルサイズの問い合わせに失敗した場合、 "fallback" 引数に与
   えられた値を利用します。 "fallback" のデフォルト値は "(80, 24)" で
   、これは多くのターミナルエミュレーターが利用しているデフォルトサイ
   ズです。

   戻り値は "os.terminal_size" 型の名前付きタプルです。

   参考: The Single UNIX Specification, Version 2, Other Environment
   Variables.

   Added in version 3.3.

   バージョン 3.11 で変更: "os.get_terminal_size()" がゼロを返した場合
   にも "fallback" の値を使うようになりました。
