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

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

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

引数 src 、 dst` を指定して :ref:`監査イベント <auditing>` ``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` を指定して :ref:`監査イベント <auditing>` ``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` を指定して :ref:`監査イベント <auditing>` ``shutil.copystat を送出します。

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

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

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

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

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

引数 src 、 dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copyfile を送出します。

引数 src 、 dst` を指定して :ref:`監査イベント <auditing>` ``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` を指定して :ref:`監査イベント <auditing>` ``shutil.copyfile を送出します。

引数 src 、 dst` を指定して :ref:`監査イベント <auditing>` ``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. dirs_exist_ok dictates whether to raise an exception in case dst or any missing parent directory already exists.

各ディレクトリのパーミッション、最終アクセス時間、最終変更時間は 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() など) ならどれでも利用可能です。

引数 src 、 dst` を指定して :ref:`監査イベント <auditing>` ``shutil.copytree を送出します。

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

バージョン 3.2 で変更: カスタムコピー機能を提供できるように copy_function 引数が追加されました。 symlinks が偽の時にダングリング (宙ぶらりんの) シンボリックリンクエラーを送出させないために ignore_dangling_symlinks 引数が追加されました。

バージョン 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` を指定して :ref:`監査イベント <auditing>` ``shutil.move を送出します。

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

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

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

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 の例

以下は前述の copytree() 関数のドキュメント文字列を省略した実装例です。本モジュールで提供される他の関数の使い方を示しています。

def copytree(src, dst, symlinks=False):
    names = os.listdir(src)
    os.makedirs(dst)
    errors = []
    for name in names:
        srcname = os.path.join(src, name)
        dstname = os.path.join(dst, name)
        try:
            if symlinks and os.path.islink(srcname):
                linkto = os.readlink(srcname)
                os.symlink(linkto, dstname)
            elif os.path.isdir(srcname):
                copytree(srcname, dstname, symlinks)
            else:
                copy2(srcname, dstname)
            # XXX What about devices, sockets etc.?
        except OSError as why:
            errors.append((srcname, dstname, str(why)))
        # catch the Error from the recursive copytree so that we can
        # continue with other files
        except Error as err:
            errors.extend(err.args[0])
    try:
        copystat(src, dst)
    except OSError as why:
        # can't copy file access times on Windows
        if why.winerror is None:
            errors.extend((src, dst, str(why)))
    if errors:
        raise Error(errors)

ignore_patterns() ヘルパ関数を利用する、もう1つの例です。

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

注釈

この関数はスレッドセーフではありません。

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

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.8.17, 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.8.17 で変更: 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 で追加.