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¶ アーカイブメンバを圧縮しない (複数ファイルを一つにまとめるだけ) ことを表す数値定数です。
参考
- 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です。 allowZip64 がTrueならば 2GB より大きな ZIP ファイルの作成時に ZIP64 拡張を使用します。これがFalse(デフォルト) ならば、zipfileモジュールは ZIP64 拡張が必要になる場面で例外を送出します。 ZIP64 拡張はデフォルトでは無効にされていますが、これは Unix の zip および unzip (InfoZIP ユーティリティ) コマンドがこの拡張をサポートしていないからです。バージョン 2.7.1 で変更: ファイルがモード
'a'または'w'で作成され、その後そのアーカイブにファイルを追加することなくクローズされた場合、空のアーカイブのための適切な ZIP 構造がファイルに書き込まれます。ZipFile はコンテキストマネージャにもなっているので、
with文をサポートしています。次の例では、myzip はwith文のブロックが終了したときに、(たとえ例外が発生したとしても) クローズされます: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/barはfoo/barとなり、Window でC:\foo\barはfoo\barとなります。また、メンバのファイル名に含まれる全ての".."は取り除かれます。例えば、../../foo../../ba..rはfoo../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 が追加され、 name に
ZipInfoオブジェクトを指定できるようになりました。
-
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_arcname にZipInfoインスタンスを指定する場合、zinfo インスタンスには少なくともファイル名、日付および時刻を指定しなければなりません。ファイル名を指定した場合、日付と時刻には現在の日付と時間が設定されます。アーカイブはモード'w'または'a'でオープンされていなければなりません。 モード'r'で作成された ZipFile に対しwritestr()メソッドを呼び出すとRuntimeErrorが送出されます。クローズした ZipFile に対しwritestr()メソッドを呼び出すとRuntimeErrorが送出されます。compress_type が指定された場合、その値はコンストラクタに与えられた compression の値か、zinfo_or_arcname が
ZipInfoのインスタンスだったときはその値をオーバーライドします。注釈
ZipInfoインスタンスを引数 zinfo_or_arcname として与えた場合、与えられたZipInfoインスタンスのメンバーである compress_type で指定された圧縮方法が使われます。デフォルトでは、ZipInfoコンストラクターが、このメンバーをZIP_STOREDに設定します。バージョン 2.7 で変更: 引数 compress_type を追加しました。
以下のデータ属性も利用することができます:
-
ZipFile.debug¶ 使用するデバッグ出力レベルです。この属性は
0(デフォルト、何も出力しない) から3(最も多く出力する) までの値に設定することができます。デバッグ情報はsys.stdoutに出力されます。
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