"zipfile" — ZIP アーカイブの処理
********************************

バージョン 1.6 で追加.

**ソースコード:** Lib/zipfile.py

======================================================================

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

This module does not currently handle multi-disk ZIP files. It can
handle ZIP files that use the ZIP64 extensions (that is ZIP files that
are more than 4 GByte in size).  It supports decryption of encrypted
files in ZIP archives, but it currently cannot create an encrypted
file.  Decryption is extremely slow as it is implemented in native
Python rather than C.

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

exception zipfile.BadZipfile

   The error raised for bad ZIP files (old name: "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

   The numeric constant for the usual ZIP compression method.  This
   requires the "zlib" module.  No other compression methods are
   currently supported.

参考:

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

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


ZipFile オブジェクト
====================

class zipfile.ZipFile(file[, mode[, compression[, allowZip64]]])

   Open a ZIP file, where *file* can be either a path to a file (a
   string) or a file-like object.  The *mode* parameter should be
   "'r'" to read an existing file, "'w'" to truncate and write a new
   file, or "'a'" to append to an existing file.  If *mode* is "'a'"
   and *file* refers to an existing ZIP file, then additional files
   are added to it.  If *file* does not refer to a ZIP file, then a
   new ZIP archive is appended to the file.  This is meant for adding
   a ZIP archive to another file (such as "python.exe").

   バージョン 2.6 で変更: If *mode* is "a" and the file does not exist
   at all, it is created.

   *compression* is the ZIP compression method to use when writing the
   archive, and should be "ZIP_STORED" or "ZIP_DEFLATED"; unrecognized
   values will cause "RuntimeError" to be raised.  If "ZIP_DEFLATED"
   is specified but the "zlib" module is not available, "RuntimeError"
   is also raised. The default is "ZIP_STORED".  If *allowZip64* is
   "True" zipfile will create ZIP files that use the ZIP64 extensions
   when the zipfile is larger than 2 GB. If it is  false (the default)
   "zipfile" will raise an exception when the ZIP file would require
   ZIP64 extensions. ZIP64 extensions are disabled by default because
   the default **zip** and **unzip** commands on Unix (the InfoZIP
   utilities) don’t support these extensions.

   バージョン 2.7.1 で変更: If the file is created with mode "'a'" or
   "'w'" and then "closed" without adding any files to the archive,
   the appropriate ZIP structures for an empty archive will be written
   to the file.

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

   Extract a member from the archive as a file-like object
   (ZipExtFile). *name* is the name of the file in the archive, or a
   "ZipInfo" object. The *mode* parameter, if included, must be one of
   the following: "'r'" (the default), "'U'", or "'rU'". Choosing
   "'U'" or  "'rU'" will enable *universal newline* support in the
   read-only object. *pwd* is the password used for encrypted files.
   Calling  "open()" on a closed ZipFile will raise a  "RuntimeError".

   注釈: The file-like object is read-only and provides the
     following methods: "read()", "readline()", "readlines()",
     "__iter__()", "next()".

   注釈: If the ZipFile was created by passing in a file-like object
     as the  first argument to the constructor, then the object
     returned by "open()" shares the ZipFile’s file pointer.  Under
     these circumstances, the object returned by "open()" should not
     be used after any additional operations are performed on the
     ZipFile object.  If the ZipFile was created by passing in a
     string (the filename) as the first argument to the constructor,
     then  "open()" will create a new file object that will be held by
     the ZipExtFile, allowing it to operate independently of the
     ZipFile.

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

   バージョン 2.6 で追加.

ZipFile.extract(member[, path[, pwd]])

   Extract a member from the archive to the current working directory;
   *member* must be its full name or a "ZipInfo" object).  Its file
   information is extracted as accurately as possible.  *path*
   specifies a different directory to extract to.  *member* can be a
   filename or a "ZipInfo" object. *pwd* is the password used for
   encrypted files.

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

   バージョン 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* は、暗号化ファイルに使われるパスワードです。

   警告: Never extract archives from untrusted sources without prior
     inspection. It is possible that files are created outside of
     *path*, e.g. members that have absolute filenames starting with
     ""/"" or filenames with two dots "".."".

   バージョン 2.7.4 で変更: The zipfile module attempts to prevent
   that.  See "extract()" note.

   バージョン 2.6 で追加.

ZipFile.printdir()

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

ZipFile.setpassword(pwd)

   *pwd* を展開する圧縮ファイルのデフォルトパスワードとして指定します
   。

   バージョン 2.6 で追加.

ZipFile.read(name[, pwd])

   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 and, if specified, it will override the
   default password set with "setpassword()".  Calling "read()" on a
   closed ZipFile  will raise a "RuntimeError".

   バージョン 2.6 で変更: *pwd* was added, and *name* can now be a
   "ZipInfo" object.

ZipFile.testzip()

   Read all the files in the archive and check their CRC’s and file
   headers. Return the name of the first bad file, or else return
   "None". Calling "testzip()" on a closed ZipFile will raise a
   "RuntimeError".

ZipFile.write(filename[, arcname[, compress_type]])

   Write the file named *filename* to the archive, giving it the
   archive name *arcname* (by default, this will be the same as
   *filename*, but without a drive letter and with leading path
   separators removed).  If given, *compress_type* overrides the value
   given for the *compression* parameter to the constructor for the
   new entry.  The archive must be open with mode "'w'" or "'a'" –
   calling "write()" on a ZipFile created with mode "'r'" will raise a
   "RuntimeError".  Calling  "write()" on a closed ZipFile will raise
   a "RuntimeError".

   注釈: ZIP ファイル中のファイル名に関する公式なエンコーディングは
     ありま せん。Unicode のファイル名が付けられている場合は、それを
     "write()" に渡す前に望ましいエンコーディングでバイト列に変換しな
     ければなりません。WinZip はすべてのファイル名を DOS Latin として
     も知られる CP437 で解釈します。

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

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

ZipFile.writestr(zinfo_or_arcname, bytes[, compress_type])

   Write the string *bytes* to the archive; *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'" or "'a'" – calling  "writestr()" on a ZipFile created
   with mode "'r'"  will raise a "RuntimeError".  Calling "writestr()"
   on a closed ZipFile will raise a "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

   The comment text associated with the ZIP file.  If assigning a
   comment to a "ZipFile" instance created with mode 『a』 or 『w』,
   this should be a string no longer than 65535 bytes.  Comments
   longer than this will be truncated in the written archive when
   "close()" is called.


PyZipFile オブジェクト
======================

The "PyZipFile" constructor takes the same parameters as the "ZipFile"
constructor.  Instances have one method in addition to those of
"ZipFile" objects.

PyZipFile.writepy(pathname[, basename])

   Search for files "*.py" and add the corresponding file to the
   archive. The corresponding file is a "*.pyo" file if available,
   else a "*.pyc" file, compiling if necessary.  If the pathname is a
   file, the filename must end with ".py", and just the (corresponding
   "*.py[co]") file is added at the top level (no path information).
   If the pathname is a file that does not end with ".py", a
   "RuntimeError" will be raised.  If it is a directory, and the
   directory is not a package directory, then all the files "*.py[co]"
   are added at the top level.  If the directory is a package
   directory, then all "*.py[co]" are added under the package name as
   a file path, and if any subdirectories are package directories, all
   of these are added recursively.  *basename* is intended for
   internal use only.  The "writepy()" method makes archives with file
   names like this:

      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


ZipInfo オブジェクト
====================

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

Instances have the following attributes:

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

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


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

"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>

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

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

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

-e <zipfile> <output_dir>

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

-t <zipfile>

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