12.4. zipfile — ZIP アーカイブの処理

バージョン 1.6 で追加.

ソースコード: Lib/zipfile.py


ZIP は一般によく知られているアーカイブ (書庫化) および圧縮の標準ファイルフォーマットです。このモジュールでは ZIP 形式のファイルの作成、読み書き、追記、書庫内のファイル一覧の作成を行うためのツールを提供します。より高度な使い方でこのモジュールを利用したいのであれば、 PKZIP Application Note に定義されている ZIP ファイルフォーマットの理解が必要になるでしょう。

このモジュールは現在マルチディスク ZIP ファイルを扱うことはできません。ZIP64 拡張を利用する ZIP ファイル (サイズが 4 GiB を超えるような ZIP ファイル) は扱えます。このモジュールは暗号化されたアーカイブの復号をサポートしますが、現在暗号化ファイルを作成することはできません。C 言語ではなく、Python で実装されているため、復号は非常に遅くなっています。

このモジュールは以下の項目を定義しています:

exception zipfile.BadZipfile

正常ではない ZIP ファイルに対して送出されるエラーです (旧名称: zipfile.error)。

exception zipfile.LargeZipFile

ZIP ファイルが ZIP64 の機能を必要としているが、その機能が有効化されていない場合に送出されるエラーです。

class zipfile.ZipFile

ZIP ファイルの読み書きのためのクラスです。コンストラクタの詳細については、ZipFile オブジェクト 節を参照してください。

class zipfile.PyZipFile

Python ライブラリを含む、ZIP アーカイブを作成するためのクラスです。

class zipfile.ZipInfo([filename[, date_time]])

アーカイブ内の 1 個のメンバの情報を取得するために使うクラスです。このクラスのインスタンスは ZipFile オブジェクトの getinfo() および infolist() メソッドを返します。ほとんどの zipfile モジュールの利用者はこれらを作成する必要はなく、このモジュールによって作成されたものを使用できます。filename はアーカイブメンバのフルネームでなければならず、date_time はファイルが最後に変更された日時を表す 6 個のフィールドのタプルでなければなりません; フィールドは ZipInfo オブジェクト 節で説明されています。

zipfile.is_zipfile(filename)

filename が正しいマジックナンバをもつ ZIP ファイルの時に True を返し、そうでない場合 False を返します。filename にはファイルやファイルライクオブジェクトを渡すこともできます。

バージョン 2.7 で変更: ファイルおよびファイルライクオブジェクトをサポートしました。

zipfile.ZIP_STORED

アーカイブメンバを圧縮しない (複数ファイルを一つにまとめるだけ) ことを表す数値定数です。

zipfile.ZIP_DEFLATED

通常の ZIP 圧縮方法を表す数値定数です。これには zlib モジュールが必要です。現在のところ他の圧縮手法はサポートされていません。

参考

PKZIP Application Note
ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz によるドキュメント。
Info-ZIP Home Page
Info-ZIP プロジェクトによる ZIP アーカイブプログラムおよびプログラム開発ライブラリに関する情報。

12.4.1. ZipFile オブジェクト

class zipfile.ZipFile(file[, mode[, compression[, allowZip64]]])

ZIP ファイルを開きます。 file はファイルへのパス名 (文字列) またはファイルのように振舞うオブジェクトのどちらでもかまいません。 mode パラメタは、既存のファイルを読むためには 'r' 、既存のファイルを切り詰めたり新しいファイルに書き込むためには 'w' 、追記を行うためには 'a' でなくてはなりません。 mode'a'file が既存の ZIP ファイルを参照している場合、追加するファイルは既存のファイル中の ZIP アーカイブに追加されます。 file が ZIP を参照していない場合、新しい ZIP アーカイブが生成され、既存のファイルの末尾に追加されます。このことは、ある ZIP ファイルを他のファイル(例えば python.exe)に追加することを意味しています。

バージョン 2.6 で変更: mode'a' でファイルが存在しない場合、ファイルが作られるようになりました。

compression はアーカイブを書き出すときの ZIP 圧縮法で、 ZIP_STORED または ZIP_DEFLATED でなくてはなりません。不正な値を指定すると RuntimeError が送出されます。また、 ZIP_DEFLATED 定数が指定されているのに zlib モジュールを利用することができない場合も、 RuntimeError が送出されます。デフォルト値は ZIP_STORED です。 allowZip64True ならば 2GB より大きな ZIP ファイルの作成時に ZIP64 拡張を使用します。これが False (デフォルト) ならば、 zipfile モジュールは ZIP64 拡張が必要になる場面で例外を送出します。 ZIP64 拡張はデフォルトでは無効にされていますが、これは Unix の zip および unzip (InfoZIP ユーティリティ) コマンドがこの拡張をサポートしていないからです。

バージョン 2.7.1 で変更: ファイルがモード 'a' または 'w' で作成され、その後そのアーカイブにファイルを追加することなく クローズ された場合、空のアーカイブのための適切な ZIP 構造がファイルに書き込まれます。

ZipFile はコンテキストマネージャにもなっているので、with 文をサポートしています。次の例では、myzipwith 文のブロックが終了したときに、(たとえ例外が発生したとしても) クローズされます:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

バージョン 2.7 で追加: ZipFile をコンテキストマネージャとして使用できるようになりました。

ZipFile.close()

アーカイブファイルをクローズします。close() はプログラムを終了する前に必ず呼び出さなければなりません。さもないとアーカイブ上の重要なレコードが書き込まれません。

ZipFile.getinfo(name)

アーカイブメンバ name に関する情報を持つ ZipInfo オブジェクトを返します。アーカイブに含まれないファイル名に対して getinfo() を呼び出すと、KeyError が送出されます。

ZipFile.infolist()

アーカイブに含まれる各メンバの ZipInfo オブジェクトからなるリストを返します。既存のアーカイブファイルを開いている場合、リストの順番は実際の ZIP ファイル中のメンバの順番と同じになります。

ZipFile.namelist()

アーカイブメンバの名前のリストを返します。

ZipFile.open(name[, mode[, pwd]])

ファイルライクオブジェクト (ZipExtFile) としてのアーカイブからメンバを 1 個展開します。 name はアーカイブ内のファイルか、または ZipInfo オブジェクトの名前です。 mode パラメータを指定する場合、次の中のどれか一つでなければなりません: 'r' (デフォルト)、 'U'` `、または ``'rU''U' または 'rU' を選択すると、読み込み専用オブジェクトでは ユニバーサル改行 サポートが有効になります。 pwd は暗号化ファイルで使用されているパスワードです。クローズしたファイルに対して open() が呼び出されると、 RuntimeError が送出されます。

注釈

file-like オブジェクトは読み出し専用で、以下のメソッドを提供します: read(), readline(), readlines(), __iter__(), next()

注釈

ファイルライクオブジェクトをコンストラクタの第一引数として ZipFile ファイルが作成された場合、open() メソッドが返したオブジェクトは ZipFile のファイルポインタを共有します。この場合、open() が返したオブジェクトを、ZipFile オブジェクトに対する追加操作後に使用してはいけません。もし、ZipFile が文字列 (ファイル名) をコンストラクタに対する第一引数として作成された場合は、open() は ZipExtFile に含まれる、新しいファイルオブジェクトを作成します。これは ZipFile と独立して操作できます。

注釈

open()read()、および extract() メソッドには、ファイル名または ZipInfo オブジェクトを指定できます。これは重複する名前のメンバを含む ZIP ファイルを読み込むときにそのメリットを享受できるでしょう。

バージョン 2.6 で追加.

ZipFile.extract(member[, path[, pwd]])

メンバをアーカイブから現在の作業ディレクトリに展開します。member は展開するファイルのフルネームまたは ZipInfo オブジェクトでなければなりません。ファイル情報は可能な限り正確に展開されます。path は展開先のディレクトリを指定します。member はファイル名または ZipInfo オブジェクトです。pwd は暗号化ファイルに使われるパスワードです。

作成された (ディレクトリか新ファイルの) 正規化されたパスを返します。

バージョン 2.6 で追加.

注釈

メンバのファイル名が絶対パスなら、ドライブ/UNC sharepoint および先頭の (バック) スラッシュは取り除かれます。例えば、Unix で ///foo/barfoo/bar となり、Window で C:\foo\barfoo\bar となります。また、メンバのファイル名に含まれる全ての ".." は取り除かれます。例えば、../../foo../../ba..rfoo../ba..r となります。Windows では、不正な文字 (:, <, >, |, ", ?, および *) はアンダースコア (_) で置き換えられます。

ZipFile.extractall([path[, members[, pwd]]])

すべてのメンバをアーカイブから現在の作業ディレクトリに展開します。path は展開先のディレクトリを指定します。members は、オプションで、namelist() で返されるリストの部分集合でなければなりません。pwd は、暗号化ファイルに使われるパスワードです。

警告

内容を信頼できない tar アーカイブを、事前の内部チェック前に展開してはいけません。ファイルが path の外側に作られる可能性があります。例えば、"/" で始まる絶対パスのファイル名や、2 重ドット ".." で始まるパスのファイル名です。

バージョン 2.7.4 で変更: zipfile モジュールは、それを防ごうと試みます。extract() の注を参照してください。

バージョン 2.6 で追加.

ZipFile.printdir()

アーカイブの内容の一覧を sys.stdout に出力します。

ZipFile.setpassword(pwd)

pwd を展開する圧縮ファイルのデフォルトパスワードとして指定します。

バージョン 2.6 で追加.

ZipFile.read(name[, pwd])

アーカイブ中のファイル名 name の内容をバイト列にして返します。name はアーカイブに含まれるファイル、もしくは、ZipInfo オブジェクトの名前です。アーカイブは読み込みまたは追記モードでオープンされていなくてはなりません。pwd は暗号化されたファイルのパスワードで、指定された場合、setpassword() で指定されたデフォルトのパスワードを上書きします。クローズした ZipFile に対し read() を呼び出すと、RuntimeError が送出されます。

バージョン 2.6 で変更: pwd が追加され、 nameZipInfo オブジェクトを指定できるようになりました。

ZipFile.testzip()

アーカイブ中のすべてのファイルを読み、CRC チェックサムとヘッダが正常か調べます。最初に見つかった不正なファイルの名前を返します。不正なファイルがなければ None を返します。クローズした ZipFile に対して testzip() メソッドを呼び出すと、RuntimeError が送出されます。

ZipFile.write(filename[, arcname[, compress_type]])

ファイル filename を、アーカイブ名 arcname (デフォルトは filename からドライブレターとパスセパレータを取り除いたもの) へ書き込みます。compress_type を指定した場合、コンストラクタを使って新たなアーカイブエントリを生成した際に使った compression パラメタを上書きします。アーカイブのモードは 'w' または 'a' でなくてはなりません。モードが 'r' で作成された ZipFile に対し write() メソッドを呼び出すと RuntimeError が送出されます。クローズした ZipFile に対し write() メソッドを呼び出すと RuntimeError が送出されます。

注釈

ZIP ファイル中のファイル名に関する公式なエンコーディングはありません。Unicode のファイル名が付けられている場合は、それを write() に渡す前に望ましいエンコーディングでバイト列に変換しなければなりません。WinZip はすべてのファイル名を DOS Latin としても知られる CP437 で解釈します。

注釈

アーカイブ名はアーカイブルートに対する相対パスでなければなりません。言い換えると、アーカイブ名はパスセパレータで始まってはいけません。

注釈

もし、arcname (arcname が与えられない場合は、filename) が null byte を含むなら、アーカイブ中のファイルのファイル名は、null byte までで切り詰められます。

ZipFile.writestr(zinfo_or_arcname, bytes[, compress_type])

文字列 bytes をアーカイブに書き込みます。zinfo_or_arcname には、アーカイブ中で指定するファイル名か、または ZipInfo インスタンスを指定します。zinfo_or_arcnameZipInfo インスタンスを指定する場合、zinfo インスタンスには少なくともファイル名、日付および時刻を指定しなければなりません。ファイル名を指定した場合、日付と時刻には現在の日付と時間が設定されます。アーカイブはモード 'w' または 'a' でオープンされていなければなりません。 モード 'r' で作成された ZipFile に対し writestr() メソッドを呼び出すと RuntimeError が送出されます。クローズした ZipFile に対し writestr() メソッドを呼び出すと RuntimeError が送出されます。

compress_type が指定された場合、その値はコンストラクタに与えられた compression の値か、zinfo_or_arcnameZipInfo のインスタンスだったときはその値をオーバーライドします。

注釈

ZipInfo インスタンスを引数 zinfo_or_arcname として与えた場合、与えられた ZipInfo インスタンスのメンバーである compress_type で指定された圧縮方法が使われます。デフォルトでは、ZipInfo コンストラクターが、このメンバーを ZIP_STORED に設定します。

バージョン 2.7 で変更: 引数 compress_type を追加しました。

以下のデータ属性も利用することができます:

ZipFile.debug

使用するデバッグ出力レベルです。この属性は 0 (デフォルト、何も出力しない) から 3 (最も多く出力する) までの値に設定することができます。デバッグ情報は sys.stdout に出力されます。

ZipFile.comment

ZIP ファイルに関連付けられたコメント文字列です。モード 'a' または 'w' で作成された ZipFile インスタンスへコメントを割り当てる場合、文字列長は 65535 バイトまでで、それを超えた場合は close() が呼び出されてアーカイブへ書き込む際に切り捨てられます。

12.4.2. PyZipFile オブジェクト

PyZipFile コンストラクタは ZipFile コンストラクタと同じパラメータを取ります。インスタンスは ZipFile のメソッドの他に、追加のメソッドを一つ持ちます。

PyZipFile.writepy(pathname[, basename])

*.py ファイルを探し、 *.py ファイルに対応するファイルをアーカイブに追加します。対応するファイルとは、もしあれば *.pyo であり、そうでなければ *.pyc で、必要に応じて *.py からコンパイルします。もし pathname がファイルなら、ファイル名は .py で終わっていなければなりません。また、(*.py に対応する *.py[co]) ファイルはアーカイブのトップレベルに (パス情報なしで) 追加されます。もし pathname が .py で終わらないファイル名なら RuntimeError を送出します。もし pathname がディレクトリで、ディレクトリがパッケージディレクトリでないなら、全ての *.py[co] ファイルはトップレベルに追加されます。もしディレクトリがパッケージディレクトリなら、全ての *.py[co] ファイルはパッケージ名の名前をもつファイルパスの下に追加されます。サブディレクトリがパッケージディレクトリなら、それらは再帰的に追加されます。 basename はクラス内部での呼び出しに使用するためのものです。 writepy() メソッドは以下のようなファイル名を持ったアーカイブを生成します。

string.pyc                                # Top level name
test/__init__.pyc                         # Package directory
test/test_support.pyc                          # Module test.test_support
test/bogus/__init__.pyc                   # Subpackage directory
test/bogus/myfile.pyc                     # Submodule test.bogus.myfile

12.4.3. ZipInfo オブジェクト

ZipInfo クラスのインスタンスは、ZipFile オブジェクトの getinfo() および infolist() メソッドによって返されます。各オブジェクトは ZIP アーカイブ内の 1 個のメンバに関する情報を格納します。

インスタンスは以下の属性を持ちます:

ZipInfo.filename

アーカイブ中のファイル名。

ZipInfo.date_time

アーカイブメンバの最終更新日時。6 つの値からなるタプルになります:

インデックス
0 西暦年 (>= 1980)
1 月 (1 から始まる)
2 日 (1 から始まる)
3 時 (0 から始まる)
4 分 (0 から始まる)
5 秒 (0 から始まる)

注釈

ZIP ファイルフォーマットは 1980 年より前のタイムスタンプをサポートしていません。

ZipInfo.compress_type

アーカイブメンバの圧縮形式。

ZipInfo.comment

各アーカイブメンバに対するコメント。

ZipInfo.extra

拡張フィールドデータ。この文字列に含まれているデータの内部構成については、PKZIP Application Note でコメントされています。

ZipInfo.create_system

ZIP アーカイブを作成したシステムを記述する文字列。

ZipInfo.create_version

このアーカイブを作成した PKZIP のバージョン。

ZipInfo.extract_version

このアーカイブを展開する際に必要な PKZIP のバージョン。

ZipInfo.reserved

予約領域。ゼロでなくてはなりません。

ZipInfo.flag_bits

ZIP フラグビット列。

ZipInfo.volume

ファイルヘッダのボリューム番号。

ZipInfo.internal_attr

内部属性。

ZipInfo.external_attr

外部ファイル属性。

ZipInfo.header_offset

ファイルヘッダへのバイトオフセット。

ZipInfo.CRC

圧縮前のファイルの CRC-32 チェックサム。

ZipInfo.compress_size

圧縮後のデータのサイズ。

ZipInfo.file_size

圧縮前のファイルのサイズ。

12.4.4. コマンドラインインターフェイス

zipfile モジュールは、 ZIP アーカイブを操作するための簡単なコマンドラインインターフェースを提供しています。

ZIP アーカイブを新規に作成したい場合、-c オプションの後にまとめたいファイルを列挙してください:

$ python -m zipfile -c monty.zip spam.txt eggs.txt

ディレクトリを渡すこともできます:

$ python -m zipfile -c monty.zip life-of-brian_1979/

ZIP アーカイブを特定のディレクトリに展開したい場合、-e オプションを使用してください:

$ python -m zipfile -e monty.zip target-dir/

ZIP アーカイブ内のファイル一覧を表示するには -l を使用してください:

$ python -m zipfile -l monty.zip

12.4.4.1. コマンドラインオプション

-l <zipfile>

zipfile 内のファイル一覧を表示します。

-c <zipfile> <source1> ... <sourceN>

ソースファイルから zipfile を作成します。

-e <zipfile> <output_dir>

zipfile を対象となるディレクトリに展開します。

-t <zipfile>

zipfile が有効かどうか調べます。