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

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

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

The "shutil" module offers a number of high-level operations on files
and collections of files.  In particular, functions are provided
which support file copying and removal. For operations on individual
files, see also the "os" module.

警告:

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


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

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

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

   "copyfileobj()" will *not* guarantee that the destination stream
   has been flushed on completion of the copy. If you want to read
   from the destination at the completion of the copy operation (for
   example, reading the contents of a temporary file that has been
   copied from a HTTP stream), you must ensure that you have called
   "flush()" or "close()" on the file-like object before attempting to
   read the destination file.

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

   This exception is raised when "copyfile()" or "copytree()" attempt
   to copy a named pipe.

   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* は :term`path-
   like object <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)

   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.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.3 で変更: *symlinks* が偽の場合メタデータをコピーしま
   す。 *dst* を返すようになりました。

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

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

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

   Delete an entire directory tree; *path* must point to a directory
   (but not a symbolic link to a directory).  If *ignore_errors* is
   true, errors resulting from failed removals will be ignored; if
   false or omitted, such errors are handled by calling a handler
   specified by *onexc* or *onerror* or, if both are omitted,
   exceptions are propagated to the caller.

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

   注釈:

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

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

   The first parameter, *function*, is the function which raised the
   exception; it depends on the platform and implementation.  The
   second parameter, *path*, will be the path name passed to
   *function*.  The third parameter, *excinfo*, is the exception that
   was raised. Exceptions raised by *onexc* will not be caught.

   The deprecated *onerror* is similar to *onexc*, except that the
   third parameter it receives is the tuple returned from
   "sys.exc_info()".

   参考:

     rmtree の例 for an example of handling the removal of a directory
     tree that contains read-only files.

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

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

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

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

   バージョン 3.12 で変更: Added the *onexc* parameter, deprecated
   *onerror*.

   バージョン 3.13 で変更: "rmtree()" now ignores "FileNotFoundError"
   exceptions for all but the top-level path. Exceptions other than
   "OSError" and subclasses of "OSError" are now always propagated to
   the caller.

   rmtree.avoids_symlink_attacks

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

      Added in version 3.3.

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

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

   If *dst* is an existing directory or a symlink to a directory, then
   *src* is moved inside that directory. The destination path in that
   directory must not already exist.

   If *dst* already exists but is not a directory, it may be
   overwritten depending on "os.rename()" semantics.

   "os.rename()" is preferably used internally when *src* and the
   destination are on the same filesystem. In case "os.rename()" fails
   due to "OSError" (e.g. the user has write permission to the
   destination file but not to its parent directory), this method
   falls back to using *copy_function*, in which case *src* is copied
   to the destination using *copy_function* and then removed.

   In case of symlinks, a new symlink pointing to the target of *src*
   will be created in or as the destination, and *src* will be
   removed.

   If *copy_function* is given, it must be a callable that takes two
   arguments, *src* and the destination, and will be used to copy
   *src* to the destination if "os.rename()" cannot be used.  If the
   source is a directory, "copytree()" is called, passing it the
   *copy_function*. The default *copy_function* is "copy2()".  Using
   "copy()" as the *copy_function* allows the move to succeed when it
   is not possible to also copy the metadata, at the expense of not
   copying any of the metadata.

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

   注釈:

     On Unix filesystems, *path* must point to a path within a
     **mounted** filesystem partition. On those platforms, CPython
     doesn't attempt to retrieve disk usage information from non-
     mounted filesystems.

   Added in version 3.3.

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

   Availability: 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"
   を送出します。

   Availability: 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* is a ""PATH" string" specifying the directories to look in,
   delimited by "os.pathsep". When no *path* is specified, the "PATH"
   environment variable is read from "os.environ", falling back to
   "os.defpath" if it is not set.

   If *cmd* contains a directory component, "which()" only checks the
   specified path directly and does not search the directories listed
   in *path* or in the system's "PATH" environment variable.

   On Windows, the current directory is prepended to the *path* if
   *mode* does not include "os.X_OK". When the *mode* does include
   "os.X_OK", the Windows API "NeedCurrentDirectoryForExePathW" will
   be consulted to determine if the current directory should be
   prepended to *path*. To avoid consulting the current working
   directory for executables: set the environment variable
   "NoDefaultCurrentDirectoryInExePath".

   Also on Windows, the "PATHEXT" environment variable is used to
   resolve commands that may not already include an extension. For
   example, if you call "shutil.which("python")", "which()" will
   search "PATHEXT" to know that it should look for "python.exe"
   within the *path* directories. For example, on Windows:

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

   This is also applied when *cmd* is a path that contains a directory
   component:

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

   Added in version 3.3.

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

   バージョン 3.12 で変更: On Windows, the current directory is no
   longer prepended to the search path if *mode* includes "os.X_OK"
   and WinAPI "NeedCurrentDirectoryForExePathW(cmd)" is false, else
   the current directory is prepended even if it is already in the
   search path; "PATHEXT" is used now even when *cmd* includes a
   directory component or ends with an extension that is in "PATHEXT";
   and filenames that have no extension can now be found.

exception shutil.Error

   This exception collects exceptions that are raised during a multi-
   file operation. For "copytree()", the exception argument is a list
   of 3-tuples (*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()" が利用されます。

On Windows "shutil.copyfile()" uses a bigger default buffer size (1
MiB instead of 64 KiB) and a "memoryview()"-based variant of
"shutil.copyfileobj()" is used.

If the fast-copy operation fails and no data was written in the
destination file then shutil will silently fall back to less efficient
"copyfileobj()" function internally.

バージョン 3.8 で変更.

バージョン 3.14 で変更: Solaris now uses "os.sendfile()".

バージョン 3.14 で変更: Copy-on-write or server-side copy may be used
internally via "os.copy_file_range()" on supported Linux filesystems.


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

   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, 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* is the name of the file to create, including the path,
   minus any format-specific extension.

   *format* is the archive format: one of "zip" (if the "zlib" module
   is available), "tar", "gztar" (if the "zlib" module is available),
   "bztar" (if the "bz2" module is available), "xztar" (if the "lzma"
   module is available), or "zstdtar" (if the "compression.zstd"
   module is available).

   *root_dir* is a directory that will be the root directory of the
   archive, all paths in the archive will be relative to it; for
   example, we typically chdir into *root_dir* before creating the
   archive.

   *base_dir* is the directory where we start archiving from; i.e.
   *base_dir* will be the common prefix of all files and directories
   in the archive.  *base_dir* must be given relative to *root_dir*.
   See base_dir を使ったアーカイブ化の例 for how to use *base_dir* and
   *root_dir* together.

   *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" を送出します。

   注釈:

     This function is not thread-safe when custom archivers registered
     with "register_archive_format()" do not support the *root_dir*
     argument.  In this case it temporarily changes the current
     working directory of the process to *root_dir* 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)" です
   。

   By default "shutil" provides these formats:

   * *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* is the callable that will be used to create archives.
   The callable will receive the *base_name* of the file to create,
   followed by the *base_dir* (which defaults to "os.curdir") to start
   archiving from. Further arguments are passed as keyword arguments:
   *owner*, *group*, *dry_run* and *logger* (as passed in
   "make_archive()").

   If *function* has the custom attribute "function.supports_root_dir"
   set to "True", the *root_dir* argument is passed as a keyword
   argument. Otherwise the current working directory of the process is
   temporarily changed to *root_dir* before calling *function*. In
   this case "make_archive()" is not thread-safe.

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

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

   バージョン 3.12 で変更: Added support for functions supporting the
   *root_dir* argument.

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" を発生させます。

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

   引数 "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, for example,
     members that have absolute filenames or filenames with ".."
     components.Since Python 3.14, the defaults for both built-in
     formats (zip and tar files) will prevent the most dangerous of
     such security issues, but will not prevent *all* unintended
     behavior. Read the Hints for further verification section for
     tar-specific details.

   バージョン 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* 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)" の形のタプ
   ルです。

   By default "shutil" provides these formats:

   * *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 で変更: The "fallback" values are also used if
   "os.get_terminal_size()" returns zeroes.
