目次

前のトピックへ

12.3. bz2bzip2 互換の圧縮ライブラリ

次のトピックへ

12.5. tarfile — tar アーカイブファイルを読み書きする

このページ

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

バージョン 1.6 で追加.

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

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

他のアーカイブ形式については、 bz2gzip 、および、 tarfile モジュールを参照下さい。

このモジュールでは、以下の項目が定義されています:

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

アーカイブ中のメンバに関する情報を提供するために用いられるクラスです。このクラスのインスタンスは ZipFile オブジェクトの getinfo() および infolist() メソッドによって返されます。 zipfile モジュールを利用するほとんどのユーザはこのオブジェクトを自ら生成する必要はなく、モジュールが生成して返すオブジェクトを利用するだけでしょう。 filename はアーカイブメンバの完全な名前で、 date_time はファイルの最終更新時刻を記述する、6つのフィールドからなるタプルでなくてはなりません。各フィールドについては ZipInfo オブジェクト 節を参照してください。

zipfile.is_zipfile(filename)

filename が正しいマジックナンバをもつ ZIP ファイルのときに True を返し、そうでない場合 False を返します。

zipfile.ZIP_STORED

アーカイブメンバが圧縮されていないことを表す数値定数です。

zipfile.ZIP_DEFLATED

通常の ZIP 圧縮手法を表す数値定数。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

cat myzip.zip >> python.exe

として追加することができ、少なくとも WinZip がこのようなファイルを読めることを意味します。もし、 modea で、かつ、ファイルが存在しなかった場合、新規に作成されます。 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.6 で変更: mode が ‘a’ でファイルが存在しない場合、ファイルが作られるようになりました。

ZipFile.close()

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

ZipFile.getinfo(name)

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

ZipFile.infolist()

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

ZipFile.namelist()

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

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

アーカイブからメンバーを file-like オブジェクト (ZipExtFile) として展開します。 name はアーカイブに含まれるファイル名、もしくは、 ZipInfo オブジェクトです。 mode パラメーターを指定するならば、以下のうちのどれかである必要があります: 'r' (デフォルト)、 'U''rU' 'U''rU' を選ぶと、読み出し専用オブジェクトにおいて universal newline support が有効化されます。 pwd は、暗号化ファイルで使われるパスワードです。閉じられた ZIP ファイルに対して open() を呼び出すと、 RuntimeError が送出されます。

ノート

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

ノート

file-like オブジェクトをコンストラクターの第一引数として、 ZipFile が作成された場合、 ZipFile のファイルポインターを使った open() メソッドにより、オブジェクトが返されます。この場合、 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 で追加.

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

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

警告

信頼できないソースからきた Zip ファイルを、事前に中身をチェックせずに展開してはいけません。ファイルを path の外側に作成することができるからです。例えば、 "/" で始まる絶対パスを持ったメンバーや、 2 つのドット ".." を持つファイル名などの場合です。

バージョン 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 ファイル中のファイル名に関する公式なエンコーディング方式はありません。もしユニコードのファイル名が付けられているならば、それを write() に渡す前に望ましいエンコーディングでバイト列に変換しなければなりません。 WinZip は全てのファイル名を DOS Latin としても知られる CP437 で解釈します。

ノート

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

ノート

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

ZipFile.writestr(zinfo_or_arcname, bytes)

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

ノート

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

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

ZipFile.debug

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

ZipFile.comment

ZIP ファイルの付けられたコメントです。モードが ‘a’、または、’w’で作成された ZipFile インスタンスにコメントを付ける場合、コメント 65535 byte 以下の文字列でなければなりません。コメントがそれより長い場合、アーカイブでは、 ZipFile.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                    # トップレベル名
test/__init__.pyc             # パッケージディレクトリ
test/test_support.pyc         # test.test_suport モジュール
test/bogus/__init__.pyc       # サブパッケージディレクトリ
test/bogus/myfile.pyc         # test.bogus.myfile サブモジュール

12.4.3. ZipInfo オブジェクト

ZipFile オブジェクトの getinfo() および infolist() メソッドは ZipInfo クラスのインスタンスを返します。それぞれのインスタンスオブジェクトは ZIP アーカイブの一個のメンバについての情報を保持しています。

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

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

ZipInfo.date_time

アーカイブメンバの最終更新日時。この属性は6つの値からなるタプルです。:

Index Value
0 西暦年
1 月 (1 から始まる)
2 日 (1 から始まる)
3 時 (0 から始まる)
4 分 (0 から始まる)
5 秒 (0 から始まる)
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

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