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"
   です。 *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" に出力されます。

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 が有効かどうか調べます。
