shutdown —高レベルのファイル操作—Pythonドキュメント

shutil —高レベルのファイル操作

ソースコード： ：source： `Lib / shutil.py`

---

shutil モジュールは、ファイルおよびファイルのコレクションに対する多数の高レベルの操作を提供します。 特に、ファイルのコピーと削除をサポートする機能が提供されています。 個々のファイルの操作については、 os モジュールも参照してください。

警告

高レベルのファイルコピー関数（ shutil.copy（）、 shutil.copy2（））でさえ、すべてのファイルメタデータをコピーすることはできません。

POSIXプラットフォームでは、これはファイルの所有者とグループ、およびACLが失われることを意味します。 Mac OSでは、リソースフォークやその他のメタデータは使用されません。 これは、リソースが失われ、ファイルタイプと作成者コードが正しくないことを意味します。 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 は、文字列として指定されたパスのようなオブジェクトまたはパス名です。

dst は完全なターゲットファイル名である必要があります。 ターゲットディレクトリパスを受け入れるコピーについては、 copy（）を参照してください。 src と dst で同じファイルを指定すると、 SameFileError が発生します。

宛先の場所は書き込み可能である必要があります。 そうしないと、 OSError 例外が発生します。 dst がすでに存在する場合は、置き換えられます。 キャラクターやブロックのデバイスやパイプなどの特殊ファイルは、この機能ではコピーできません。

follow_symlinks がfalseで、 src がシンボリックリンクの場合、 src が指すファイルをコピーする代わりに、新しいシンボリックリンクが作成されます。

バージョン3.3で変更： OSError の代わりに IOError が発生していました。 follow_symlinks 引数を追加しました。 dst を返すようになりました。

バージョン3.4で変更： Error の代わりに Raise SameFileError 。 前者は後者のサブクラスであるため、この変更には下位互換性があります。

バージョン3.8で変更：ファイルをより効率的にコピーするために、プラットフォーム固有の高速コピーシステムコールが内部で使用される場合があります。 プラットフォームに依存する効率的なコピー操作セクションを参照してください。

exception shutil.SameFileError

この例外は、 copyfile（）のソースと宛先が同じファイルである場合に発生します。

バージョン3.4の新機能。

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

src から dst に許可ビットをコピーします。 ファイルの内容、所有者、およびグループは影響を受けません。 src および dst は、文字列として指定されたパスのようなオブジェクトまたはパス名です。 follow_symlinks がfalseで、 src と dst の両方がシンボリックリンクである場合、 copymode（）はのモードを変更しようとします。 ] dst 自体（それが指すファイルではなく）。 この機能は、すべてのプラットフォームで利用できるわけではありません。 詳細については、 copystat（）を参照してください。 copymode（）がローカルプラットフォーム上のシンボリックリンクを変更できず、変更するように求められた場合、何もせずに戻ります。

バージョン3.3で変更： follow_symlinks 引数を追加しました。

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

許可ビット、最終アクセス時刻、最終変更時刻、およびフラグを src から dst にコピーします。 Linuxでは、 copystat（）は、可能な場合は「拡張属性」もコピーします。 ファイルの内容、所有者、およびグループは影響を受けません。 src および dst は、文字列として指定されたパスのようなオブジェクトまたはパス名です。

follow_symlinks がfalseで、 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 を参照してください。

バージョン3.3で変更： follow_symlinks 引数を追加し、Linux拡張属性のサポートを追加しました。

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

ファイル src をファイルまたはディレクトリ dst にコピーします。 src および dst は、パスのようなオブジェクトまたは文字列である必要があります。 dst がディレクトリを指定している場合、ファイルは src のベースファイル名を使用して dst にコピーされます。 新しく作成されたファイルへのパスを返します。

follow_symlinks がfalseで、 src がシンボリックリンクの場合、 dst はシンボリックリンクとして作成されます。 follow_symlinks がtrueで、 src がシンボリックリンクの場合、 dst は src が参照するファイルのコピーになります。

copy（）は、ファイルデータとファイルのアクセス許可モードをコピーします（ os.chmod（）を参照）。 ファイルの作成時間や変更時間など、その他のメタデータは保持されません。 元のファイルメタデータをすべて保持するには、代わりに copy2（）を使用します。

バージョン3.3で変更： follow_symlinks 引数を追加しました。 新しく作成されたファイルへのパスを返します。

バージョン3.8で変更：ファイルをより効率的にコピーするために、プラットフォーム固有の高速コピーシステムコールが内部で使用される場合があります。 プラットフォームに依存する効率的なコピー操作セクションを参照してください。

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

copy（）と同じですが、 copy2（）もファイルメタデータを保持しようとする点が異なります。

follow_symlinks がfalseで、 src がシンボリックリンクの場合、 copy2（）は src シンボリックリンクからすべてのメタデータをコピーしようとします。新しく作成された dst シンボリックリンク。 ただし、この機能はすべてのプラットフォームで利用できるわけではありません。 この機能の一部またはすべてが利用できないプラットフォームでは、 copy2（）は可能なすべてのメタデータを保持します。 copy2（）は、ファイルメタデータを保持できないため、例外を発生させることはありません。

copy2（）は、 copystat（）を使用してファイルメタデータをコピーします。 シンボリックリンクメタデータを変更するためのプラットフォームサポートの詳細については、 copystat（）を参照してください。

バージョン3.3で変更： follow_symlinks 引数を追加し、拡張ファイルシステム属性もコピーしてみてください（現在はLinuxのみ）。 新しく作成されたファイルへのパスを返します。

バージョン3.8で変更：ファイルをより効率的にコピーするために、プラットフォーム固有の高速コピーシステムコールが内部で使用される場合があります。 プラットフォームに依存する効率的なコピー操作セクションを参照してください。

shutil.ignore_patterns(*patterns)

このファクトリ関数は、 copytree（） 'の ignore 引数の呼び出し可能オブジェクトとして使用できる関数を作成し、globスタイルのの1つに一致するファイルとディレクトリを無視します。 ]パターンが提供されます。 以下の例を参照してください。

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

src をルートとするディレクトリツリー全体を dst という名前のディレクトリに再帰的にコピーし、宛先ディレクトリを返します。 dirs_exist_ok は、 dst または欠落している親ディレクトリがすでに存在する場合に例外を発生させるかどうかを指定します。

ディレクトリのアクセス許可と時間は copystat（）を使用してコピーされ、個々のファイルは copy2（）を使用してコピーされます。

symlinks がtrueの場合、ソースツリーのシンボリックリンクは新しいツリーのシンボリックリンクとして表され、プラットフォームが許可する限り、元のリンクのメタデータがコピーされます。 falseまたは省略した場合、リンクされたファイルの内容とメタデータが新しいツリーにコピーされます。

symlinks がfalseの場合、symlinkが指すファイルが存在しないと、コピーの最後にある Error 例外で発生したエラーのリストに例外が追加されます。処理する。 この例外を消音したい場合は、オプションの ignore_dangling_symlinks フラグをtrueに設定できます。 このオプションは、 os.symlink（）をサポートしていないプラットフォームには影響しないことに注意してください。

ignore が指定されている場合、 copytree（）がアクセスしているディレクトリと、が返すコンテンツのリストを引数として受け取る呼び出し可能オブジェクトである必要があります。 os.listdir（）。 copytree（）は再帰的に呼び出されるため、 ignore 呼び出し可能オブジェクトは、コピーされるディレクトリごとに1回呼び出されます。 呼び出し可能オブジェクトは、現在のディレクトリに関連する一連のディレクトリ名とファイル名を返す必要があります（つまり、 2番目の引数の項目のサブセット）; これらの名前は、コピープロセスでは無視されます。 ignore_patterns（）を使用して、globスタイルのパターンに基づいて名前を無視する呼び出し可能オブジェクトを作成できます。

例外が発生すると、エラーが理由のリストとともに発生します。

copy_function が指定されている場合、各ファイルのコピーに使用される呼び出し可能である必要があります。 ソースパスと宛先パスを引数として呼び出されます。 デフォルトでは、 copy2（）が使用されますが、同じ署名をサポートする任意の関数（ copy（）など）を使用できます。

バージョン3.3で変更：シンボリックリンクがfalseの場合にメタデータをコピーします。 dst を返すようになりました。

バージョン3.2で変更：カスタムコピー関数を提供できるように copy_function 引数を追加しました。 symlinks がfalseの場合のサイレントダングリングシンボリックリンクエラーに、 ignore_dangling_symlinks 引数を追加しました。

バージョン3.8で変更：ファイルをより効率的にコピーするために、プラットフォーム固有の高速コピーシステムコールが内部で使用される場合があります。 プラットフォームに依存する効率的なコピー操作セクションを参照してください。

バージョン3.8の新機能： dirs_exist_ok パラメーター。

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

ディレクトリツリー全体を削除します。 パスはディレクトリを指している必要があります（ただし、ディレクトリへのシンボリックリンクではありません）。 ignore_errors がtrueの場合、削除の失敗に起因するエラーは無視されます。 falseまたは省略された場合、そのようなエラーは onerror で指定されたハンドラーを呼び出すことによって処理されます。省略された場合、例外が発生します。

ノート

必要なfdベースの関数をサポートするプラットフォームでは、 rmtree（）のシンボリックリンク攻撃耐性バージョンがデフォルトで使用されます。 他のプラットフォームでは、 rmtree（）の実装はシンボリックリンク攻撃の影響を受けやすくなります。適切なタイミングと状況があれば、攻撃者はファイルシステム上のシンボリックリンクを操作して、他の方法ではアクセスできないファイルを削除できます。 アプリケーションは、 rmtree.avoids_symlink_attacks 関数属性を使用して、どのケースが適用されるかを判別できます。

onerror が指定されている場合は、 function 、 path 、および excinfo の3つのパラメーターを受け入れる呼び出し可能である必要があります。

最初のパラメーター function は、例外を発生させた関数です。 プラットフォームと実装によって異なります。 2番目のパラメーター path は、 function に渡されるパス名になります。 3番目のパラメーター excinfo は、 sys.exc_info（）によって返される例外情報になります。 onerror によって発生した例外はキャッチされません。

バージョン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（）が使用されます。 それ以外の場合、 src は copy_function を使用して dst にコピーされ、削除されます。 シンボリックリンクの場合、 src のターゲットを指す新しいシンボリックリンクが dst 内に作成されるか、 dst として作成されます。 src は削除されます。

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

バージョン3.3で変更：外部ファイルシステムの明示的なシンボリックリンク処理を追加し、GNUの mv の動作に適合させました。 dst を返すようになりました。

バージョン3.5で変更： copy_function キーワード引数を追加しました。

バージョン3.8で変更：ファイルをより効率的にコピーするために、プラットフォーム固有の高速コピーシステムコールが内部で使用される場合があります。 プラットフォームに依存する効率的なコピー操作セクションを参照してください。

shutil.disk_usage(path)

指定されたパスに関するディスク使用統計を、属性 total 、 used 、および free を持つ named tuple として返します。合計、使用済み、および空き領域（バイト単位）。 path は、ファイルまたはディレクトリの場合があります。

バージョン3.3の新機能。

バージョン3.8で変更： Windowsでは、パスをファイルまたはディレクトリにできるようになりました。

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

指定されたパスの所有者ユーザーおよび/またはグループを変更します。

user は、システムユーザー名またはuidにすることができます。 同じことがグループにも当てはまります。 少なくとも1つの引数が必要です。

基礎となる関数である os.chown（）も参照してください。

バージョン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では、デフォルトを使用するか、独自のディレクトリを提供するかに関係なく、現在のディレクトリは常にパスの前に付加されます。これは、実行可能ファイルを検索するときにコマンドシェルが使用する動作です。 さらに、パスで cmd を見つけると、PATHEXT環境変数がチェックされます。 たとえば、shutil.which("python")を呼び出すと、 which（）はPATHEXTを検索して、パス[内でpython.exeを検索する必要があることを認識します。 X136X]ディレクトリ。 たとえば、Windowsの場合：

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

バージョン3.3の新機能。

バージョン3.8で変更： バイトタイプが受け入れられるようになりました。 cmd タイプが bytes の場合、結果タイプも bytes になります。

exception shutil.Error

この例外は、複数ファイル操作中に発生した例外を収集します。 copytree（）の場合、例外引数は3タプルのリストです（ srcname 、 dstname 、 exception ）。

プラットフォームに依存する効率的なコピー操作

Python 3.8以降、ファイルコピーに関連するすべての関数（ copyfile（）、 copy（）、 copy2（）、 copytree（）[X133X ]、および move（））は、ファイルをより効率的にコピーするために、プラットフォーム固有の「高速コピー」システムコールを使用する場合があります（：issue： `33671` を参照）。 「高速コピー」とは、「outfd.write(infd.read())」のようにPythonでユーザースペースバッファーを使用せずに、カーネル内でコピー操作が行われることを意味します。

macOSでは、 fcopyfile を使用してファイルの内容をコピーします（メタデータではありません）。

Linuxでは、 os.sendfile（）が使用されます。

Windowsでは、 shutil.copyfile（）は、より大きなデフォルトのバッファーサイズ（64KiBではなく1MiB）と memoryview（）ベースの shutil.copyfileobj（）のバリアントを使用します。 を使用します。

高速コピー操作が失敗し、宛先ファイルにデータが書き込まれなかった場合、shutilは、効率の低い copyfileobj（）関数を内部で使用してサイレントにフォールバックします。

バージョン3.8で変更されました。

コピーツリーの例

この例は、上記の copytree（）関数の実装であり、docstringは省略されています。 これは、このモジュールによって提供される他の多くの機能を示しています。

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（）ヘルパーを使用する別の例：

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 にchdirします。

base_dir は、アーカイブを開始するディレクトリです。 NS base_dir は、アーカイブ内のすべてのファイルとディレクトリに共通のプレフィックスになります。 base_dir は、 root_dir を基準にして指定する必要があります。 base_dir と root_dir を一緒に使用する方法については、 base_dir を使用したアーカイブの例を参照してください。

root_dir と base_dir はどちらも、デフォルトで現在のディレクトリになります。

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

owner および group は、tarアーカイブを作成するときに使用されます。 デフォルトでは、現在の所有者とグループを使用します。

logger は、 PEP 282 と互換性のあるオブジェクトである必要があり、通常は logging.Logger のインスタンスです。

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

ノート

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

バージョン3.8で変更： format="tar"で作成されたアーカイブには、従来のGNU形式の代わりに最新のpax（POSIX.1-2001）形式が使用されるようになりました。

shutil.get_archive_formats()

アーカイブでサポートされている形式のリストを返します。 返されるシーケンスの各要素はタプル(name, description)です。

デフォルトでは、 shutil は次の形式を提供します。

• zip ：ZIPファイル（ zlib モジュールが使用可能な場合）。

• tar ：非圧縮のtarファイル。 新しいアーカイブにはPOSIX.1-2001pax形式を使用します。

• 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 は、アーカイブを解凍するために使用される呼び出し可能オブジェクトです。 呼び出し可能ファイルは、作成するファイルの base_name を受け取り、続いて base_dir （デフォルトは os.curdir ）を受け取り、アーカイブを開始します。 owner 、 group 、 dry_run 、 logger （ make_archive（）[ X152X]）。

指定した場合、 extra_args は、アーカイバ呼び出し可能オブジェクトが使用されるときに追加のキーワード引数として使用される(name, value)ペアのシーケンスです。

description は、アーカイバのリストを返す get_archive_formats（）によって使用されます。 デフォルトは空の文字列です。

shutil.unregister_archive_format(name)

サポートされている形式のリストからアーカイブ形式 name を削除します。

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

アーカイブを解凍します。 filename はアーカイブのフルパスです。

extract_dir は、アーカイブが解凍されるターゲットディレクトリの名前です。 指定しない場合は、現在の作業ディレクトリが使用されます。

format は、アーカイブ形式です。「zip」、「tar」、「gztar」、「bztar」、または「xztar」のいずれかです。 または、 register_unpack_format（）に登録されているその他の形式。 指定しない場合、 unpack_archive（）はアーカイブファイル名拡張子を使用し、その拡張子にアンパッカーが登録されているかどうかを確認します。 何も見つからない場合は、 ValueError が発生します。

バージョン3.7で変更： ファイル名および extract_dir のパスのようなオブジェクトを受け入れます。

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

アンパック形式を登録します。 name はフォーマットの名前であり、 extension は、Zipファイルの.zipのように、フォーマットに対応する拡張子のリストです。

function は、アーカイブを解凍するために使用される呼び出し可能オブジェクトです。 呼び出し可能オブジェクトは、アーカイブのパスを受け取り、その後にアーカイブを抽出する必要のあるディレクトリを受け取ります。

提供される場合、 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 モジュールが使用可能な場合）。

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 を使用したアーカイブ例

この例では、上記の [[#shutil-archiving-example|]] と同様に、 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))

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

2つの次元のそれぞれについて、環境変数COLUMNSとLINESがそれぞれチェックされます。 変数が定義されていて、値が正の整数の場合、それが使用されます。

COLUMNSまたはLINESが定義されていない場合（一般的なケース）、 sys .__ stdout __ に接続されている端末は、 os.get_terminal_size（）[を呼び出すことによって照会されます。 X169X]。

システムがクエリをサポートしていないか、端末に接続されていないために端末サイズを正常にクエリできない場合は、fallbackパラメータで指定された値が使用されます。 fallbackのデフォルトは(80, 24)です。これは、多くの端末エミュレーターで使用されるデフォルトのサイズです。

返される値は、タイプ os.terminal_size の名前付きタプルです。

参照：Single UNIX Specification、バージョン2、その他の環境変数。

バージョン3.3の新機能。