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