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(mode='r', *, pwd, **) 493 494 Invoke :meth:`ZipFile.open` on the current path. 495 Allows opening for read or write, text or binary 496 through supported modes: 'r', 'w', 'rb', 'wb'. 497 Positional and keyword arguments are passed through to 498 :class:`io.TextIOWrapper` when opened as text and 499 ignored otherwise. 500 ``pwd`` is the ``pwd`` parameter to 501 :meth:`ZipFile.open`. 502 503 .. versionchanged:: 3.9 504 Added support for text and binary modes for open. Default 505 mode is now text. 506 507.. method:: Path.iterdir() 508 509 Enumerate the children of the current directory. 510 511.. method:: Path.is_dir() 512 513 Return ``True`` if the current context references a directory. 514 515.. method:: Path.is_file() 516 517 Return ``True`` if the current context references a file. 518 519.. method:: Path.exists() 520 521 Return ``True`` if the current context references a file or 522 directory in the zip file. 523 524.. method:: Path.read_text(*, **) 525 526 Read the current file as unicode text. Positional and 527 keyword arguments are passed through to 528 :class:`io.TextIOWrapper` (except ``buffer``, which is 529 implied by the context). 530 531.. method:: Path.read_bytes() 532 533 Read the current file as bytes. 534 535 536.. _pyzipfile-objects: 537 538PyZipFile Objects 539----------------- 540 541The :class:`PyZipFile` constructor takes the same parameters as the 542:class:`ZipFile` constructor, and one additional parameter, *optimize*. 543 544.. class:: PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, \ 545 optimize=-1) 546 547 .. versionadded:: 3.2 548 The *optimize* parameter. 549 550 .. versionchanged:: 3.4 551 ZIP64 extensions are enabled by default. 552 553 Instances have one method in addition to those of :class:`ZipFile` objects: 554 555 .. method:: PyZipFile.writepy(pathname, basename='', filterfunc=None) 556 557 Search for files :file:`\*.py` and add the corresponding file to the 558 archive. 559 560 If the *optimize* parameter to :class:`PyZipFile` was not given or ``-1``, 561 the corresponding file is a :file:`\*.pyc` file, compiling if necessary. 562 563 If the *optimize* parameter to :class:`PyZipFile` was ``0``, ``1`` or 564 ``2``, only files with that optimization level (see :func:`compile`) are 565 added to the archive, compiling if necessary. 566 567 If *pathname* is a file, the filename must end with :file:`.py`, and 568 just the (corresponding :file:`\*.pyc`) file is added at the top level 569 (no path information). If *pathname* is a file that does not end with 570 :file:`.py`, a :exc:`RuntimeError` will be raised. If it is a directory, 571 and the directory is not a package directory, then all the files 572 :file:`\*.pyc` are added at the top level. If the directory is a 573 package directory, then all :file:`\*.pyc` are added under the package 574 name as a file path, and if any subdirectories are package directories, 575 all of these are added recursively in sorted order. 576 577 *basename* is intended for internal use only. 578 579 *filterfunc*, if given, must be a function taking a single string 580 argument. It will be passed each path (including each individual full 581 file path) before it is added to the archive. If *filterfunc* returns a 582 false value, the path will not be added, and if it is a directory its 583 contents will be ignored. For example, if our test files are all either 584 in ``test`` directories or start with the string ``test_``, we can use a 585 *filterfunc* to exclude them:: 586 587 >>> zf = PyZipFile('myprog.zip') 588 >>> def notests(s): 589 ... fn = os.path.basename(s) 590 ... return (not (fn == 'test' or fn.startswith('test_'))) 591 >>> zf.writepy('myprog', filterfunc=notests) 592 593 The :meth:`writepy` method makes archives with file names like 594 this:: 595 596 string.pyc # Top level name 597 test/__init__.pyc # Package directory 598 test/testall.pyc # Module test.testall 599 test/bogus/__init__.pyc # Subpackage directory 600 test/bogus/myfile.pyc # Submodule test.bogus.myfile 601 602 .. versionadded:: 3.4 603 The *filterfunc* parameter. 604 605 .. versionchanged:: 3.6.2 606 The *pathname* parameter accepts a :term:`path-like object`. 607 608 .. versionchanged:: 3.7 609 Recursion sorts directory entries. 610 611 612.. _zipinfo-objects: 613 614ZipInfo Objects 615--------------- 616 617Instances of the :class:`ZipInfo` class are returned by the :meth:`.getinfo` and 618:meth:`.infolist` methods of :class:`ZipFile` objects. Each object stores 619information about a single member of the ZIP archive. 620 621There is one classmethod to make a :class:`ZipInfo` instance for a filesystem 622file: 623 624.. classmethod:: ZipInfo.from_file(filename, arcname=None, *, \ 625 strict_timestamps=True) 626 627 Construct a :class:`ZipInfo` instance for a file on the filesystem, in 628 preparation for adding it to a zip file. 629 630 *filename* should be the path to a file or directory on the filesystem. 631 632 If *arcname* is specified, it is used as the name within the archive. 633 If *arcname* is not specified, the name will be the same as *filename*, but 634 with any drive letter and leading path separators removed. 635 636 The *strict_timestamps* argument, when set to ``False``, allows to 637 zip files older than 1980-01-01 at the cost of setting the 638 timestamp to 1980-01-01. 639 Similar behavior occurs with files newer than 2107-12-31, 640 the timestamp is also set to the limit. 641 642 .. versionadded:: 3.6 643 644 .. versionchanged:: 3.6.2 645 The *filename* parameter accepts a :term:`path-like object`. 646 647 .. versionadded:: 3.8 648 The *strict_timestamps* keyword-only argument 649 650 651Instances have the following methods and attributes: 652 653.. method:: ZipInfo.is_dir() 654 655 Return ``True`` if this archive member is a directory. 656 657 This uses the entry's name: directories should always end with ``/``. 658 659 .. versionadded:: 3.6 660 661 662.. attribute:: ZipInfo.filename 663 664 Name of the file in the archive. 665 666 667.. attribute:: ZipInfo.date_time 668 669 The time and date of the last modification to the archive member. This is a 670 tuple of six values: 671 672 +-------+--------------------------+ 673 | Index | Value | 674 +=======+==========================+ 675 | ``0`` | Year (>= 1980) | 676 +-------+--------------------------+ 677 | ``1`` | Month (one-based) | 678 +-------+--------------------------+ 679 | ``2`` | Day of month (one-based) | 680 +-------+--------------------------+ 681 | ``3`` | Hours (zero-based) | 682 +-------+--------------------------+ 683 | ``4`` | Minutes (zero-based) | 684 +-------+--------------------------+ 685 | ``5`` | Seconds (zero-based) | 686 +-------+--------------------------+ 687 688 .. note:: 689 690 The ZIP file format does not support timestamps before 1980. 691 692 693.. attribute:: ZipInfo.compress_type 694 695 Type of compression for the archive member. 696 697 698.. attribute:: ZipInfo.comment 699 700 Comment for the individual archive member as a :class:`bytes` object. 701 702 703.. attribute:: ZipInfo.extra 704 705 Expansion field data. The `PKZIP Application Note`_ contains 706 some comments on the internal structure of the data contained in this 707 :class:`bytes` object. 708 709 710.. attribute:: ZipInfo.create_system 711 712 System which created ZIP archive. 713 714 715.. attribute:: ZipInfo.create_version 716 717 PKZIP version which created ZIP archive. 718 719 720.. attribute:: ZipInfo.extract_version 721 722 PKZIP version needed to extract archive. 723 724 725.. attribute:: ZipInfo.reserved 726 727 Must be zero. 728 729 730.. attribute:: ZipInfo.flag_bits 731 732 ZIP flag bits. 733 734 735.. attribute:: ZipInfo.volume 736 737 Volume number of file header. 738 739 740.. attribute:: ZipInfo.internal_attr 741 742 Internal attributes. 743 744 745.. attribute:: ZipInfo.external_attr 746 747 External file attributes. 748 749 750.. attribute:: ZipInfo.header_offset 751 752 Byte offset to the file header. 753 754 755.. attribute:: ZipInfo.CRC 756 757 CRC-32 of the uncompressed file. 758 759 760.. attribute:: ZipInfo.compress_size 761 762 Size of the compressed data. 763 764 765.. attribute:: ZipInfo.file_size 766 767 Size of the uncompressed file. 768 769 770.. _zipfile-commandline: 771.. program:: zipfile 772 773Command-Line Interface 774---------------------- 775 776The :mod:`zipfile` module provides a simple command-line interface to interact 777with ZIP archives. 778 779If you want to create a new ZIP archive, specify its name after the :option:`-c` 780option and then list the filename(s) that should be included: 781 782.. code-block:: shell-session 783 784 $ python -m zipfile -c monty.zip spam.txt eggs.txt 785 786Passing a directory is also acceptable: 787 788.. code-block:: shell-session 789 790 $ python -m zipfile -c monty.zip life-of-brian_1979/ 791 792If you want to extract a ZIP archive into the specified directory, use 793the :option:`-e` option: 794 795.. code-block:: shell-session 796 797 $ python -m zipfile -e monty.zip target-dir/ 798 799For a list of the files in a ZIP archive, use the :option:`-l` option: 800 801.. code-block:: shell-session 802 803 $ python -m zipfile -l monty.zip 804 805 806Command-line options 807~~~~~~~~~~~~~~~~~~~~ 808 809.. cmdoption:: -l <zipfile> 810 --list <zipfile> 811 812 List files in a zipfile. 813 814.. cmdoption:: -c <zipfile> <source1> ... <sourceN> 815 --create <zipfile> <source1> ... <sourceN> 816 817 Create zipfile from source files. 818 819.. cmdoption:: -e <zipfile> <output_dir> 820 --extract <zipfile> <output_dir> 821 822 Extract zipfile into target directory. 823 824.. cmdoption:: -t <zipfile> 825 --test <zipfile> 826 827 Test whether the zipfile is valid or not. 828 829Decompression pitfalls 830---------------------- 831 832The extraction in zipfile module might fail due to some pitfalls listed below. 833 834From file itself 835~~~~~~~~~~~~~~~~ 836 837Decompression may fail due to incorrect password / CRC checksum / ZIP format or 838unsupported compression method / decryption. 839 840File System limitations 841~~~~~~~~~~~~~~~~~~~~~~~ 842 843Exceeding limitations on different file systems can cause decompression failed. 844Such as allowable characters in the directory entries, length of the file name, 845length of the pathname, size of a single file, and number of files, etc. 846 847Resources limitations 848~~~~~~~~~~~~~~~~~~~~~ 849 850The lack of memory or disk volume would lead to decompression 851failed. For example, decompression bombs (aka `ZIP bomb`_) 852apply to zipfile library that can cause disk volume exhaustion. 853 854Interruption 855~~~~~~~~~~~~ 856 857Interruption during the decompression, such as pressing control-C or killing the 858decompression process may result in incomplete decompression of the archive. 859 860Default behaviors of extraction 861~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 862 863Not knowing the default extraction behaviors 864can cause unexpected decompression results. 865For example, when extracting the same archive twice, 866it overwrites files without asking. 867 868 869.. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb 870.. _PKZIP Application Note: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT 871