2 :mod:`zipfile` --- Work with ZIP archives
3 =========================================
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>
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>`_.
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.
27 For other archive formats, see the :mod:`bz2`, :mod:`gzip`, and
28 :mod:`tarfile` modules.
30 The module defines the following items:
32 .. exception:: BadZipfile
34 The error raised for bad ZIP files (old name: ``zipfile.error``).
37 .. exception:: LargeZipFile
39 The error raised when a ZIP file would require ZIP64 functionality but that has
45 The class for reading and writing ZIP files. See section
46 :ref:`zipfile-objects` for constructor details.
51 Class for creating ZIP archives containing Python libraries.
54 .. class:: ZipInfo([filename[, date_time]])
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`.
66 .. function:: is_zipfile(filename)
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.
72 .. versionchanged:: 2.7
73 Support for file and file-like objects.
77 The numeric constant for an uncompressed archive member.
80 .. data:: ZIP_DEFLATED
82 The numeric constant for the usual ZIP compression method. This requires the
83 zlib module. No other compression methods are currently supported.
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
92 `Info-ZIP Home Page <http://www.info-zip.org/>`_
93 Information about the Info-ZIP project's ZIP archive programs and development
103 .. class:: ZipFile(file[, mode[, compression[, allowZip64]]])
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 ::
113 cat myzip.zip >> python.exe
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.
128 .. versionchanged:: 2.6
129 If the file does not exist, it is created if the mode is 'a'.
132 .. method:: ZipFile.close()
134 Close the archive file. You must call :meth:`close` before exiting your program
135 or essential records will not be written.
138 .. method:: ZipFile.getinfo(name)
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`.
145 .. method:: ZipFile.infolist()
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.
152 .. method:: ZipFile.namelist()
154 Return a list of archive members by name.
157 .. method:: ZipFile.open(name[, mode[, pwd]])
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`.
168 The file-like object is read-only and provides the following methods:
169 :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`__iter__`,
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.
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.
189 .. versionadded:: 2.6
192 .. method:: ZipFile.extract(member[, path[, pwd]])
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.
200 .. versionadded:: 2.6
203 .. method:: ZipFile.extractall([path[, members[, pwd]]])
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.
210 .. versionadded:: 2.6
213 .. method:: ZipFile.printdir()
215 Print a table of contents for the archive to ``sys.stdout``.
218 .. method:: ZipFile.setpassword(pwd)
220 Set *pwd* as default password to extract encrypted files.
222 .. versionadded:: 2.6
225 .. method:: ZipFile.read(name[, pwd])
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`.
233 .. versionchanged:: 2.6
234 *pwd* was added, and *name* can now be a :class:`ZipInfo` object.
237 .. method:: ZipFile.testzip()
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`.
244 .. method:: ZipFile.write(filename[, arcname[, compress_type]])
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
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.
264 Archive names should be relative to the archive root, that is, they should not
265 start with a path separator.
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.
273 .. method:: ZipFile.writestr(zinfo_or_arcname, bytes)
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`.
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`.
290 The following data attributes are also available:
293 .. attribute:: ZipFile.debug
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
299 .. attribute:: ZipFile.comment
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.
306 .. _pyzipfile-objects:
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.
316 .. method:: PyZipFile.writepy(pathname[, basename])
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
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
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.
348 Instances have the following attributes:
351 .. attribute:: ZipInfo.filename
353 Name of the file in the archive.
356 .. attribute:: ZipInfo.date_time
358 The time and date of the last modification to the archive member. This is a
361 +-------+--------------------------+
363 +=======+==========================+
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 +-------+--------------------------+
378 .. attribute:: ZipInfo.compress_type
380 Type of compression for the archive member.
383 .. attribute:: ZipInfo.comment
385 Comment for the individual archive member.
388 .. attribute:: ZipInfo.extra
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.
395 .. attribute:: ZipInfo.create_system
397 System which created ZIP archive.
400 .. attribute:: ZipInfo.create_version
402 PKZIP version which created ZIP archive.
405 .. attribute:: ZipInfo.extract_version
407 PKZIP version needed to extract archive.
410 .. attribute:: ZipInfo.reserved
415 .. attribute:: ZipInfo.flag_bits
420 .. attribute:: ZipInfo.volume
422 Volume number of file header.
425 .. attribute:: ZipInfo.internal_attr
430 .. attribute:: ZipInfo.external_attr
432 External file attributes.
435 .. attribute:: ZipInfo.header_offset
437 Byte offset to the file header.
440 .. attribute:: ZipInfo.CRC
442 CRC-32 of the uncompressed file.
445 .. attribute:: ZipInfo.compress_size
447 Size of the compressed data.
450 .. attribute:: ZipInfo.file_size
452 Size of the uncompressed file.