13.5. zipfile — ZIP アーカイブの処理¶
ソースコード: Lib/zipfile.py
ZIP は一般によく知られているアーカイブ (書庫化) および圧縮の標準ファイルフォーマットです。このモジュールでは ZIP 形式のファイルの作成、読み書き、追記、書庫内のファイル一覧の作成を行うためのツールを提供します。より高度な使い方でこのモジュールを利用したいのであれば、 PKZIP Application Note に定義されている ZIP ファイルフォーマットの理解が必要になるでしょう。
このモジュールは現在マルチディスク ZIP ファイルを扱うことはできません。ZIP64 拡張を利用する ZIP ファイル (サイズが 4 GiB を超えるような ZIP ファイル) は扱えます。このモジュールは暗号化されたアーカイブの復号をサポートしますが、現在暗号化ファイルを作成することはできません。C 言語ではなく、Python で実装されているため、復号は非常に遅くなっています。
このモジュールは以下の項目を定義しています:
-
exception
zipfile.BadZipFile¶ 正常ではない ZIP ファイルに対して送出されるエラーです。
バージョン 3.2 で追加.
-
exception
zipfile.BadZipfile¶ BadZipFileの別名です。過去のバージョンの Python との互換性のために用意されています。バージョン 3.2 で撤廃.
-
exception
zipfile.LargeZipFile¶ ZIP ファイルが ZIP64 の機能を必要としているが、その機能が有効化されていない場合に送出されるエラーです。
-
class
zipfile.ZipFile ZIP ファイルの読み書きのためのクラスです。コンストラクタの詳細については、ZipFile オブジェクト 節を参照してください。
-
class
zipfile.PyZipFile Python ライブラリを含む、ZIP アーカイブを作成するためのクラスです。
-
class
zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))¶ アーカイブ内の 1 個のメンバの情報を取得するために使うクラスです。このクラスのインスタンスは
ZipFileオブジェクトのgetinfo()およびinfolist()メソッドを返します。ほとんどのzipfileモジュールの利用者はこれらを作成する必要はなく、このモジュールによって作成されたものを使用できます。filename はアーカイブメンバのフルネームでなければならず、date_time はファイルが最後に変更された日時を表す 6 個のフィールドのタプルでなければなりません; フィールドは ZipInfo オブジェクト 節で説明されています。
-
zipfile.is_zipfile(filename)¶ filename が正しいマジックナンバをもつ ZIP ファイルの時に
Trueを返し、そうでない場合Falseを返します。filename にはファイルやファイルライクオブジェクトを渡すこともできます。バージョン 3.1 で変更: ファイルおよびファイルライクオブジェクトをサポートしました。
-
zipfile.ZIP_STORED¶ アーカイブメンバを圧縮しない (複数ファイルを一つにまとめるだけ) ことを表す数値定数です。
-
zipfile.ZIP_LZMA¶ LZMA 圧縮方法を表す数値定数です。これには
lzmaモジュールが必要です。バージョン 3.3 で追加.
注釈
ZIP ファイルフォーマット仕様は 2001 年より bzip2 圧縮を、2006 年より LZMA 圧縮をサポートしていますが、(過去の Python リリースを含む) 一部のツールはこれら圧縮方式をサポートしていないため、ZIP ファイルの処理を全く受け付けないか、あるいは個々のファイルの抽出に失敗する場合があります。
参考
- PKZIP Application Note
ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz によるドキュメント。
- Info-ZIP Home Page
Info-ZIP プロジェクトによる ZIP アーカイブプログラムおよびプログラム開発ライブラリに関する情報。
13.5.1. ZipFile オブジェクト¶
-
class
zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True)¶ ZIP ファイルを開きます。 file はファイルへのパス (文字列) またはファイルライクオブジェクトのどちらでも構いません。 パラメータ mode は、既存のファイルからの読み込む
'r'、ファイルを上書きまたは新規に作成する'w'、既存のファイルに追記する'a'、あるいは排他的に開く'x'でなければなりません。 mode が'x'で file が既存のファイルを参照している場合、FileExistsErrorが送出されます。 mode が'a'で file が既存の ZIP ファイルを参照している場合、追加するファイルはその ZIP ファイルに追加されます。 file が ZIP ファイルを参照していない場合、新しく作成したアーカイブがそのファイルに追加されます。 これは、ZIP ファイルを他のファイル (例えばpython.exe) に追加することを意味します。 mode が'a'でファイルが存在しない場合、ファイルが新規に作成されます。 mode が'r'または'a'の場合、ファイルは seek 可能のはずです。 compression はアーカイブに書き込む時の ZIP 圧縮方式で、ZIP_STORED,ZIP_DEFLATED,ZIP_BZIP2,ZIP_LZMAのいずれかでなければなりません; 不正な値を指定するとRuntimeErrorが送出されます。ZIP_DEFLATED,ZIP_BZIP2,ZIP_LZMAのいずれかが指定された場合、対応するモジュール (zlib,bz2もしくはlzma) が利用できないとRuntimeErrorが送出されます。 デフォルトはZIP_STOREDです。 allowZip64 に (デフォルトの)Trueを指定すると、zipfile は ZIP ファイルの大きさが 2 GiB を超える場合に ZIP64 拡張を使用して ZIP ファイルを作成します。 False の場合、zipfileは ZIP ファイルが ZIP64 拡張を要求した時点で例外を送出します。ファイルがモード
'w'、'x'または'a'で作成され、その後そのアーカイブにファイルを追加することなくクローズされた場合、空のアーカイブのための適切な ZIP 構造がファイルに書き込まれます。ZipFile はコンテキストマネージャにもなっているので、
with文をサポートしています。次の例では、myzip はwith文のブロックが終了したときに、(たとえ例外が発生したとしても) クローズされます:with ZipFile('spam.zip', 'w') as myzip: myzip.write('eggs.txt')
バージョン 3.2 で追加:
ZipFileをコンテキストマネージャとして使用できるようになりました。バージョン 3.4 で変更: ZIP64 拡張がデフォルトで有効になりました。
バージョン 3.5 で変更: seek 出来ないストリームのサポートが追加されました。
'x'モードのサポートが追加されました。
-
ZipFile.close()¶ アーカイブファイルをクローズします。
close()はプログラムを終了する前に必ず呼び出さなければなりません。さもないとアーカイブ上の重要なレコードが書き込まれません。
-
ZipFile.getinfo(name)¶ アーカイブメンバ name に関する情報を持つ
ZipInfoオブジェクトを返します。アーカイブに含まれないファイル名に対してgetinfo()を呼び出すと、KeyErrorが送出されます。
-
ZipFile.infolist()¶ アーカイブに含まれる各メンバの
ZipInfoオブジェクトからなるリストを返します。既存のアーカイブファイルを開いている場合、リストの順番は実際の ZIP ファイル中のメンバの順番と同じになります。
-
ZipFile.namelist()¶ アーカイブメンバの名前のリストを返します。
-
ZipFile.open(name, mode='r', pwd=None)¶ ファイルライクオブジェクト (ZipExtFile) としてのアーカイブからメンバを 1 個展開します。name はアーカイブ内のファイルか、または
ZipInfoオブジェクトの名前です。mode パラメータを指定する場合、次の中のどれか一つでなければなりません:'r'(デフォルト)、'U'、または'rU'。'U'or'rU'を選択すると、読み込み専用オブジェクトでは ユニバーサル改行 サポートが有効になります。pwd は暗号化ファイルで使用されているパスワードです。クローズしたファイルに対してopen()が呼び出されると、RuntimeErrorが送出されます。open()はコンテクストマネージャでもあるのでwith文をサポートしています:with ZipFile('spam.zip') as myzip: with myzip.open('eggs.txt') as myfile: print(myfile.read())
注釈
file-like オブジェクトは読み出し専用で、以下のメソッドを提供します:
read(),readline(),readlines(),__iter__(),__next__().注釈
open()から返されるオブジェクトは、ZipFile とは独立して機能します。注釈
open()、read()、およびextract()メソッドには、ファイル名またはZipInfoオブジェクトを指定できます。これは重複する名前のメンバを含む ZIP ファイルを読み込むときにそのメリットを享受できるでしょう。バージョン 3.4 で非推奨、バージョン 3.6 で削除予定。’U’ や ‘rU’ モード。 圧縮されたテキストファイルを universal newlines モードで読み込むには io.TextIOWrapper を使用してください。
-
ZipFile.extract(member, path=None, pwd=None)¶ メンバをアーカイブから現在の作業ディレクトリに展開します。member は展開するファイルのフルネームまたは
ZipInfoオブジェクトでなければなりません。ファイル情報は可能な限り正確に展開されます。path は展開先のディレクトリを指定します。member はファイル名またはZipInfoオブジェクトです。pwd は暗号化ファイルに使われるパスワードです。作成された (ディレクトリか新ファイルの) 正規化されたパスを返します。
注釈
メンバのファイル名が絶対パスなら、ドライブ/UNC sharepoint および先頭の (バック) スラッシュは取り除かれます。例えば、Unix で
///foo/barはfoo/barとなり、Window でC:\foo\barはfoo\barとなります。また、メンバのファイル名に含まれる全ての".."は取り除かれます。例えば、../../foo../../ba..rはfoo../ba..rとなります。Windows では、不正な文字 (:,<,>,|,",?, および*) はアンダースコア (_) で置き換えられます。
-
ZipFile.extractall(path=None, members=None, pwd=None)¶ すべてのメンバをアーカイブから現在の作業ディレクトリに展開します。path は展開先のディレクトリを指定します。members は、オプションで、
namelist()で返されるリストの部分集合でなければなりません。pwd は、暗号化ファイルに使われるパスワードです。警告
信頼できないソースからきた Zip ファイルを、事前に中身をチェックせずに展開してはいけません。ファイルを path の外側に作成することができるからです。例えば、
"/"で始まる絶対パスを持ったメンバーや、 2 つのドット".."を持つファイル名などの場合です。このモジュールはそれを避けようとします。extract()の注釈を参照してください。
-
ZipFile.printdir()¶ アーカイブの内容の一覧を
sys.stdoutに出力します。
-
ZipFile.setpassword(pwd)¶ pwd を展開する圧縮ファイルのデフォルトパスワードとして指定します。
-
ZipFile.read(name, pwd=None)¶ アーカイブ中のファイル名 name の内容をバイト列にして返します。 name はアーカイブに含まれるファイル、もしくは、
ZipInfoオブジェクトの名前です。アーカイブは読み込みまたは追記モードで開かれていなくてはなりません。 pwd は暗号化されたファイルのパスワードで、指定された場合、setpassword()で指定されたデフォルトのパスワードを上書きします。閉じられた ZipFile に対しread()を呼び出すと、RuntimeErrorが送出されます。ZIP_STORED,ZIP_DEFLATED,ZIP_BZIP2,ZIP_LZMA以外の圧縮方法とともにread()を呼び出すと、NotImplementedErrorが送出されます。対応する圧縮モジュールが利用可能でない場合にも同様に、例外が送出されます。
-
ZipFile.testzip()¶ アーカイブ中のすべてのファイルを読み、CRC チェックサムとヘッダが正常か調べます。最初に見つかった不正なファイルの名前を返します。不正なファイルがなければ
Noneを返します。クローズした ZipFile に対してtestzip()メソッドを呼び出すと、RuntimeErrorが送出されます。
-
ZipFile.write(filename, arcname=None, compress_type=None)¶ ファイル filename を、アーカイブ名 arcname (デフォルトは filename からドライブレターとパスセパレータを取り除いたもの) へ書き込みます。compress_type を指定した場合、コンストラクタを使って新たなアーカイブエントリを生成した際に使った compression 引数を上書きします。アーカイブのモードは
'w'、'x'または'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, data[, compress_type])¶ 文字列 data をアーカイブに書き込みます。zinfo_or_arcname には、アーカイブ中で指定するファイル名か、または
ZipInfoインスタンスを指定します。zinfo_or_arcname にZipInfoインスタンスを指定する場合、zinfo インスタンスには少なくともファイル名、日付および時刻を指定しなければなりません。ファイル名を指定した場合、日付と時刻には現在の日付と時間が設定されます。アーカイブはモード'w'、'x'または'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に設定します。バージョン 3.2 で変更: 引数 compress_type を追加しました。
以下のデータ属性も利用することができます:
-
ZipFile.debug¶ 使用するデバッグ出力レベルです。この属性は
0(デフォルト、何も出力しない) から3(最も多く出力する) までの値に設定することができます。デバッグ情報はsys.stdoutに出力されます。
13.5.2. PyZipFile オブジェクト¶
PyZipFile コンストラクタは ZipFile コンストラクタと同じパラメータに加え、optimize パラメータをとります。
-
class
zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)¶ バージョン 3.2 で追加: パラメータに optimize を追加しました。
バージョン 3.4 で変更: ZIP64 拡張がデフォルトで有効になりました。
インスタンスは
ZipFileオブジェクトのメソッドの他に、追加のメソッドを 1 個持ちます:-
writepy(pathname, basename='', filterfunc=None)¶ *.pyファイルを探し、一致するファイルをアーカイブに追加します。PyZipFileに optimize 引数が与えられない場合、あるいは-1が指定された場合、対応するファイルは*.pycファイルで、必要に応じてコンパイルします。PyZipFileの optimize パラメータが0、1、あるいは2の場合、それを最適化レベル (compile()参照) とするファイルのみが、必要に応じてコンパイルされアーカイブに追加されます。If pathname is a file, the filename must end with
.py, and just the (corresponding*.pyc) file is added at the top level (no path information). If pathname is a file that does not end with.py, aRuntimeErrorwill be raised. If it is a directory, and the directory is not a package directory, then all the files*.pycare added at the top level. If the directory is a package directory, then all*.pycare added under the package name as a file path, and if any subdirectories are package directories, all of these are added recursively.basename は内部が使用するためだけのものです。
filterfunc を与える場合、単一の文字列引数を取る関数を渡してください。これには(個々のフルパスを含む)それぞれのパスがアーカイブに加えられる前に渡されます。 filterfunc が偽を返せば、そのパスはアーカイブに追加されず、ディレクトリだった場合はその中身が無視されます。例として、私たちのテストファイルが全て
testディレクトリの中にあるか、test文字列で始まるとしましょう。 filterfunc を使ってそれらを除外出来ます:>>> zf = PyZipFile('myprog.zip') >>> def notests(s): ... fn = os.path.basename(s) ... return (not (fn == 'test' or fn.startswith('test_'))) >>> zf.writepy('myprog', filterfunc=notests)
writepy()メソッドは以下のようなファイル名でアーカイブを作成します:string.pyc # Top level name test/__init__.pyc # Package directory test/testall.pyc # Module test.testall test/bogus/__init__.pyc # Subpackage directory test/bogus/myfile.pyc # Submodule test.bogus.myfile
バージョン 3.4 で追加: filterfunc パラメータ。
-
13.5.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¶ 圧縮前のファイルのサイズ。
13.5.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