"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])

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

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.SameFileError

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

   バージョン 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()" と等価です。

   When *follow_symlinks* is false, and *src* is a symbolic link,
   "copy2()" attempts to copy all metadata from the *src* symbolic
   link to the newly created *dst* symbolic link. However, this
   functionality is not available on all platforms. On platforms where
   some or all of this functionality is unavailable, "copy2()" will
   preserve all the metadata it can; "copy2()" never raises an
   exception because it cannot preserve file metadata.

   "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)

   Recursively copy an entire directory tree rooted at *src* to a
   directory named *dst* and return the destination directory.  All
   intermediate directories needed to contain *dst* will also be
   created by default.

   各ディレクトリのパーミッション、最終アクセス時間、最終変更時間は
   "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()"
   が利用されますが、同じ特徴を持つ関数 ("shutil.copy()" など) ならど
   れでも利用可能です。

   If *dirs_exist_ok* is false (the default) and *dst* already exists,
   a "FileExistsError" is raised. If *dirs_exist_ok* is true, the
   copying operation will continue if it encounters existing
   directories, and files within the *dst* tree will be overwritten by
   corresponding files from the *src* tree.

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

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

   バージョン 3.2 で変更: Added the *copy_function* argument to be
   able to provide a custom copy function. Added the
   *ignore_dangling_symlinks* argument to silence dangling symlinks
   errors when *symlinks* is false.

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

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

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

   ディレクトリツリー全体を削除します。 *path* はディレクトリを指して
   いなければなりません (ただしディレクトリに対するシンボリックリンク
   ではいけません)。*ignore_errors* が真である場合、削除に失敗したこと
   によるエラーは無視されます。偽や省略された場合はこれらのエラーは
   *onerror* で与えられたハンドラを呼び出して処理され、*onerror* が省
   略された場合は例外を送出します。

   注釈:

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

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

   最初の引数 *function* は例外を送出した関数で、プラットフォームや実
   装に依存します。第二引数 *path* は *function* に渡されたパス名です
   。第三引数 *excinfo* は "sys.exc_info()" が返した例外の情報です。
   *onerror* が送出した例外は捕捉されません。

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

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

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

   rmtree.avoids_symlink_attacks

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

      バージョン 3.3 で追加.

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

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

   移動先が存在するディレクトリの場合、 *src* はそのディレクトリの中へ
   移動します。移動先が存在していてそれがディレクトリでない場合、
   "os.rename()" の動作によっては上書きされることがあります。

   ターゲットが現在のファイルシステム上にある場合、 "os.rename()" が使
   用されます。 それ以外の場合 *copy_function* を使用して *src* を
   *dst* にコピーし、その後削除します。 シンボリックリンクの場合には、
   *src* のターゲットを指す新しいシンボリックリンクが、 *dst* の中また
   は *dst* として作成され、 *src* が削除されます。

   *copy_function* を指定する場合、 *src* と *dst* の 2 つの引数を持つ
   呼び出し可能オブジェクトを指定する必要があります。このオブジェクト
   は、"os.rename()" を使用できない場合に *src* を *dest* にコピーする
   ために使用されます。ソースがディレクトリの場合、 "copytree()" が呼
   び出され、そのディレクトリを "copy_function()" に渡します。デフォル
   トの  *copy_function* は "copy2()" です。"copy()" を
   *copy_function* として使用すると、メタデータをともにコピーすること
   ができない場合に移動を成功させることができます。この場合、メタデー
   タはまったくコピーされません。

   引数 "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* はファイルまたはディレクトリです。

   バージョン 3.3 で追加.

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

   Availability: Unix, Windows。

shutil.chown(path, user=None, group=None)

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

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

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

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

   利用可能な環境: Unix。

   バージョン 3.3 で追加.

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

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

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

   *path* が指定されなかった場合、 "os.environ()" が利用され、 "PATH"
   の値を返すか "os.defpath" にフォールバックします。

   Windows では、 *path* を指定した場合もデフォルト値を使った場合も、
   カレントディレクトリが最初に探されます。これはコマンドシェルが実行
   ファイルを探すときの動作です。また、 *cmd* を *path* から検索すると
   きに、 "PATHEXT" 環境変数も利用します。例えば、
   "shutil.which("python")" を実行した場合、 "which()" は "PATHEXT" を
   参照して *path* ディレクトリから "python.exe" を探すべきだというこ
   とを把握します。例えば、 Windows では:

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

   バージョン 3.3 で追加.

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

exception shutil.Error

   この例外は複数ファイルの操作を行っているときに生じる例外をまとめた
   ものです。 "copytree()" に対しては例外の引数は3つのタプル
   (*srcname*, *dstname*, *exception*)からなるリストです。


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

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

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

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

Windows では "shutil.copyfile()" はより大きなバッファサイズをデフォル
トとして使います (6 KiB の代わりに 1 MiB が使われます)。また、
"memoryview()" ベースの変形である "shutil.copyfileobj()" が使われます
。

高速なコピー操作が失敗して出力ファイルにデータが書き込まれなかった場合
、shutil はユーザーへの通知なしでより効率の低い "copyfileobj()" 関数に
フォールバックします。

バージョン 3.8 で変更.


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 []   # nothing will be ignored

   copytree(source, destination, ignore=_logpath)


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

次の例は、Windows で一部のファイルが読み取り専用のビットセットを含む場
合に、ディレクトリツリーを削除する方法を示します。onerror コールバック
を使用して、読み取り専用のビットを消去し、削除を再試行します。結果とし
て失敗が発生した場合、それらは伝搬されます:

   import os, stat
   import shutil

   def remove_readonly(func, path, _):
       "Clear the readonly bit and reattempt the removal"
       os.chmod(path, stat.S_IWRITE)
       func(path)

   shutil.rmtree(directory, onerror=remove_readonly)


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

バージョン 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* は、作成するファイルの、パスを含み、フォーマットごとの
   拡張子を抜いた名前です。 *format* はアーカイブフォーマットで "zip"
   ("zlib" モジュールが利用可能な場合), "tar", "gztar" ("zlib" モジュ
   ールが利用可能な場合), "bztar" ("bz2" モジュールが利用可能な場合),
   "xztar" ("lzma" モジュールが利用可能な場合) のいずれかです。

   *root_dir* はアーカイブファイルのルートとなるディレクトリです。アー
   カイブに含まれる全てのパスは *root_dir* からの相対パスになります。
   これは、アーカイブファイルを生成する前に *root_dir* へ移動すること
   に相当します。

   *base_dir* はアーカイブを開始するディレクトリです。すなわち、
   *base_dir* アーカイブに含まれるファイルとディレクトリに対する共通の
   プレフィックスになります。 *base_dir* は *root_dir* からの相対パス
   でなければなりません。 *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``を指定して
   :ref:`監査イベント <auditing>` ``shutil.make_archive" を送出します
   。

   注釈:

     This function is not thread-safe when custom archivers registered
     with "register_archive_format()" are used.  In this case it
     temporarily changes the current working directory of the process
     to perform archiving.

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

   バージョン 3.10.6 で変更: This function is now made thread-safe
   during creation of standard ".zip" and tar archives.

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" モジュールが利用可
     能な場合)。

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

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

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

   *function* はアーカイブのアンパックに使用される呼び出し可能オブジェ
   クトです。*funciton* は作成するファイルの *base_name*、続いてアーカ
   イブを開始する元の *base_dir* (デフォルトは "os.curdir") を受け取り
   ます。さらなる引数は、次のキーワード引数として渡されます: *owner*,
   *group*, *dry_run* ならびに *logger* ("make_archive()" に渡されます
   )。

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

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

shutil.unregister_archive_format(name)

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

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

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

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

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

   The keyword-only *filter* argument, which was added in Python
   3.10.12, is passed to the underlying unpacking function. For zip
   files, *filter* is not accepted. For tar files, it is recommended
   to set it to "'data'", unless using features specific to tar and
   UNIX-like filesystems. (See Extraction filters for details.) The
   "'data'" filter will become the default for tar files in Python
   3.14.

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

   警告:

     Never extract archives from untrusted sources without prior
     inspection. It is possible that files are created outside of the
     path specified in the *extract_dir* argument, e.g. members that
     have absolute filenames starting with "/" or filenames with two
     dots "..".

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

   バージョン 3.10.12 で変更: Added the *filter* argument.

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

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

   *function* is the callable that will be used to unpack archives.
   The callable will receive:

   * the path of the archive, as a positional argument;

   * the directory the archive must be extracted to, as a positional
     argument;

   * possibly a *filter* keyword argument, if it was given to
     "unpack_archive()";

   * additional keyword arguments, specified by *extra_args* as a
     sequence of "(name, value)" tuples.

   フォーマットの説明として *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" モジュールが利用可
     能な場合)。

   "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/my_archive.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.

   バージョン 3.3 で追加.
