Doc/library/zipfile.rst

   1
   2 :mod:`zipfile` --- Work with ZIP archives
   3 =========================================
   4
   5 .. module:: zipfile
   6    :synopsis: Read and write ZIP-format archive files.
   7 .. moduleauthor:: James C. Ahlstrom <jim@interet.com>
   8 .. sectionauthor:: James C. Ahlstrom <jim@interet.com>
   9
  10 .. versionadded:: 1.6
  11
  12 The ZIP file format is a common archive and compression standard. This module
  13 provides tools to create, read, write, append, and list a ZIP file.  Any
  14 advanced use of this module will require an understanding of the format, as
  15 defined in `PKZIP Application Note
  16 <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_.
  17
  18 This module does not currently handle multi-disk ZIP files, or ZIP files
  19 which have appended comments (although it correctly handles comments
  20 added to individual archive members---for which see the :ref:`zipinfo-objects`
  21 documentation). It can handle ZIP files that use the ZIP64 extensions
  22 (that is ZIP files that are more than 4 GByte in size).  It supports
  23 decryption of encrypted files in ZIP archives, but it currently cannot
  24 create an encrypted file.  Decryption is extremely slow as it is
  25 implemented in native python rather than C.
  26
  27 For other archive formats, see the :mod:`bz2`, :mod:`gzip`, and
  28 :mod:`tarfile` modules.
  29
  30 The module defines the following items:
  31
  32 .. exception:: BadZipfile
  33
  34    The error raised for bad ZIP files (old name: ``zipfile.error``).
  35
  36
  37 .. exception:: LargeZipFile
  38
  39    The error raised when a ZIP file would require ZIP64 functionality but that has
  40    not been enabled.
  41
  42
  43 .. class:: ZipFile
  44
  45    The class for reading and writing ZIP files.  See section
  46    :ref:`zipfile-objects` for constructor details.
  47
  48
  49 .. class:: PyZipFile
  50
  51    Class for creating ZIP archives containing Python libraries.
  52
  53
  54 .. class:: ZipInfo([filename[, date_time]])
  55
  56    Class used to represent information about a member of an archive. Instances
  57    of this class are returned by the :meth:`getinfo` and :meth:`infolist`
  58    methods of :class:`ZipFile` objects.  Most users of the :mod:`zipfile` module
  59    will not need to create these, but only use those created by this
  60    module. *filename* should be the full name of the archive member, and
  61    *date_time* should be a tuple containing six fields which describe the time
  62    of the last modification to the file; the fields are described in section
  63    :ref:`zipinfo-objects`.
  64
  65
  66 .. function:: is_zipfile(filename)
  67
  68    Returns ``True`` if *filename* is a valid ZIP file based on its magic number,
  69    otherwise returns ``False``.  *filename* may be a file or file-like object too.
  70    This module does not currently handle ZIP files which have appended comments.
  71
  72    .. versionchanged:: 2.7
  73       Support for file and file-like objects.
  74
  75 .. data:: ZIP_STORED
  76
  77    The numeric constant for an uncompressed archive member.
  78
  79
  80 .. data:: ZIP_DEFLATED
  81
  82    The numeric constant for the usual ZIP compression method.  This requires the
  83    zlib module.  No other compression methods are currently supported.
  84
  85
  86 .. seealso::
  87
  88    `PKZIP Application Note <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_
  89       Documentation on the ZIP file format by Phil Katz, the creator of the format and
  90       algorithms used.
  91
  92    `Info-ZIP Home Page <http://www.info-zip.org/>`_
  93       Information about the Info-ZIP project's ZIP archive programs and development
  94       libraries.
  95
  96
  97 .. _zipfile-objects:
  98
  99 ZipFile Objects
 100 ---------------
 101
 102
 103 .. class:: ZipFile(file[, mode[, compression[, allowZip64]]])
 104
 105    Open a ZIP file, where *file* can be either a path to a file (a string) or a
 106    file-like object.  The *mode* parameter should be ``'r'`` to read an existing
 107    file, ``'w'`` to truncate and write a new file, or ``'a'`` to append to an
 108    existing file.  If *mode* is ``'a'`` and *file* refers to an existing ZIP file,
 109    then additional files are added to it.  If *file* does not refer to a ZIP file,
 110    then a new ZIP archive is appended to the file.  This is meant for adding a ZIP
 111    archive to another file, such as :file:`python.exe`.  Using ::
 112
 113       cat myzip.zip >> python.exe
 114
 115    also works, and at least :program:`WinZip` can read such files. If *mode* is
 116    ``a`` and the file does not exist at all, it is created. *compression* is the
 117    ZIP compression method to use when writing the archive, and should be
 118    :const:`ZIP_STORED` or :const:`ZIP_DEFLATED`; unrecognized values will cause
 119    :exc:`RuntimeError` to be raised.  If :const:`ZIP_DEFLATED` is specified but the
 120    :mod:`zlib` module is not available, :exc:`RuntimeError` is also raised.  The
 121    default is :const:`ZIP_STORED`.  If *allowZip64* is ``True`` zipfile will create
 122    ZIP files that use the ZIP64 extensions when the zipfile is larger than 2 GB. If
 123    it is  false (the default) :mod:`zipfile` will raise an exception when the ZIP
 124    file would require ZIP64 extensions. ZIP64 extensions are disabled by default
 125    because the default :program:`zip` and :program:`unzip` commands on Unix (the
 126    InfoZIP utilities) don't support these extensions.
 127
 128    .. versionchanged:: 2.6
 129       If the file does not exist, it is created if the mode is 'a'.
 130
 131
 132 .. method:: ZipFile.close()
 133
 134    Close the archive file.  You must call :meth:`close` before exiting your program
 135    or essential records will not be written.
 136
 137
 138 .. method:: ZipFile.getinfo(name)
 139
 140    Return a :class:`ZipInfo` object with information about the archive member
 141    *name*.  Calling :meth:`getinfo` for a name not currently contained in the
 142    archive will raise a :exc:`KeyError`.
 143
 144
 145 .. method:: ZipFile.infolist()
 146
 147    Return a list containing a :class:`ZipInfo` object for each member of the
 148    archive.  The objects are in the same order as their entries in the actual ZIP
 149    file on disk if an existing archive was opened.
 150
 151
 152 .. method:: ZipFile.namelist()
 153
 154    Return a list of archive members by name.
 155
 156
 157 .. method:: ZipFile.open(name[, mode[, pwd]])
 158
 159    Extract a member from the archive as a file-like object (ZipExtFile). *name* is
 160    the name of the file in the archive, or a :class:`ZipInfo` object. The *mode*
 161    parameter, if included, must be one of the following: ``'r'`` (the  default),
 162    ``'U'``, or ``'rU'``. Choosing ``'U'`` or  ``'rU'`` will enable universal newline
 163    support in the read-only object. *pwd* is the password used for encrypted files.
 164    Calling  :meth:`open` on a closed ZipFile will raise a  :exc:`RuntimeError`.
 165
 166    .. note::
 167
 168       The file-like object is read-only and provides the following methods:
 169       :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`__iter__`,
 170       :meth:`next`.
 171
 172    .. note::
 173
 174       If the ZipFile was created by passing in a file-like object as the  first
 175       argument to the constructor, then the object returned by :meth:`.open` shares the
 176       ZipFile's file pointer.  Under these  circumstances, the object returned by
 177       :meth:`.open` should not  be used after any additional operations are performed
 178       on the  ZipFile object.  If the ZipFile was created by passing in a string (the
 179       filename) as the first argument to the constructor, then  :meth:`.open` will
 180       create a new file object that will be held by the ZipExtFile, allowing it to
 181       operate independently of the  ZipFile.
 182
 183    .. note::
 184
 185       The :meth:`open`, :meth:`read` and :meth:`extract` methods can take a filename
 186       or a :class:`ZipInfo` object.  You will appreciate this when trying to read a
 187       ZIP file that contains members with duplicate names.
 188
 189    .. versionadded:: 2.6
 190
 191
 192 .. method:: ZipFile.extract(member[, path[, pwd]])
 193
 194    Extract a member from the archive to the current working directory; *member*
 195    must be its full name or a :class:`ZipInfo` object).  Its file information is
 196    extracted as accurately as possible.  *path* specifies a different directory
 197    to extract to.  *member* can be a filename or a :class:`ZipInfo` object.
 198    *pwd* is the password used for encrypted files.
 199
 200    .. versionadded:: 2.6
 201
 202
 203 .. method:: ZipFile.extractall([path[, members[, pwd]]])
 204
 205    Extract all members from the archive to the current working directory.  *path*
 206    specifies a different directory to extract to.  *members* is optional and must
 207    be a subset of the list returned by :meth:`namelist`.  *pwd* is the password
 208    used for encrypted files.
 209
 210    .. versionadded:: 2.6
 211
 212
 213 .. method:: ZipFile.printdir()
 214
 215    Print a table of contents for the archive to ``sys.stdout``.
 216
 217
 218 .. method:: ZipFile.setpassword(pwd)
 219
 220    Set *pwd* as default password to extract encrypted files.
 221
 222    .. versionadded:: 2.6
 223
 224
 225 .. method:: ZipFile.read(name[, pwd])
 226
 227    Return the bytes of the file *name* in the archive.  *name* is the name of the
 228    file in the archive, or a :class:`ZipInfo` object.  The archive must be open for
 229    read or append. *pwd* is the password used for encrypted  files and, if specified,
 230    it will override the default password set with :meth:`setpassword`.  Calling
 231    :meth:`read` on a closed ZipFile  will raise a :exc:`RuntimeError`.
 232
 233    .. versionchanged:: 2.6
 234       *pwd* was added, and *name* can now be a :class:`ZipInfo` object.
 235
 236
 237 .. method:: ZipFile.testzip()
 238
 239    Read all the files in the archive and check their CRC's and file headers.
 240    Return the name of the first bad file, or else return ``None``. Calling
 241    :meth:`testzip` on a closed ZipFile will raise a :exc:`RuntimeError`.
 242
 243
 244 .. method:: ZipFile.write(filename[, arcname[, compress_type]])
 245
 246    Write the file named *filename* to the archive, giving it the archive name
 247    *arcname* (by default, this will be the same as *filename*, but without a drive
 248    letter and with leading path separators removed).  If given, *compress_type*
 249    overrides the value given for the *compression* parameter to the constructor for
 250    the new entry.  The archive must be open with mode ``'w'`` or ``'a'`` -- calling
 251    :meth:`write` on a ZipFile created with mode ``'r'`` will raise a
 252    :exc:`RuntimeError`.  Calling  :meth:`write` on a closed ZipFile will raise a
 253    :exc:`RuntimeError`.
 254
 255    .. note::
 256
 257       There is no official file name encoding for ZIP files. If you have unicode file
 258       names, you must convert them to byte strings in your desired encoding before
 259       passing them to :meth:`write`. WinZip interprets all file names as encoded in
 260       CP437, also known as DOS Latin.
 261
 262    .. note::
 263
 264       Archive names should be relative to the archive root, that is, they should not
 265       start with a path separator.
 266
 267    .. note::
 268
 269       If ``arcname`` (or ``filename``, if ``arcname`` is  not given) contains a null
 270       byte, the name of the file in the archive will be truncated at the null byte.
 271
 272
 273 .. method:: ZipFile.writestr(zinfo_or_arcname, bytes)
 274
 275    Write the string *bytes* to the archive; *zinfo_or_arcname* is either the file
 276    name it will be given in the archive, or a :class:`ZipInfo` instance.  If it's
 277    an instance, at least the filename, date, and time must be given.  If it's a
 278    name, the date and time is set to the current date and time. The archive must be
 279    opened with mode ``'w'`` or ``'a'`` -- calling  :meth:`writestr` on a ZipFile
 280    created with mode ``'r'``  will raise a :exc:`RuntimeError`.  Calling
 281    :meth:`writestr` on a closed ZipFile will raise a :exc:`RuntimeError`.
 282
 283    .. note::
 284
 285       When passing a :class:`ZipInfo` instance as the *zinfo_or_acrname* parameter,
 286       the compression method used will be that specified in the *compress_type*
 287       member of the given :class:`ZipInfo` instance.  By default, the
 288       :class:`ZipInfo` constructor sets this member to :const:`ZIP_STORED`.
 289
 290 The following data attributes are also available:
 291
 292
 293 .. attribute:: ZipFile.debug
 294
 295    The level of debug output to use.  This may be set from ``0`` (the default, no
 296    output) to ``3`` (the most output).  Debugging information is written to
 297    ``sys.stdout``.
 298
 299 .. attribute:: ZipFile.comment
 300
 301    The comment text associated with the ZIP file.  If assigning a comment to a
 302    :class:`ZipFile` instance created with mode 'a' or 'w', this should be a
 303    string no longer than 65535 bytes.  Comments longer than this will be
 304    truncated in the written archive when :meth:`ZipFile.close` is called.
 305
 306 .. _pyzipfile-objects:
 307
 308 PyZipFile Objects
 309 -----------------
 310
 311 The :class:`PyZipFile` constructor takes the same parameters as the
 312 :class:`ZipFile` constructor.  Instances have one method in addition to those of
 313 :class:`ZipFile` objects.
 314
 315
 316 .. method:: PyZipFile.writepy(pathname[, basename])
 317
 318    Search for files :file:`\*.py` and add the corresponding file to the archive.
 319    The corresponding file is a :file:`\*.pyo` file if available, else a
 320    :file:`\*.pyc` file, compiling if necessary.  If the pathname is a file, the
 321    filename must end with :file:`.py`, and just the (corresponding
 322    :file:`\*.py[co]`) file is added at the top level (no path information).  If the
 323    pathname is a file that does not end with :file:`.py`, a :exc:`RuntimeError`
 324    will be raised.  If it is a directory, and the directory is not a package
 325    directory, then all the files :file:`\*.py[co]` are added at the top level.  If
 326    the directory is a package directory, then all :file:`\*.py[co]` are added under
 327    the package name as a file path, and if any subdirectories are package
 328    directories, all of these are added recursively.  *basename* is intended for
 329    internal use only.  The :meth:`writepy` method makes archives with file names
 330    like this::
 331
 332       string.pyc                                # Top level name
 333       test/__init__.pyc                         # Package directory
 334       test/test_support.pyc                          # Module test.test_support
 335       test/bogus/__init__.pyc                   # Subpackage directory
 336       test/bogus/myfile.pyc                     # Submodule test.bogus.myfile
 337
 338
 339 .. _zipinfo-objects:
 340
 341 ZipInfo Objects
 342 ---------------
 343
 344 Instances of the :class:`ZipInfo` class are returned by the :meth:`getinfo` and
 345 :meth:`infolist` methods of :class:`ZipFile` objects.  Each object stores
 346 information about a single member of the ZIP archive.
 347
 348 Instances have the following attributes:
 349
 350
 351 .. attribute:: ZipInfo.filename
 352
 353    Name of the file in the archive.
 354
 355
 356 .. attribute:: ZipInfo.date_time
 357
 358    The time and date of the last modification to the archive member.  This is a
 359    tuple of six values:
 360
 361    +-------+--------------------------+
 362    | Index | Value                    |
 363    +=======+==========================+
 364    | ``0`` | Year                     |
 365    +-------+--------------------------+
 366    | ``1`` | Month (one-based)        |
 367    +-------+--------------------------+
 368    | ``2`` | Day of month (one-based) |
 369    +-------+--------------------------+
 370    | ``3`` | Hours (zero-based)       |
 371    +-------+--------------------------+
 372    | ``4`` | Minutes (zero-based)     |
 373    +-------+--------------------------+
 374    | ``5`` | Seconds (zero-based)     |
 375    +-------+--------------------------+
 376
 377
 378 .. attribute:: ZipInfo.compress_type
 379
 380    Type of compression for the archive member.
 381
 382
 383 .. attribute:: ZipInfo.comment
 384
 385    Comment for the individual archive member.
 386
 387
 388 .. attribute:: ZipInfo.extra
 389
 390    Expansion field data.  The `PKZIP Application Note
 391    <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_ contains
 392    some comments on the internal structure of the data contained in this string.
 393
 394
 395 .. attribute:: ZipInfo.create_system
 396
 397    System which created ZIP archive.
 398
 399
 400 .. attribute:: ZipInfo.create_version
 401
 402    PKZIP version which created ZIP archive.
 403
 404
 405 .. attribute:: ZipInfo.extract_version
 406
 407    PKZIP version needed to extract archive.
 408
 409
 410 .. attribute:: ZipInfo.reserved
 411
 412    Must be zero.
 413
 414
 415 .. attribute:: ZipInfo.flag_bits
 416
 417    ZIP flag bits.
 418
 419
 420 .. attribute:: ZipInfo.volume
 421
 422    Volume number of file header.
 423
 424
 425 .. attribute:: ZipInfo.internal_attr
 426
 427    Internal attributes.
 428
 429
 430 .. attribute:: ZipInfo.external_attr
 431
 432    External file attributes.
 433
 434
 435 .. attribute:: ZipInfo.header_offset
 436
 437    Byte offset to the file header.
 438
 439
 440 .. attribute:: ZipInfo.CRC
 441
 442    CRC-32 of the uncompressed file.
 443
 444
 445 .. attribute:: ZipInfo.compress_size
 446
 447    Size of the compressed data.
 448
 449
 450 .. attribute:: ZipInfo.file_size
 451
 452    Size of the uncompressed file.
 453