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