"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 回展開すると、確認せずにファイルを上書きし
ます。
