zipfile --- ZIP アーカイブの処理

Source code: Lib/zipfile/

---

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

このモジュールは分割された ZIP ファイルを扱えません。 ZIP64 拡張を使う ZIP ファイル (サイズが 4 GiB を超える ZIP ファイル) は扱えます。 ZIP アーカイブ内の暗号化されたファイルの復号をサポートしていますが、暗号化されたファイルの作成はできません。 復号処理は C ではなく Python で実装されているため、非常に低速です。

圧縮されたアーカイブを扱うには、zlib、bz2、lzma、compression.zstd などの オプションモジュール が必要です。 使用している CPython にこれらが含まれていない場合は、配布元 (Python を提供した組織など) のドキュメントを確認してください。 配布する立場の場合は オプションのモジュールの要件 を参照してください。

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

exception zipfile.BadZipFile

正常ではない ZIP ファイルに対して送出されるエラーです。

Added in version 3.2.

exception zipfile.BadZipfile

BadZipFile の別名です。過去のバージョンの Python との互換性のために用意されています。

バージョン 3.2 で非推奨.

exception zipfile.LargeZipFile

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

class zipfile.ZipFile

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

class zipfile.Path

pathlib.Path インターフェースの一部を実装したクラスです。 importlib.resources.abc.Traversable インターフェースは完全に実装しています。

Added in version 3.8.

class zipfile.PyZipFile

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

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))

アーカイブ内のメンバーの情報を表すクラスです。 このクラスのインスタンスは ZipFile オブジェクトの getinfo() メソッドと infolist() メソッドが返します。 zipfile モジュールの利用者のほとんどは、自分でインスタンスを作る必要はなく、モジュールが作成したものを使うだけで十分です。 filename はアーカイブ内のメンバーの完全な名前、date_time はファイルの最終更新日時を表す 6 フィールドのタプルでなければなりません。 各フィールドについては ZipInfo オブジェクト を参照してください。

バージョン 3.13 で変更: これまで保護された属性だった _compresslevel を公開する compress_level 属性を追加しました。 後方互換性のため、以前の保護された名前もプロパティとして引き続き使えます。

_for_archive(archive)

ZipFile.writestr() で使う適切なデフォルト値を date_time、圧縮関連の属性、外部属性に設定します。

呼び出しを連結できるように、自身を返します。

Added in version 3.14.

zipfile.is_zipfile(filename)

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

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

zipfile.ZIP_STORED

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

zipfile.ZIP_DEFLATED

通常の ZIP 圧縮方法を表す数値定数です。これには zlib モジュールが必要です。

zipfile.ZIP_BZIP2

BZIP2 圧縮方法を表す数値定数です。これには bz2 モジュールが必要です。

Added in version 3.3.

zipfile.ZIP_LZMA

LZMA 圧縮方法を表す数値定数です。これには lzma モジュールが必要です。

Added in version 3.3.

zipfile.ZIP_ZSTANDARD

Zstandard 圧縮を表す数値定数です。 compression.zstd モジュールが必要です。

注釈

APPNOTE 6.3.7 では、Zstandard 圧縮に方式 ID 20 が割り当てられました。 競合を避けるため、APPNOTE 6.3.8 で方式 ID は 93 に変更され、20 は非推奨になりました。 互換性のため、zipfile モジュールはどちらの方式 ID も読み込めますが、書き込みには方式 ID 93 だけを使います。

Added in version 3.14.

注釈

ZIP ファイル形式の仕様は 2001 年から bzip2 圧縮、2006 年から LZMA 圧縮、2020 年から Zstandard 圧縮をサポートしています。 ただし、古い Python のリリースを含む一部のツールはこれらの圧縮方式をサポートしておらず、ZIP ファイル全体の処理を拒否したり、個々のファイルを展開できなかったりする場合があります。

参考

PKZIP Application Note

ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz によるドキュメント。

Info-ZIP Home Page

Info-ZIP プロジェクトによる ZIP アーカイブプログラムおよびプログラム開発ライブラリに関する情報。

ZipFile オブジェクト

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)

ZIP ファイルを開きます。 file はファイルのパス (文字列) か、ファイルライクオブジェクト、 path-like object のいずれかです。

mode 引数には、既存のファイルを読み込む場合は 'r'、内容を消去して新しいファイルとして書き込む場合は 'w'、既存のファイルの末尾に追加する場合は 'a'、ファイルが存在しない場合にのみファイルを作成して書き込む場合は 'x' を指定します。 mode が 'x' で file が既存のファイルを指している場合、FileExistsError が送出されます。 mode が 'a' で file が既存の ZIP ファイルを指している場合、その ZIP ファイルにファイルが追加されます。 file が ZIP ファイルでない場合は、ファイルの末尾に新しい ZIP アーカイブが追加されます。 これは、既存のファイル (例えば python.exe) に ZIP アーカイブを付け加える用途を想定したものです。 mode が 'a' で file が存在しない場合は、ファイルが作成されます。 mode が 'r' か 'a' の場合、ファイルはシーク可能である必要があります。

compression はアーカイブの書き込みに使う ZIP 圧縮方式で、ZIP_STORED、ZIP_DEFLATED、ZIP_BZIP2、ZIP_LZMA、ZIP_ZSTANDARD のいずれかを指定します。 認識できない値を指定すると NotImplementedError が送出されます。 ZIP_DEFLATED、ZIP_BZIP2、ZIP_LZMA、ZIP_ZSTANDARD を指定したとき、対応するモジュール (zlib、bz2、lzma、compression.zstd) が利用できなければ RuntimeError が送出されます。 デフォルトは ZIP_STORED です。

allowZip64 が True (デフォルト) の場合、zipfile はサイズが 4 GiB を超えると ZIP64 拡張を使う ZIP ファイルを作成します。 false の場合、ZIP ファイルに ZIP64 拡張が必要になると zipfile は例外を送出します。

compresslevel 引数は、アーカイブにファイルを書き込む際の圧縮レベルを指定します。 ZIP_STORED または ZIP_LZMA を使う場合は効果がありません。 ZIP_DEFLATED では 0 から 9 までの整数を指定できます (詳細は zlib を参照)。 ZIP_BZIP2 では 1 から 9 までの整数を指定できます (詳細は bz2 を参照)。 ZIP_ZSTANDARD では通常 -131072 から 22 までの整数を指定できます (有効な値の取得方法と意味については CompressionParameter.compression_level を参照)。

strict_timestamps 引数を False にすると、1980-01-01 より前のファイルを ZIP に格納できますが、タイムスタンプは 1980-01-01 に設定されます。 2107-12-31 より後のファイルも同様に扱われ、タイムスタンプは上限の日時に設定されます。

mode が 'r' の場合、metadata_encoding にコーデックの名前を設定し、メンバーの名前や ZIP コメントなどのメタデータのデコードに使うことができます。

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

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

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

注釈

metadata_encoding は ZipFile インスタンス全体に適用される設定です。 メンバーごとに設定することはできません。

この属性は、現在のロケールのエンコーディングやコードページを名前に使ってアーカイブを作成する古い実装 (主に Windows) に対処するためのものです。 .ZIP 標準では、アーカイブヘッダーのフラグによってメタデータのエンコーディングを IBM コードページ (デフォルト) または UTF-8 に指定できます。 このフラグは、Python 独自の拡張である metadata_encoding よりも優先されます。

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

バージョン 3.3 で変更: bzip2 および lzma 圧縮をサポートしました。

バージョン 3.4 で変更: ZIP64 拡張がデフォルトで有効になりました。

バージョン 3.5 で変更: シークできないストリームへの書き込みをサポートしました。 'x' モードをサポートしました。

バージョン 3.6 で変更: 以前は、認識できない圧縮方式の値に対して単なる RuntimeError が送出されていました。

バージョン 3.6.2 で変更: file 引数が path-like object を受け入れるようになりました。

バージョン 3.7 で変更: compresslevel パラメータが追加されました。

バージョン 3.8 で変更: キーワード専用引数 strict_timestamps を追加しました。

バージョン 3.11 で変更: zip ファイルのディレクトリとファイルヘッダーのメタデータを読み込む際、メンバー名のエンコーディングを指定できるようになりました。

ZipFile.close()

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

ZipFile.getinfo(name)

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

ZipFile.infolist()

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

ZipFile.namelist()

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

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)

アーカイブ内のメンバーに、バイナリのファイル風オブジェクトとしてアクセスします。 name にはアーカイブ内のファイル名または ZipInfo オブジェクトを指定できます。 mode 引数を指定する場合は 'r' (デフォルト) または 'w' でなければなりません。 pwd は暗号化された ZIP ファイルの復号に使うパスワードを表す bytes オブジェクトです。

open() はコンテキストマネージャでもあるので with 文をサポートしています:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

mode が 'r' の場合、ファイル風オブジェクト (ZipExtFile) は読み取り専用で、read()、readline()、readlines()、seek()、tell()、__iter__()、__next__() メソッドを提供します。 これらのオブジェクトは ZipFile とは独立して動作できます。

mode='w' の場合、write() メソッドをサポートする書き込み可能なファイルハンドルを返します。 書き込み可能なファイルハンドルが開いている間に、ZIP ファイル内のほかのファイルの読み書きを試みると ValueError が送出されます。

いずれの場合も、ファイル風オブジェクトにはアーカイブ内のファイル名に等しい name 属性と、指定したモードに応じて 'rb' または 'wb' になる mode 属性があります。

書き込むファイルのサイズが事前に分からず、2 GiB を超える可能性がある場合は、force_zip64=True を渡して大きなファイルに対応するヘッダー形式が使われるようにしてください。 サイズが事前に分かる場合は、file_size を設定した ZipInfo オブジェクトを作成し、name 引数に渡してください。

注釈

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

バージョン 3.6 で変更: mode='U' のサポートを削除しました。 圧縮されたテキストファイルを ユニバーサル改行 モードで読み込むには io.TextIOWrapper を使ってください。

バージョン 3.6 で変更: mode='w' オプションを指定して ZipFile.open() を呼び出し、アーカイブにファイルを書き込めるようになりました。

バージョン 3.6 で変更: 閉じた ZipFile の open() を呼び出すと ValueError が送出されるようになりました。 以前は RuntimeError が送出されていました。

バージョン 3.13 で変更: 書き込み可能なファイル風オブジェクトに name 属性と mode 属性を追加しました。 読み取り可能なファイル風オブジェクトの mode 属性の値を 'r' から 'rb' に変更しました。

ZipFile.extract(member, path=None, pwd=None)

アーカイブ内のメンバーを現在の作業ディレクトリに展開します。 member はメンバーの完全な名前または ZipInfo オブジェクトでなければなりません。 ファイル情報は可能な限り正確に復元されます。 path には別の展開先ディレクトリを指定します。 member にはファイル名または ZipInfo オブジェクトを指定できます。 pwd は暗号化されたファイルに使うパスワードを表す bytes オブジェクトです。

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

注釈

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

バージョン 3.6 で変更: 閉じた ZipFile の extract() を呼び出すと ValueError が送出されるようになりました。 以前は RuntimeError が送出されていました。

バージョン 3.6.2 で変更: path パラメタが path-like object を受け付けるようになりました。

ZipFile.extractall(path=None, members=None, pwd=None)

アーカイブ内のすべてのメンバーを現在の作業ディレクトリに展開します。 path には別の展開先ディレクトリを指定します。 members は省略可能で、指定する場合は namelist() が返すリストの部分集合でなければなりません。 pwd は暗号化されたファイルに使うパスワードを表す bytes オブジェクトです。

警告

信頼できないソースから取得したアーカイブは、事前に確認せずに展開しないでください。 例えば、絶対パスや ".." 要素を含むファイル名のメンバーがあると、path の外にファイルが作成される可能性があります。 このモジュールはそれを防ぐようにしています。 extract() の注記を参照してください。

バージョン 3.6 で変更: 閉じた ZipFile の extractall() を呼び出すと ValueError が送出されるようになりました。 以前は RuntimeError が送出されていました。

バージョン 3.6.2 で変更: path パラメタが path-like object を受け付けるようになりました。

ZipFile.printdir()

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

ZipFile.setpassword(pwd)

暗号化されたファイルを展開する際のデフォルトのパスワードとして、bytes オブジェクトの pwd を設定します。

ZipFile.read(name, pwd=None)

Return the bytes of the file name in the archive. name is the name of the file in the archive, or a ZipInfo object. The archive must be open for read or append. pwd is the password used for encrypted files as a bytes object and, if specified, overrides the default password set with setpassword(). Calling read() on a ZipFile that uses a compression method other than ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2, ZIP_LZMA, or ZIP_ZSTANDARD will raise a NotImplementedError. An error will also be raised if the corresponding compression module is not available.

バージョン 3.6 で変更: 閉じた ZipFile の read() を呼び出すと ValueError が送出されるようになりました。 以前は RuntimeError が送出されていました。

ZipFile.testzip()

アーカイブ内のすべてのファイルを読み込み、CRC とファイルヘッダーを検査します。 最初に見つかった不正なファイルの名前を返し、不正なファイルがなければ None を返します。

バージョン 3.6 で変更: 閉じた ZipFile の testzip() を呼び出すと ValueError が送出されるようになりました。 以前は RuntimeError が送出されていました。

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)

filename で指定したファイルを、アーカイブ内の名前を arcname として書き込みます。 デフォルトの名前は filename からドライブ文字と先頭のパス区切り文字を取り除いたものです。 compress_type を指定すると、新しいエントリーにはコンストラクタの compression 引数の値よりも優先して使われます。 同様に、compresslevel を指定するとコンストラクタの値よりも優先されます。 アーカイブは 'w'、'x'、'a' のいずれかのモードで開いていなければなりません。

注釈

ZIP ファイルの標準は、以前はメタデータのエンコーディングを規定していませんでしたが、相互運用性のために CP437 (初代 IBM PC のエンコーディング) を強く推奨していました。 最近のバージョンでは UTF-8 (のみ) も使えます。 このモジュールは、メンバー名に非 ASCII 文字が含まれる場合、自動的に UTF-8 で書き込みます。 ASCII または UTF-8 以外のエンコーディングでメンバー名を書き込むことはできません。

注釈

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

注釈

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

注釈

ファイル名の先頭にスラッシュがあると、Windows 上の一部の zip プログラムでアーカイブを開けなくなる場合があります。

バージョン 3.6 で変更: モード 'r' で作成した ZipFile、または閉じた ZipFile の write() を呼び出すと ValueError が送出されるようになりました。 以前は RuntimeError が送出されていました。

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)

Write a file into the archive. The contents is data, which may be either a str or a bytes instance; if it is a str, it is encoded as UTF-8 first. zinfo_or_arcname is either the file name it will be given in the archive, or a ZipInfo instance. If it's an instance, at least the filename, date, and time must be given. If it's a name, the date and time is set to the current date and time. The archive must be opened with mode 'w', 'x' or 'a'.

compress_type を指定すると、新しいエントリーにはコンストラクタの compression 引数の値、または ZipInfo インスタンスとして渡した zinfo_or_arcname の値よりも優先して使われます。 同様に、compresslevel を指定するとコンストラクタの値よりも優先されます。

注釈

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

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

バージョン 3.6 で変更: モード 'r' で作成した ZipFile、または閉じた ZipFile の writestr() を呼び出すと ValueError が送出されるようになりました。 以前は RuntimeError が送出されていました。

バージョン 3.14 で変更: SOURCE_DATE_EPOCH 環境変数を参照するようになりました。 設定されている場合、ZIP アーカイブに書き込むファイルの更新タイムスタンプには現在時刻ではなくこの値を使います。

ZipFile.mkdir(zinfo_or_directory, mode=511)

アーカイブ内にディレクトリを作成します。 zinfo_or_directory が文字列の場合、mode 引数で指定したモードでアーカイブ内にディレクトリを作成します。 zinfo_or_directory が ZipInfo インスタンスの場合は mode 引数を無視します。

アーカイブは 'w'、'x'、'a' のいずれかのモードで開いていなければなりません。

Added in version 3.11.

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

ZipFile.filename

ZIP ファイルの名前です。

ZipFile.debug

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

ZipFile.comment

ZIP ファイルに bytes オブジェクトとして関連付けられたコメントです。モード 'w' 、 'x' または 'a' で作成された ZipFile インスタンスへコメントを割り当てる場合、文字列長は 65535 バイトまでにしてください。その長さを超えたコメントは切り捨てられます。

Path オブジェクト

class zipfile.Path(root, at='')

zip ファイルを表す root から Path オブジェクトを作成します。 root には ZipFile インスタンス、または ZipFile コンストラクタの file 引数に渡せるものを指定できます。

at は zip ファイル内でのこの Path の位置を指定します。 例えば 'dir/file.txt'、'dir/'、'' などです。 デフォルトはルートを示す空文字列です。

注釈

Path クラスは ZIP アーカイブ内のファイル名を安全な形に変換しません。 ZipFile.extract() メソッドや ZipFile.extractall() メソッドと異なり、パストラバーサルの脆弱性を防ぐために、呼び出し側がファイル名の検証や安全な形への変換を行う必要があります (例えば絶対パスや ".." 要素を含むパスに注意してください)。 信頼できないアーカイブを扱う場合は、os.path.abspath() でファイル名を解決し、os.path.commonpath() で出力先ディレクトリと照合することを検討してください。

Path オブジェクトは pathlib.Path オブジェクトの以下の機能を提供します。

Path オブジェクトは / 演算子または joinpath でたどれます。

Path.name

パスの最後の要素。

Path.open(mode='r', *, pwd, **)

Invoke ZipFile.open() on the current path. Allows opening for read or write, text or binary through supported modes: 'r', 'w', 'rb', 'wb'. Positional and keyword arguments are passed through to io.TextIOWrapper when opened as text and ignored otherwise. pwd is the pwd parameter to ZipFile.open().

バージョン 3.9 で変更: open でテキストモードとバイナリモードをサポートしました。 デフォルトはテキストモードになりました。

バージョン 3.11.2 で変更: 3.9 と同様に、encoding 引数を位置引数で渡しても TypeError が発生しなくなりました。 修正前の 3.10 や 3.11 との互換性が必要なコードでは、encoding を含む io.TextIOWrapper の引数をすべてキーワード引数として渡してください。

Path.iterdir()

現在のディレクトリの子を列挙します。

Path.is_dir()

現在の対象がディレクトリを指していれば True を返します。

Path.is_file()

現在の対象がファイルを指していれば True を返します。

Path.is_symlink()

現在の対象がシンボリックリンクを指していれば True を返します。

Added in version 3.12.

バージョン 3.13 で変更: 以前は is_symlink は無条件に False を返していました。

Path.exists()

現在の対象が zip ファイル内のファイルまたはディレクトリを指していれば True を返します。

Path.suffix

パスの最後の要素にドットが含まれる場合、その最後のドットから後ろの部分です。 一般にファイル拡張子と呼ばれます。

Added in version 3.11: Path.suffix プロパティを追加しました。

Path.stem

パスの最後の要素から拡張子を取り除いたもの。

Added in version 3.11: Path.stem プロパティを追加しました。

Path.suffixes

パスのサフィックスのリストです。 サフィックスは一般にファイル拡張子と呼ばれます。

Added in version 3.11: Path.suffixes プロパティを追加しました。

Path.read_text(*, **)

現在のファイルを Unicode テキストとして読み込みます。 位置引数とキーワード引数は io.TextIOWrapper に渡されます (buffer は現在の対象から決まるため除きます)。

バージョン 3.11.2 で変更: 3.9 と同様に、encoding 引数を位置引数で渡しても TypeError が発生しなくなりました。 修正前の 3.10 や 3.11 との互換性が必要なコードでは、encoding を含む io.TextIOWrapper の引数をすべてキーワード引数として渡してください。

Path.read_bytes()

現在のファイルをバイト列として読み込みます。

Path.joinpath(*other)

各 other 引数を結合した新しい Path オブジェクトを返します。 次の記述は同じ意味です。

>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'

バージョン 3.10 で変更: 3.10 より前では joinpath はドキュメント化されておらず、引数を 1 つだけ受け付けていました。

zipp プロジェクトは、最新の Path オブジェクトの機能を古い Python にバックポートしています。 変更をいち早く利用するには、zipfile.Path の代わりに zipp.Path を使ってください。

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() 参照) とするファイルのみが、必要に応じてコンパイルされアーカイブに追加されます。

pathname がファイルの場合、ファイル名は .py で終わる必要があり、対応する *.pyc ファイルだけがパス情報なしで最上位に追加されます。 pathname が .py で終わらないファイルの場合は RuntimeError が送出されます。 ディレクトリであって、パッケージディレクトリではない場合は、すべての *.pyc ファイルが最上位に追加されます。 パッケージディレクトリの場合は、パッケージ名をパスとしてその下にすべての *.pyc ファイルが追加されます。 サブディレクトリもパッケージディレクトリであれば、ソート順で再帰的に追加されます。

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                   # 最上位の名前
test/__init__.pyc            # パッケージディレクトリ
test/testall.pyc             # モジュール test.testall
test/bogus/__init__.pyc      # サブパッケージディレクトリ
test/bogus/myfile.pyc        # サブモジュール test.bogus.myfile

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

バージョン 3.6.2 で変更: pathname 引数が path-like object を受け付けるようになりました。

バージョン 3.7 で変更: 再帰処理でディレクトリエントリーをソートするようになりました。

ZipInfo オブジェクト

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

ファイルシステム上のファイルから ZipInfo インスタンスを作成するクラスメソッドが 1 つあります。

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)

zip ファイルに追加する準備として、ファイルシステム上のファイルに対する ZipInfo インスタンスを作成します。

filename はファイルシステム上のファイルまたはディレクトリへのパスでなければなりません。

arcname を指定した場合は、アーカイブ内の名前として使われます。 指定しない場合は filename からドライブ文字と先頭のパス区切り文字を取り除いた名前が使われます。

strict_timestamps 引数を False にすると、1980-01-01 より前のファイルを ZIP に格納できますが、タイムスタンプは 1980-01-01 に設定されます。 2107-12-31 より後のファイルも同様に扱われ、タイムスタンプは上限の日時に設定されます。

Added in version 3.6.

バージョン 3.6.2 で変更: filename 引数が path-like object を受け入れるようになりました。

バージョン 3.8 で変更: キーワード専用引数 strict_timestamps を追加しました。

インスタンスは以下のメソッドと属性を持ちます:

ZipInfo.is_dir()

アーカイブのメンバーがディレクトリの場合に True を返します。

エントリーの名前で判定します。 ディレクトリの名前は常に / で終わる必要があります。

Added in version 3.6.

ZipInfo.filename

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

ZipInfo.date_time

アーカイブ内のメンバーの最終更新日時です。 ZIP ファイルの中央ディレクトリにある「最終更新時刻」と「最終更新日」のフィールドを表す、6 要素のタプルです。

タプルには次の値が含まれます。

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

注釈

ZIP 形式では、中央ディレクトリや NTFS/UNIX システム用の拡張フィールドなど、複数の場所にタイムスタンプのフィールドがあります。 この属性は中央ディレクトリのタイムスタンプを返します。 ZIP ファイルの中央ディレクトリのタイムスタンプ形式は、1980 年より前の日時をサポートしていません。 UNIX タイムスタンプなど、一部の拡張フィールドの形式ではそれ以前の日時も表せますが、この属性が返すのは中央ディレクトリのタイムスタンプだけです。

ほかの zip ツールの動作に合わせ、中央ディレクトリのタイムスタンプは UTC ではなくローカル時刻を表すものとして解釈されます。

ZipInfo.compress_type

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

ZipInfo.comment

個々のアーカイブメンバーのコメントを表す bytes オブジェクト。

ZipInfo.extra

拡張フィールドデータ。この bytes オブジェクトに含まれているデータの内部構成については、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

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

コマンドライン・インターフェース

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

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

-l <zipfile>

--list <zipfile>

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

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

--create <zipfile> <source1> ... <sourceN>

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

-e <zipfile> <output_dir>

--extract <zipfile> <output_dir>

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

-t <zipfile>

--test <zipfile>

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

--metadata-encoding <encoding>

-l、-e、-t で使うメンバー名のエンコーディングを指定します。

Added in version 3.11.

展開時の注意点

zipfile モジュールによる展開は、以下のような問題によって失敗する場合があります。

ファイル自体の問題

パスワード、CRC チェックサム、ZIP 形式の誤りや、サポートされていない圧縮方式または復号方式によって展開に失敗する場合があります。

ファイルシステムの制限

ファイルシステムごとの制限を超えると、展開に失敗する場合があります。 ディレクトリエントリーに使用できる文字、ファイル名やパス名の長さ、単一ファイルのサイズ、ファイル数などの制限があります。

リソースの制限

メモリやディスク容量が不足すると展開に失敗します。 例えば、zipfile ライブラリでも展開爆弾 (別名 ZIP bomb) によってディスク容量が使い果たされる可能性があります。

中断

Control-C を押す、展開を行うプロセスを終了させるなど、展開中に処理が中断されると、アーカイブの展開が不完全な状態になる場合があります。

展開時のデフォルトの動作

展開時のデフォルトの動作を知らないと、予想外の結果になることがあります。 例えば同じアーカイブを 2 回展開すると、確認せずにファイルを上書きします。