1:mod:`zipfile` --- Work with ZIP archives 2========================================= 3 4.. module:: zipfile 5 :synopsis: Read and write ZIP-format archive files. 6 7.. moduleauthor:: James C. Ahlstrom <jim@interet.com> 8.. sectionauthor:: James C. Ahlstrom <jim@interet.com> 9 10**Source code:** :source:`Lib/zipfile.py` 11 12-------------- 13 14The ZIP file format is a common archive and compression standard. This module 15provides tools to create, read, write, append, and list a ZIP file. Any 16advanced use of this module will require an understanding of the format, as 17defined in `PKZIP Application Note`_. 18 19This module does not currently handle multi-disk ZIP files. 20It can handle ZIP files that use the ZIP64 extensions 21(that is ZIP files that are more than 4 GiB in size). It supports 22decryption of encrypted files in ZIP archives, but it currently cannot 23create an encrypted file. Decryption is extremely slow as it is 24implemented in native Python rather than C. 25 26The module defines the following items: 27 28.. exception:: BadZipFile 29 30 The error raised for bad ZIP files. 31 32 .. versionadded:: 3.2 33 34 35.. exception:: BadZipfile 36 37 Alias of :exc:`BadZipFile`, for compatibility with older Python versions. 38 39 .. deprecated:: 3.2 40 41 42.. exception:: LargeZipFile 43 44 The error raised when a ZIP file would require ZIP64 functionality but that has 45 not been enabled. 46 47 48.. class:: ZipFile 49 :noindex: 50 51 The class for reading and writing ZIP files. See section 52 :ref:`zipfile-objects` for constructor details. 53 54 55.. class:: Path 56 :noindex: 57 58 A pathlib-compatible wrapper for zip files. See section 59 :ref:`path-objects` for details. 60 61 .. versionadded:: 3.8 62 63 64.. class:: PyZipFile 65 :noindex: 66 67 Class for creating ZIP archives containing Python libraries. 68 69 70.. class:: ZipInfo(filename='NoName', date_time=(1980,1,1,0,0,0)) 71 72 Class used to represent information about a member of an archive. Instances 73 of this class are returned by the :meth:`.getinfo` and :meth:`.infolist` 74 methods of :class:`ZipFile` objects. Most users of the :mod:`zipfile` module 75 will not need to create these, but only use those created by this 76 module. *filename* should be the full name of the archive member, and 77 *date_time* should be a tuple containing six fields which describe the time 78 of the last modification to the file; the fields are described in section 79 :ref:`zipinfo-objects`. 80 81 82.. function:: is_zipfile(filename) 83 84 Returns ``True`` if *filename* is a valid ZIP file based on its magic number, 85 otherwise returns ``False``. *filename* may be a file or file-like object too. 86 87 .. versionchanged:: 3.1 88 Support for file and file-like objects. 89 90 91.. data:: ZIP_STORED 92 93 The numeric constant for an uncompressed archive member. 94 95 96.. data:: ZIP_DEFLATED 97 98 The numeric constant for the usual ZIP compression method. This requires the 99 :mod:`zlib` module. 100 101 102.. data:: ZIP_BZIP2 103 104 The numeric constant for the BZIP2 compression method. This requires the 105 :mod:`bz2` module. 106 107 .. versionadded:: 3.3 108 109.. data:: ZIP_LZMA 110 111 The numeric constant for the LZMA compression method. This requires the 112 :mod:`lzma` module. 113 114 .. versionadded:: 3.3 115 116 .. note:: 117 118 The ZIP file format specification has included support for bzip2 compression 119 since 2001, and for LZMA compression since 2006. However, some tools 120 (including older Python releases) do not support these compression 121 methods, and may either refuse to process the ZIP file altogether, 122 or fail to extract individual files. 123 124 125.. seealso:: 126 127 `PKZIP Application Note`_ 128 Documentation on the ZIP file format by Phil Katz, the creator of the format and 129 algorithms used. 130 131 `Info-ZIP Home Page <http://www.info-zip.org/>`_ 132 Information about the Info-ZIP project's ZIP archive programs and development 133 libraries. 134 135 136.. _zipfile-objects: 137 138ZipFile Objects 139--------------- 140 141 142.. class:: ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, \ 143 compresslevel=None, *, strict_timestamps=True) 144 145 Open a ZIP file, where *file* can be a path to a file (a string), a 146 file-like object or a :term:`path-like object`. 147 148 The *mode* parameter should be ``'r'`` to read an existing 149 file, ``'w'`` to truncate and write a new file, ``'a'`` to append to an 150 existing file, or ``'x'`` to exclusively create and write a new file. 151 If *mode* is ``'x'`` and *file* refers to an existing file, 152 a :exc:`FileExistsError` will be raised. 153 If *mode* is ``'a'`` and *file* refers to an existing ZIP 154 file, then additional files are added to it. If *file* does not refer to a 155 ZIP file, then a new ZIP archive is appended to the file. This is meant for 156 adding a ZIP archive to another file (such as :file:`python.exe`). If 157 *mode* is ``'a'`` and the file does not exist at all, it is created. 158 If *mode* is ``'r'`` or ``'a'``, the file should be seekable. 159 160 *compression* is the ZIP compression method to use when writing the archive, 161 and should be :const:`ZIP_STORED`, :const:`ZIP_DEFLATED`, 162 :const:`ZIP_BZIP2` or :const:`ZIP_LZMA`; unrecognized 163 values will cause :exc:`NotImplementedError` to be raised. If 164 :const:`ZIP_DEFLATED`, :const:`ZIP_BZIP2` or :const:`ZIP_LZMA` is specified 165 but the corresponding module (:mod:`zlib`, :mod:`bz2` or :mod:`lzma`) is not 166 available, :exc:`RuntimeError` is raised. The default is :const:`ZIP_STORED`. 167 168 If *allowZip64* is ``True`` (the default) zipfile will create ZIP files that 169 use the ZIP64 extensions when the zipfile is larger than 4 GiB. If it is 170 ``false`` :mod:`zipfile` will raise an exception when the ZIP file would 171 require ZIP64 extensions. 172 173 The *compresslevel* parameter controls the compression level to use when 174 writing files to the archive. 175 When using :const:`ZIP_STORED` or :const:`ZIP_LZMA` it has no effect. 176 When using :const:`ZIP_DEFLATED` integers ``0`` through ``9`` are accepted 177 (see :class:`zlib <zlib.compressobj>` for more information). 178 When using :const:`ZIP_BZIP2` integers ``1`` through ``9`` are accepted 179 (see :class:`bz2 <bz2.BZ2File>` for more information). 180 181 The *strict_timestamps* argument, when set to ``False``, allows to 182 zip files older than 1980-01-01 at the cost of setting the 183 timestamp to 1980-01-01. 184 Similar behavior occurs with files newer than 2107-12-31, 185 the timestamp is also set to the limit. 186 187 If the file is created with mode ``'w'``, ``'x'`` or ``'a'`` and then 188 :meth:`closed <close>` without adding any files to the archive, the appropriate 189 ZIP structures for an empty archive will be written to the file. 190 191 ZipFile is also a context manager and therefore supports the 192 :keyword:`with` statement. In the example, *myzip* is closed after the 193 :keyword:`!with` statement's suite is finished---even if an exception occurs:: 194 195 with ZipFile('spam.zip', 'w') as myzip: 196 myzip.write('eggs.txt') 197 198 .. versionadded:: 3.2 199 Added the ability to use :class:`ZipFile` as a context manager. 200 201 .. versionchanged:: 3.3 202 Added support for :mod:`bzip2 <bz2>` and :mod:`lzma` compression. 203 204 .. versionchanged:: 3.4 205 ZIP64 extensions are enabled by default. 206 207 .. versionchanged:: 3.5 208 Added support for writing to unseekable streams. 209 Added support for the ``'x'`` mode. 210 211 .. versionchanged:: 3.6 212 Previously, a plain :exc:`RuntimeError` was raised for unrecognized 213 compression values. 214 215 .. versionchanged:: 3.6.2 216 The *file* parameter accepts a :term:`path-like object`. 217 218 .. versionchanged:: 3.7 219 Add the *compresslevel* parameter. 220 221 .. versionadded:: 3.8 222 The *strict_timestamps* keyword-only argument 223 224 225.. method:: ZipFile.close() 226 227 Close the archive file. You must call :meth:`close` before exiting your program 228 or essential records will not be written. 229 230 231.. method:: ZipFile.getinfo(name) 232 233 Return a :class:`ZipInfo` object with information about the archive member 234 *name*. Calling :meth:`getinfo` for a name not currently contained in the 235 archive will raise a :exc:`KeyError`. 236 237 238.. method:: ZipFile.infolist() 239 240 Return a list containing a :class:`ZipInfo` object for each member of the 241 archive. The objects are in the same order as their entries in the actual ZIP 242 file on disk if an existing archive was opened. 243 244 245.. method:: ZipFile.namelist() 246 247 Return a list of archive members by name. 248 249 250.. method:: ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False) 251 252 Access a member of the archive as a binary file-like object. *name* 253 can be either the name of a file within the archive or a :class:`ZipInfo` 254 object. The *mode* parameter, if included, must be ``'r'`` (the default) 255 or ``'w'``. *pwd* is the password used to decrypt encrypted ZIP files. 256 257 :meth:`~ZipFile.open` is also a context manager and therefore supports the 258 :keyword:`with` statement:: 259 260 with ZipFile('spam.zip') as myzip: 261 with myzip.open('eggs.txt') as myfile: 262 print(myfile.read()) 263 264 With *mode* ``'r'`` the file-like object 265 (``ZipExtFile``) is read-only and provides the following methods: 266 :meth:`~io.BufferedIOBase.read`, :meth:`~io.IOBase.readline`, 267 :meth:`~io.IOBase.readlines`, :meth:`~io.IOBase.seek`, 268 :meth:`~io.IOBase.tell`, :meth:`__iter__`, :meth:`~iterator.__next__`. 269 These objects can operate independently of the ZipFile. 270 271 With ``mode='w'``, a writable file handle is returned, which supports the 272 :meth:`~io.BufferedIOBase.write` method. While a writable file handle is open, 273 attempting to read or write other files in the ZIP file will raise a 274 :exc:`ValueError`. 275 276 When writing a file, if the file size is not known in advance but may exceed 277 2 GiB, pass ``force_zip64=True`` to ensure that the header format is 278 capable of supporting large files. If the file size is known in advance, 279 construct a :class:`ZipInfo` object with :attr:`~ZipInfo.file_size` set, and 280 use that as the *name* parameter. 281 282 .. note:: 283 284 The :meth:`.open`, :meth:`read` and :meth:`extract` methods can take a filename 285 or a :class:`ZipInfo` object. You will appreciate this when trying to read a 286 ZIP file that contains members with duplicate names. 287 288 .. versionchanged:: 3.6 289 Removed support of ``mode='U'``. Use :class:`io.TextIOWrapper` for reading 290 compressed text files in :term:`universal newlines` mode. 291 292 .. versionchanged:: 3.6 293 :meth:`open` can now be used to write files into the archive with the 294 ``mode='w'`` option. 295 296 .. versionchanged:: 3.6 297 Calling :meth:`.open` on a closed ZipFile will raise a :exc:`ValueError`. 298 Previously, a :exc:`RuntimeError` was raised. 299 300 301.. method:: ZipFile.extract(member, path=None, pwd=None) 302 303 Extract a member from the archive to the current working directory; *member* 304 must be its full name or a :class:`ZipInfo` object. Its file information is 305 extracted as accurately as possible. *path* specifies a different directory 306 to extract to. *member* can be a filename or a :class:`ZipInfo` object. 307 *pwd* is the password used for encrypted files. 308 309 Returns the normalized path created (a directory or new file). 310 311 .. note:: 312 313 If a member filename is an absolute path, a drive/UNC sharepoint and 314 leading (back)slashes will be stripped, e.g.: ``///foo/bar`` becomes 315 ``foo/bar`` on Unix, and ``C:\foo\bar`` becomes ``foo\bar`` on Windows. 316 And all ``".."`` components in a member filename will be removed, e.g.: 317 ``../../foo../../ba..r`` becomes ``foo../ba..r``. On Windows illegal 318 characters (``:``, ``<``, ``>``, ``|``, ``"``, ``?``, and ``*``) 319 replaced by underscore (``_``). 320 321 .. versionchanged:: 3.6 322 Calling :meth:`extract` on a closed ZipFile will raise a 323 :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised. 324 325 .. versionchanged:: 3.6.2 326 The *path* parameter accepts a :term:`path-like object`. 327 328 329.. method:: ZipFile.extractall(path=None, members=None, pwd=None) 330 331 Extract all members from the archive to the current working directory. *path* 332 specifies a different directory to extract to. *members* is optional and must 333 be a subset of the list returned by :meth:`namelist`. *pwd* is the password 334 used for encrypted files. 335 336 .. warning:: 337 338 Never extract archives from untrusted sources without prior inspection. 339 It is possible that files are created outside of *path*, e.g. members 340 that have absolute filenames starting with ``"/"`` or filenames with two 341 dots ``".."``. This module attempts to prevent that. 342 See :meth:`extract` note. 343 344 .. versionchanged:: 3.6 345 Calling :meth:`extractall` on a closed ZipFile will raise a 346 :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised. 347 348 .. versionchanged:: 3.6.2 349 The *path* parameter accepts a :term:`path-like object`. 350 351 352.. method:: ZipFile.printdir() 353 354 Print a table of contents for the archive to ``sys.stdout``. 355 356 357.. method:: ZipFile.setpassword(pwd) 358 359 Set *pwd* as default password to extract encrypted files. 360 361 362.. method:: ZipFile.read(name, pwd=None) 363 364 Return the bytes of the file *name* in the archive. *name* is the name of the 365 file in the archive, or a :class:`ZipInfo` object. The archive must be open for 366 read or append. *pwd* is the password used for encrypted files and, if specified, 367 it will override the default password set with :meth:`setpassword`. Calling 368 :meth:`read` on a ZipFile that uses a compression method other than 369 :const:`ZIP_STORED`, :const:`ZIP_DEFLATED`, :const:`ZIP_BZIP2` or 370 :const:`ZIP_LZMA` will raise a :exc:`NotImplementedError`. An error will also 371 be raised if the corresponding compression module is not available. 372 373 .. versionchanged:: 3.6 374 Calling :meth:`read` on a closed ZipFile will raise a :exc:`ValueError`. 375 Previously, a :exc:`RuntimeError` was raised. 376 377 378.. method:: ZipFile.testzip() 379 380 Read all the files in the archive and check their CRC's and file headers. 381 Return the name of the first bad file, or else return ``None``. 382 383 .. versionchanged:: 3.6 384 Calling :meth:`testzip` on a closed ZipFile will raise a 385 :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised. 386 387 388.. method:: ZipFile.write(filename, arcname=None, compress_type=None, \ 389 compresslevel=None) 390 391 Write the file named *filename* to the archive, giving it the archive name 392 *arcname* (by default, this will be the same as *filename*, but without a drive 393 letter and with leading path separators removed). If given, *compress_type* 394 overrides the value given for the *compression* parameter to the constructor for 395 the new entry. Similarly, *compresslevel* will override the constructor if 396 given. 397 The archive must be open with mode ``'w'``, ``'x'`` or ``'a'``. 398 399 .. note:: 400 401 Archive names should be relative to the archive root, that is, they should not 402 start with a path separator. 403 404 .. note:: 405 406 If ``arcname`` (or ``filename``, if ``arcname`` is not given) contains a null 407 byte, the name of the file in the archive will be truncated at the null byte. 408 409 .. versionchanged:: 3.6 410 Calling :meth:`write` on a ZipFile created with mode ``'r'`` or 411 a closed ZipFile will raise a :exc:`ValueError`. Previously, 412 a :exc:`RuntimeError` was raised. 413 414 415.. method:: ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, \ 416 compresslevel=None) 417 418 Write a file into the archive. The contents is *data*, which may be either 419 a :class:`str` or a :class:`bytes` instance; if it is a :class:`str`, 420 it is encoded as UTF-8 first. *zinfo_or_arcname* is either the file 421 name it will be given in the archive, or a :class:`ZipInfo` instance. If it's 422 an instance, at least the filename, date, and time must be given. If it's a 423 name, the date and time is set to the current date and time. 424 The archive must be opened with mode ``'w'``, ``'x'`` or ``'a'``. 425 426 If given, *compress_type* overrides the value given for the *compression* 427 parameter to the constructor for the new entry, or in the *zinfo_or_arcname* 428 (if that is a :class:`ZipInfo` instance). Similarly, *compresslevel* will 429 override the constructor if given. 430 431 .. note:: 432 433 When passing a :class:`ZipInfo` instance as the *zinfo_or_arcname* parameter, 434 the compression method used will be that specified in the *compress_type* 435 member of the given :class:`ZipInfo` instance. By default, the 436 :class:`ZipInfo` constructor sets this member to :const:`ZIP_STORED`. 437 438 .. versionchanged:: 3.2 439 The *compress_type* argument. 440 441 .. versionchanged:: 3.6 442 Calling :meth:`writestr` on a ZipFile created with mode ``'r'`` or 443 a closed ZipFile will raise a :exc:`ValueError`. Previously, 444 a :exc:`RuntimeError` was raised. 445 446 447The following data attributes are also available: 448 449.. attribute:: ZipFile.filename 450 451 Name of the ZIP file. 452 453.. attribute:: ZipFile.debug 454 455 The level of debug output to use. This may be set from ``0`` (the default, no 456 output) to ``3`` (the most output). Debugging information is written to 457 ``sys.stdout``. 458 459.. attribute:: ZipFile.comment 460 461 The comment associated with the ZIP file as a :class:`bytes` object. 462 If assigning a comment to a 463 :class:`ZipFile` instance created with mode ``'w'``, ``'x'`` or ``'a'``, 464 it should be no longer than 65535 bytes. Comments longer than this will be 465 truncated. 466 467 468.. _path-objects: 469 470Path Objects 471------------ 472 473.. class:: Path(root, at='') 474 475 Construct a Path object from a ``root`` zipfile (which may be a 476 :class:`ZipFile` instance or ``file`` suitable for passing to 477 the :class:`ZipFile` constructor). 478 479 ``at`` specifies the location of this Path within the zipfile, 480 e.g. 'dir/file.txt', 'dir/', or ''. Defaults to the empty string, 481 indicating the root. 482 483Path objects expose the following features of :mod:`pathlib.Path` 484objects: 485 486Path objects are traversable using the ``/`` operator. 487 488.. attribute:: Path.name 489 490 The final path component. 491 492.. method:: Path.open(*, **) 493 494 Invoke :meth:`ZipFile.open` on the current path. Accepts 495 the same arguments as :meth:`ZipFile.open`. 496 497 .. caution:: 498 499 The signature on this function changes in an incompatible way 500 in Python 3.9. For a future-compatible version, consider using 501 the third-party zipp.Path package (3.0 or later). 502 503.. method:: Path.iterdir() 504 505 Enumerate the children of the current directory. 506 507.. method:: Path.is_dir() 508 509 Return ``True`` if the current context references a directory. 510 511.. method:: Path.is_file() 512 513 Return ``True`` if the current context references a file. 514 515.. method:: Path.exists() 516 517 Return ``True`` if the current context references a file or 518 directory in the zip file. 519 520.. method:: Path.read_text(*, **) 521 522 Read the current file as unicode text. Positional and 523 keyword arguments are passed through to 524 :class:`io.TextIOWrapper` (except ``buffer``, which is 525 implied by the context). 526 527.. method:: Path.read_bytes() 528 529 Read the current file as bytes. 530 531 532.. _pyzipfile-objects: 533 534PyZipFile Objects 535----------------- 536 537The :class:`PyZipFile` constructor takes the same parameters as the 538:class:`ZipFile` constructor, and one additional parameter, *optimize*. 539 540.. class:: PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, \ 541 optimize=-1) 542 543 .. versionadded:: 3.2 544 The *optimize* parameter. 545 546 .. versionchanged:: 3.4 547 ZIP64 extensions are enabled by default. 548 549 Instances have one method in addition to those of :class:`ZipFile` objects: 550 551 .. method:: PyZipFile.writepy(pathname, basename='', filterfunc=None) 552 553 Search for files :file:`\*.py` and add the corresponding file to the 554 archive. 555 556 If the *optimize* parameter to :class:`PyZipFile` was not given or ``-1``, 557 the corresponding file is a :file:`\*.pyc` file, compiling if necessary. 558 559 If the *optimize* parameter to :class:`PyZipFile` was ``0``, ``1`` or 560 ``2``, only files with that optimization level (see :func:`compile`) are 561 added to the archive, compiling if necessary. 562 563 If *pathname* is a file, the filename must end with :file:`.py`, and 564 just the (corresponding :file:`\*.pyc`) file is added at the top level 565 (no path information). If *pathname* is a file that does not end with 566 :file:`.py`, a :exc:`RuntimeError` will be raised. If it is a directory, 567 and the directory is not a package directory, then all the files 568 :file:`\*.pyc` are added at the top level. If the directory is a 569 package directory, then all :file:`\*.pyc` are added under the package 570 name as a file path, and if any subdirectories are package directories, 571 all of these are added recursively in sorted order. 572 573 *basename* is intended for internal use only. 574 575 *filterfunc*, if given, must be a function taking a single string 576 argument. It will be passed each path (including each individual full 577 file path) before it is added to the archive. If *filterfunc* returns a 578 false value, the path will not be added, and if it is a directory its 579 contents will be ignored. For example, if our test files are all either 580 in ``test`` directories or start with the string ``test_``, we can use a 581 *filterfunc* to exclude them:: 582 583 >>> zf = PyZipFile('myprog.zip') 584 >>> def notests(s): 585 ... fn = os.path.basename(s) 586 ... return (not (fn == 'test' or fn.startswith('test_'))) 587 >>> zf.writepy('myprog', filterfunc=notests) 588 589 The :meth:`writepy` method makes archives with file names like 590 this:: 591 592 string.pyc # Top level name 593 test/__init__.pyc # Package directory 594 test/testall.pyc # Module test.testall 595 test/bogus/__init__.pyc # Subpackage directory 596 test/bogus/myfile.pyc # Submodule test.bogus.myfile 597 598 .. versionadded:: 3.4 599 The *filterfunc* parameter. 600 601 .. versionchanged:: 3.6.2 602 The *pathname* parameter accepts a :term:`path-like object`. 603 604 .. versionchanged:: 3.7 605 Recursion sorts directory entries. 606 607 608.. _zipinfo-objects: 609 610ZipInfo Objects 611--------------- 612 613Instances of the :class:`ZipInfo` class are returned by the :meth:`.getinfo` and 614:meth:`.infolist` methods of :class:`ZipFile` objects. Each object stores 615information about a single member of the ZIP archive. 616 617There is one classmethod to make a :class:`ZipInfo` instance for a filesystem 618file: 619 620.. classmethod:: ZipInfo.from_file(filename, arcname=None, *, \ 621 strict_timestamps=True) 622 623 Construct a :class:`ZipInfo` instance for a file on the filesystem, in 624 preparation for adding it to a zip file. 625 626 *filename* should be the path to a file or directory on the filesystem. 627 628 If *arcname* is specified, it is used as the name within the archive. 629 If *arcname* is not specified, the name will be the same as *filename*, but 630 with any drive letter and leading path separators removed. 631 632 The *strict_timestamps* argument, when set to ``False``, allows to 633 zip files older than 1980-01-01 at the cost of setting the 634 timestamp to 1980-01-01. 635 Similar behavior occurs with files newer than 2107-12-31, 636 the timestamp is also set to the limit. 637 638 .. versionadded:: 3.6 639 640 .. versionchanged:: 3.6.2 641 The *filename* parameter accepts a :term:`path-like object`. 642 643 .. versionadded:: 3.8 644 The *strict_timestamps* keyword-only argument 645 646 647Instances have the following methods and attributes: 648 649.. method:: ZipInfo.is_dir() 650 651 Return ``True`` if this archive member is a directory. 652 653 This uses the entry's name: directories should always end with ``/``. 654 655 .. versionadded:: 3.6 656 657 658.. attribute:: ZipInfo.filename 659 660 Name of the file in the archive. 661 662 663.. attribute:: ZipInfo.date_time 664 665 The time and date of the last modification to the archive member. This is a 666 tuple of six values: 667 668 +-------+--------------------------+ 669 | Index | Value | 670 +=======+==========================+ 671 | ``0`` | Year (>= 1980) | 672 +-------+--------------------------+ 673 | ``1`` | Month (one-based) | 674 +-------+--------------------------+ 675 | ``2`` | Day of month (one-based) | 676 +-------+--------------------------+ 677 | ``3`` | Hours (zero-based) | 678 +-------+--------------------------+ 679 | ``4`` | Minutes (zero-based) | 680 +-------+--------------------------+ 681 | ``5`` | Seconds (zero-based) | 682 +-------+--------------------------+ 683 684 .. note:: 685 686 The ZIP file format does not support timestamps before 1980. 687 688 689.. attribute:: ZipInfo.compress_type 690 691 Type of compression for the archive member. 692 693 694.. attribute:: ZipInfo.comment 695 696 Comment for the individual archive member as a :class:`bytes` object. 697 698 699.. attribute:: ZipInfo.extra 700 701 Expansion field data. The `PKZIP Application Note`_ contains 702 some comments on the internal structure of the data contained in this 703 :class:`bytes` object. 704 705 706.. attribute:: ZipInfo.create_system 707 708 System which created ZIP archive. 709 710 711.. attribute:: ZipInfo.create_version 712 713 PKZIP version which created ZIP archive. 714 715 716.. attribute:: ZipInfo.extract_version 717 718 PKZIP version needed to extract archive. 719 720 721.. attribute:: ZipInfo.reserved 722 723 Must be zero. 724 725 726.. attribute:: ZipInfo.flag_bits 727 728 ZIP flag bits. 729 730 731.. attribute:: ZipInfo.volume 732 733 Volume number of file header. 734 735 736.. attribute:: ZipInfo.internal_attr 737 738 Internal attributes. 739 740 741.. attribute:: ZipInfo.external_attr 742 743 External file attributes. 744 745 746.. attribute:: ZipInfo.header_offset 747 748 Byte offset to the file header. 749 750 751.. attribute:: ZipInfo.CRC 752 753 CRC-32 of the uncompressed file. 754 755 756.. attribute:: ZipInfo.compress_size 757 758 Size of the compressed data. 759 760 761.. attribute:: ZipInfo.file_size 762 763 Size of the uncompressed file. 764 765 766.. _zipfile-commandline: 767.. program:: zipfile 768 769Command-Line Interface 770---------------------- 771 772The :mod:`zipfile` module provides a simple command-line interface to interact 773with ZIP archives. 774 775If you want to create a new ZIP archive, specify its name after the :option:`-c` 776option and then list the filename(s) that should be included: 777 778.. code-block:: shell-session 779 780 $ python -m zipfile -c monty.zip spam.txt eggs.txt 781 782Passing a directory is also acceptable: 783 784.. code-block:: shell-session 785 786 $ python -m zipfile -c monty.zip life-of-brian_1979/ 787 788If you want to extract a ZIP archive into the specified directory, use 789the :option:`-e` option: 790 791.. code-block:: shell-session 792 793 $ python -m zipfile -e monty.zip target-dir/ 794 795For a list of the files in a ZIP archive, use the :option:`-l` option: 796 797.. code-block:: shell-session 798 799 $ python -m zipfile -l monty.zip 800 801 802Command-line options 803~~~~~~~~~~~~~~~~~~~~ 804 805.. cmdoption:: -l <zipfile> 806 --list <zipfile> 807 808 List files in a zipfile. 809 810.. cmdoption:: -c <zipfile> <source1> ... <sourceN> 811 --create <zipfile> <source1> ... <sourceN> 812 813 Create zipfile from source files. 814 815.. cmdoption:: -e <zipfile> <output_dir> 816 --extract <zipfile> <output_dir> 817 818 Extract zipfile into target directory. 819 820.. cmdoption:: -t <zipfile> 821 --test <zipfile> 822 823 Test whether the zipfile is valid or not. 824 825Decompression pitfalls 826---------------------- 827 828The extraction in zipfile module might fail due to some pitfalls listed below. 829 830From file itself 831~~~~~~~~~~~~~~~~ 832 833Decompression may fail due to incorrect password / CRC checksum / ZIP format or 834unsupported compression method / decryption. 835 836File System limitations 837~~~~~~~~~~~~~~~~~~~~~~~ 838 839Exceeding limitations on different file systems can cause decompression failed. 840Such as allowable characters in the directory entries, length of the file name, 841length of the pathname, size of a single file, and number of files, etc. 842 843Resources limitations 844~~~~~~~~~~~~~~~~~~~~~ 845 846The lack of memory or disk volume would lead to decompression 847failed. For example, decompression bombs (aka `ZIP bomb`_) 848apply to zipfile library that can cause disk volume exhaustion. 849 850Interruption 851~~~~~~~~~~~~ 852 853Interruption during the decompression, such as pressing control-C or killing the 854decompression process may result in incomplete decompression of the archive. 855 856Default behaviors of extraction 857~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 858 859Not knowing the default extraction behaviors 860can cause unexpected decompression results. 861For example, when extracting the same archive twice, 862it overwrites files without asking. 863 864 865.. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb 866.. _PKZIP Application Note: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT 867