Debian Codegraph @

Doc/library/zipfile.rst

raw
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 <[email protected]>
8 .. sectionauthor:: James C. Ahlstrom <[email protected]>
9
10 **Source code:** :source:`Lib/zipfile/`
11
12 --------------
13
14 The ZIP file format is a common archive and compression standard. This module
15 provides tools to create, read, write, append, and list a ZIP file. Any
16 advanced use of this module will require an understanding of the format, as
17 defined in `PKZIP Application Note`_.
18
19 This module does not handle multipart ZIP files.
20 It can handle ZIP files that use the ZIP64 extensions
21 (that is ZIP files that are more than 4 GiB in size). It supports
22 decryption of encrypted files in ZIP archives, but it cannot
23 create an encrypted file. Decryption is extremely slow as it is
24 implemented in native Python rather than C.
25
26 ..
27 The following paragraph should be similar to ../includes/optional-module.rst
28
29 Handling compressed archives requires :term:`optional modules <optional module>`
30 such as :mod:`zlib`, :mod:`bz2`, :mod:`lzma`, and :mod:`compression.zstd`.
31 If any of them are missing from your copy of CPython,
32 look for documentation from your distributor (that is,
33 whoever provided Python to you).
34 If you are the distributor, see :ref:`optional-module-requirements`.
35
36 The module defines the following items:
37
38 .. exception:: BadZipFile
39
40 The error raised for bad ZIP files.
41
42 .. versionadded:: 3.2
43
44
45 .. exception:: BadZipfile
46
47 Alias of :exc:`BadZipFile`, for compatibility with older Python versions.
48
49 .. deprecated:: 3.2
50
51
52 .. exception:: LargeZipFile
53
54 The error raised when a ZIP file would require ZIP64 functionality but that has
55 not been enabled.
56
57
58 .. class:: ZipFile
59 :noindex:
60
61 The class for reading and writing ZIP files. See section
62 :ref:`zipfile-objects` for constructor details.
63
64
65 .. class:: Path
66 :noindex:
67
68 Class that implements a subset of the interface provided by
69 :class:`pathlib.Path`, including the full
70 :class:`importlib.resources.abc.Traversable` interface.
71
72 .. versionadded:: 3.8
73
74
75 .. class:: PyZipFile
76 :noindex:
77
78 Class for creating ZIP archives containing Python libraries.
79
80
81 .. class:: ZipInfo(filename='NoName', date_time=(1980,1,1,0,0,0))
82
83 Class used to represent information about a member of an archive. Instances
84 of this class are returned by the :meth:`.getinfo` and :meth:`.infolist`
85 methods of :class:`ZipFile` objects. Most users of the :mod:`!zipfile` module
86 will not need to create these, but only use those created by this
87 module. *filename* should be the full name of the archive member, and
88 *date_time* should be a tuple containing six fields which describe the time
89 of the last modification to the file; the fields are described in section
90 :ref:`zipinfo-objects`.
91
92 .. versionchanged:: 3.13
93 A public :attr:`!compress_level` attribute has been added to expose the
94 formerly protected :attr:`!_compresslevel`. The older protected name
95 continues to work as a property for backwards compatibility.
96
97
98 .. method:: _for_archive(archive)
99
100 Resolve the date_time, compression attributes, and external attributes
101 to suitable defaults as used by :meth:`ZipFile.writestr`.
102
103 Returns self for chaining.
104
105 .. versionadded:: 3.14
106
107
108 .. function:: is_zipfile(filename)
109
110 Returns ``True`` if *filename* is a valid ZIP file based on its magic number,
111 otherwise returns ``False``. *filename* may be a file or file-like object too.
112
113 .. versionchanged:: 3.1
114 Support for file and file-like objects.
115
116
117 .. data:: ZIP_STORED
118
119 The numeric constant for an uncompressed archive member.
120
121
122 .. data:: ZIP_DEFLATED
123
124 The numeric constant for the usual ZIP compression method. This requires the
125 :mod:`zlib` module.
126
127
128 .. data:: ZIP_BZIP2
129
130 The numeric constant for the BZIP2 compression method. This requires the
131 :mod:`bz2` module.
132
133 .. versionadded:: 3.3
134
135 .. data:: ZIP_LZMA
136
137 The numeric constant for the LZMA compression method. This requires the
138 :mod:`lzma` module.
139
140 .. versionadded:: 3.3
141
142 .. data:: ZIP_ZSTANDARD
143
144 The numeric constant for Zstandard compression. This requires the
145 :mod:`compression.zstd` module.
146
147 .. note::
148
149 In APPNOTE 6.3.7, the method ID ``20`` was assigned to Zstandard
150 compression. This was changed in APPNOTE 6.3.8 to method ID ``93`` to
151 avoid conflicts, with method ID ``20`` being deprecated. For
152 compatibility, the :mod:`!zipfile` module reads both method IDs but will
153 only write data with method ID ``93``.
154
155 .. versionadded:: 3.14
156
157 .. note::
158
159 The ZIP file format specification has included support for bzip2 compression
160 since 2001, for LZMA compression since 2006, and Zstandard compression since
161 2020. However, some tools (including older Python releases) do not support
162 these compression methods, and may either refuse to process the ZIP file
163 altogether, or fail to extract individual files.
164
165 .. seealso::
166
167 `PKZIP Application Note`_
168 Documentation on the ZIP file format by Phil Katz, the creator of the format and
169 algorithms used.
170
171 `Info-ZIP Home Page <https://infozip.sourceforge.net/>`_
172 Information about the Info-ZIP project's ZIP archive programs and development
173 libraries.
174
175
176 .. _zipfile-objects:
177
178 ZipFile objects
179 ---------------
180
181
182 .. class:: ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, \
183 compresslevel=None, *, strict_timestamps=True, \
184 metadata_encoding=None)
185
186 Open a ZIP file, where *file* can be a path to a file (a string), a
187 file-like object or a :term:`path-like object`.
188
189 The *mode* parameter should be ``'r'`` to read an existing
190 file, ``'w'`` to truncate and write a new file, ``'a'`` to append to an
191 existing file, or ``'x'`` to exclusively create and write a new file.
192 If *mode* is ``'x'`` and *file* refers to an existing file,
193 a :exc:`FileExistsError` will be raised.
194 If *mode* is ``'a'`` and *file* refers to an existing ZIP
195 file, then additional files are added to it. If *file* does not refer to a
196 ZIP file, then a new ZIP archive is appended to the file. This is meant for
197 adding a ZIP archive to another file (such as :file:`python.exe`). If
198 *mode* is ``'a'`` and the file does not exist at all, it is created.
199 If *mode* is ``'r'`` or ``'a'``, the file should be seekable.
200
201 *compression* is the ZIP compression method to use when writing the archive,
202 and should be :const:`ZIP_STORED`, :const:`ZIP_DEFLATED`,
203 :const:`ZIP_BZIP2`, :const:`ZIP_LZMA`, or :const:`ZIP_ZSTANDARD`;
204 unrecognized values will cause :exc:`NotImplementedError` to be raised. If
205 :const:`ZIP_DEFLATED`, :const:`ZIP_BZIP2`, :const:`ZIP_LZMA`, or
206 :const:`ZIP_ZSTANDARD` is specified but the corresponding module
207 (:mod:`zlib`, :mod:`bz2`, :mod:`lzma`, or :mod:`compression.zstd`) is not
208 available, :exc:`RuntimeError` is raised. The default is :const:`ZIP_STORED`.
209
210 If *allowZip64* is ``True`` (the default) zipfile will create ZIP files that
211 use the ZIP64 extensions when the zipfile is larger than 4 GiB. If it is
212 ``false`` :mod:`!zipfile` will raise an exception when the ZIP file would
213 require ZIP64 extensions.
214
215 The *compresslevel* parameter controls the compression level to use when
216 writing files to the archive.
217 When using :const:`ZIP_STORED` or :const:`ZIP_LZMA` it has no effect.
218 When using :const:`ZIP_DEFLATED` integers ``0`` through ``9`` are accepted
219 (see :class:`zlib <zlib.compressobj>` for more information).
220 When using :const:`ZIP_BZIP2` integers ``1`` through ``9`` are accepted
221 (see :class:`bz2 <bz2.BZ2File>` for more information).
222 When using :const:`ZIP_ZSTANDARD` integers ``-131072`` through ``22`` are
223 commonly accepted (see
224 :attr:`CompressionParameter.compression_level <compression.zstd.CompressionParameter.compression_level>`
225 for more on retrieving valid values and their meaning).
226
227 The *strict_timestamps* argument, when set to ``False``, allows to
228 zip files older than 1980-01-01 at the cost of setting the
229 timestamp to 1980-01-01.
230 Similar behavior occurs with files newer than 2107-12-31,
231 the timestamp is also set to the limit.
232
233 When mode is ``'r'``, *metadata_encoding* may be set to the name of a codec,
234 which will be used to decode metadata such as the names of members and ZIP
235 comments.
236
237 If the file is created with mode ``'w'``, ``'x'`` or ``'a'`` and then
238 :meth:`closed <close>` without adding any files to the archive, the appropriate
239 ZIP structures for an empty archive will be written to the file.
240
241 ZipFile is also a context manager and therefore supports the
242 :keyword:`with` statement. In the example, *myzip* is closed after the
243 :keyword:`!with` statement's suite is finished---even if an exception occurs::
244
245 with ZipFile('spam.zip', 'w') as myzip:
246 myzip.write('eggs.txt')
247
248 .. note::
249
250 *metadata_encoding* is an instance-wide setting for the ZipFile.
251 It is not possible to set this on a per-member basis.
252
253 This attribute is a workaround for legacy implementations which produce
254 archives with names in the current locale encoding or code page (mostly
255 on Windows). According to the .ZIP standard, the encoding of metadata
256 may be specified to be either IBM code page (default) or UTF-8 by a flag
257 in the archive header.
258 That flag takes precedence over *metadata_encoding*, which is
259 a Python-specific extension.
260
261 .. versionchanged:: 3.2
262 Added the ability to use :class:`ZipFile` as a context manager.
263
264 .. versionchanged:: 3.3
265 Added support for :mod:`bzip2 <bz2>` and :mod:`lzma` compression.
266
267 .. versionchanged:: 3.4
268 ZIP64 extensions are enabled by default.
269
270 .. versionchanged:: 3.5
271 Added support for writing to unseekable streams.
272 Added support for the ``'x'`` mode.
273
274 .. versionchanged:: 3.6
275 Previously, a plain :exc:`RuntimeError` was raised for unrecognized
276 compression values.
277
278 .. versionchanged:: 3.6.2
279 The *file* parameter accepts a :term:`path-like object`.
280
281 .. versionchanged:: 3.7
282 Add the *compresslevel* parameter.
283
284 .. versionchanged:: 3.8
285 The *strict_timestamps* keyword-only parameter.
286
287 .. versionchanged:: 3.11
288 Added support for specifying member name encoding for reading
289 metadata in the zipfile's directory and file headers.
290
291
292 .. method:: ZipFile.close()
293
294 Close the archive file. You must call :meth:`close` before exiting your program
295 or essential records will not be written.
296
297
298 .. method:: ZipFile.getinfo(name)
299
300 Return a :class:`ZipInfo` object with information about the archive member
301 *name*. Calling :meth:`getinfo` for a name not currently contained in the
302 archive will raise a :exc:`KeyError`.
303
304
305 .. method:: ZipFile.infolist()
306
307 Return a list containing a :class:`ZipInfo` object for each member of the
308 archive. The objects are in the same order as their entries in the actual ZIP
309 file on disk if an existing archive was opened.
310
311
312 .. method:: ZipFile.namelist()
313
314 Return a list of archive members by name.
315
316
317 .. method:: ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)
318
319 Access a member of the archive as a binary file-like object. *name*
320 can be either the name of a file within the archive or a :class:`ZipInfo`
321 object. The *mode* parameter, if included, must be ``'r'`` (the default)
322 or ``'w'``. *pwd* is the password used to decrypt encrypted ZIP files as a
323 :class:`bytes` object.
324
325 :meth:`~ZipFile.open` is also a context manager and therefore supports the
326 :keyword:`with` statement::
327
328 with ZipFile('spam.zip') as myzip:
329 with myzip.open('eggs.txt') as myfile:
330 print(myfile.read())
331
332 With *mode* ``'r'`` the file-like object
333 (``ZipExtFile``) is read-only and provides the following methods:
334 :meth:`~io.BufferedIOBase.read`, :meth:`~io.IOBase.readline`,
335 :meth:`~io.IOBase.readlines`, :meth:`~io.IOBase.seek`,
336 :meth:`~io.IOBase.tell`, :meth:`~container.__iter__`, :meth:`~iterator.__next__`.
337 These objects can operate independently of the ZipFile.
338
339 With ``mode='w'``, a writable file handle is returned, which supports the
340 :meth:`~io.BufferedIOBase.write` method. While a writable file handle is open,
341 attempting to read or write other files in the ZIP file will raise a
342 :exc:`ValueError`.
343
344 In both cases the file-like object has also attributes :attr:`!name`,
345 which is equivalent to the name of a file within the archive, and
346 :attr:`!mode`, which is ``'rb'`` or ``'wb'`` depending on the input mode.
347
348 When writing a file, if the file size is not known in advance but may exceed
349 2 GiB, pass ``force_zip64=True`` to ensure that the header format is
350 capable of supporting large files. If the file size is known in advance,
351 construct a :class:`ZipInfo` object with :attr:`~ZipInfo.file_size` set, and
352 use that as the *name* parameter.
353
354 .. note::
355
356 The :meth:`.open`, :meth:`read` and :meth:`extract` methods can take a filename
357 or a :class:`ZipInfo` object. You will appreciate this when trying to read a
358 ZIP file that contains members with duplicate names.
359
360 .. versionchanged:: 3.6
361 Removed support of ``mode='U'``. Use :class:`io.TextIOWrapper` for reading
362 compressed text files in :term:`universal newlines` mode.
363
364 .. versionchanged:: 3.6
365 :meth:`ZipFile.open` can now be used to write files into the archive with the
366 ``mode='w'`` option.
367
368 .. versionchanged:: 3.6
369 Calling :meth:`.open` on a closed ZipFile will raise a :exc:`ValueError`.
370 Previously, a :exc:`RuntimeError` was raised.
371
372 .. versionchanged:: 3.13
373 Added attributes :attr:`!name` and :attr:`!mode` for the writeable
374 file-like object.
375 The value of the :attr:`!mode` attribute for the readable file-like
376 object was changed from ``'r'`` to ``'rb'``.
377
378
379 .. method:: ZipFile.extract(member, path=None, pwd=None)
380
381 Extract a member from the archive to the current working directory; *member*
382 must be its full name or a :class:`ZipInfo` object. Its file information is
383 extracted as accurately as possible. *path* specifies a different directory
384 to extract to. *member* can be a filename or a :class:`ZipInfo` object.
385 *pwd* is the password used for encrypted files as a :class:`bytes` object.
386
387 Returns the normalized path created (a directory or new file).
388
389 .. note::
390
391 If a member filename is an absolute path, a drive/UNC sharepoint and
392 leading (back)slashes will be stripped, e.g.: ``///foo/bar`` becomes
393 ``foo/bar`` on Unix, and ``C:\foo\bar`` becomes ``foo\bar`` on Windows.
394 And all ``".."`` components in a member filename will be removed, e.g.:
395 ``../../foo../../ba..r`` becomes ``foo../ba..r``. On Windows illegal
396 characters (``:``, ``<``, ``>``, ``|``, ``"``, ``?``, and ``*``)
397 replaced by underscore (``_``).
398
399 .. versionchanged:: 3.6
400 Calling :meth:`extract` on a closed ZipFile will raise a
401 :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised.
402
403 .. versionchanged:: 3.6.2
404 The *path* parameter accepts a :term:`path-like object`.
405
406
407 .. method:: ZipFile.extractall(path=None, members=None, pwd=None)
408
409 Extract all members from the archive to the current working directory. *path*
410 specifies a different directory to extract to. *members* is optional and must
411 be a subset of the list returned by :meth:`namelist`. *pwd* is the password
412 used for encrypted files as a :class:`bytes` object.
413
414 .. warning::
415
416 Never extract archives from untrusted sources without prior inspection.
417 It is possible that files are created outside of *path*, for example, members
418 that have absolute filenames or filenames with ".." components.
419 This module attempts to prevent that.
420 See :meth:`extract` note.
421
422 .. versionchanged:: 3.6
423 Calling :meth:`extractall` on a closed ZipFile will raise a
424 :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised.
425
426 .. versionchanged:: 3.6.2
427 The *path* parameter accepts a :term:`path-like object`.
428
429
430 .. method:: ZipFile.printdir()
431
432 Print a table of contents for the archive to ``sys.stdout``.
433
434
435 .. method:: ZipFile.setpassword(pwd)
436
437 Set *pwd* (a :class:`bytes` object) as default password to extract encrypted files.
438
439
440 .. method:: ZipFile.read(name, pwd=None)
441
442 Return the bytes of the file *name* in the archive. *name* is the name of the
443 file in the archive, or a :class:`ZipInfo` object. The archive must be open for
444 read or append. *pwd* is the password used for encrypted files as a :class:`bytes`
445 object and, if specified, overrides the default password set with :meth:`setpassword`.
446 Calling :meth:`read` on a ZipFile that uses a compression method other than
447 :const:`ZIP_STORED`, :const:`ZIP_DEFLATED`, :const:`ZIP_BZIP2`,
448 :const:`ZIP_LZMA`, or :const:`ZIP_ZSTANDARD` will raise a
449 :exc:`NotImplementedError`. An error will also be raised if the
450 corresponding compression module is not available.
451
452 .. versionchanged:: 3.6
453 Calling :meth:`read` on a closed ZipFile will raise a :exc:`ValueError`.
454 Previously, a :exc:`RuntimeError` was raised.
455
456
457 .. method:: ZipFile.testzip()
458
459 Read all the files in the archive and check their CRC's and file headers.
460 Return the name of the first bad file, or else return ``None``.
461
462 .. versionchanged:: 3.6
463 Calling :meth:`testzip` on a closed ZipFile will raise a
464 :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised.
465
466
467 .. method:: ZipFile.write(filename, arcname=None, compress_type=None, \
468 compresslevel=None)
469
470 Write the file named *filename* to the archive, giving it the archive name
471 *arcname* (by default, this will be the same as *filename*, but without a drive
472 letter and with leading path separators removed). If given, *compress_type*
473 overrides the value given for the *compression* parameter to the constructor for
474 the new entry. Similarly, *compresslevel* will override the constructor if
475 given.
476 The archive must be open with mode ``'w'``, ``'x'`` or ``'a'``.
477
478 .. note::
479
480 The ZIP file standard historically did not specify a metadata encoding,
481 but strongly recommended CP437 (the original IBM PC encoding) for
482 interoperability. Recent versions allow use of UTF-8 (only). In this
483 module, UTF-8 will automatically be used to write the member names if
484 they contain any non-ASCII characters. It is not possible to write
485 member names in any encoding other than ASCII or UTF-8.
486
487 .. note::
488
489 Archive names should be relative to the archive root, that is, they should not
490 start with a path separator.
491
492 .. note::
493
494 If ``arcname`` (or ``filename``, if ``arcname`` is not given) contains a null
495 byte, the name of the file in the archive will be truncated at the null byte.
496
497 .. note::
498
499 A leading slash in the filename may lead to the archive being impossible to
500 open in some zip programs on Windows systems.
501
502 .. versionchanged:: 3.6
503 Calling :meth:`write` on a ZipFile created with mode ``'r'`` or
504 a closed ZipFile will raise a :exc:`ValueError`. Previously,
505 a :exc:`RuntimeError` was raised.
506
507
508 .. method:: ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, \
509 compresslevel=None)
510
511 Write a file into the archive. The contents is *data*, which may be either
512 a :class:`str` or a :class:`bytes` instance; if it is a :class:`str`,
513 it is encoded as UTF-8 first. *zinfo_or_arcname* is either the file
514 name it will be given in the archive, or a :class:`ZipInfo` instance. If it's
515 an instance, at least the filename, date, and time must be given. If it's a
516 name, the date and time is set to the current date and time.
517 The archive must be opened with mode ``'w'``, ``'x'`` or ``'a'``.
518
519 If given, *compress_type* overrides the value given for the *compression*
520 parameter to the constructor for the new entry, or in the *zinfo_or_arcname*
521 (if that is a :class:`ZipInfo` instance). Similarly, *compresslevel* will
522 override the constructor if given.
523
524 .. note::
525
526 When passing a :class:`ZipInfo` instance as the *zinfo_or_arcname* parameter,
527 the compression method used will be that specified in the *compress_type*
528 member of the given :class:`ZipInfo` instance. By default, the
529 :class:`ZipInfo` constructor sets this member to :const:`ZIP_STORED`.
530
531 .. versionchanged:: 3.2
532 The *compress_type* argument.
533
534 .. versionchanged:: 3.6
535 Calling :meth:`writestr` on a ZipFile created with mode ``'r'`` or
536 a closed ZipFile will raise a :exc:`ValueError`. Previously,
537 a :exc:`RuntimeError` was raised.
538
539 .. versionchanged:: 3.14
540 Now respects the :envvar:`SOURCE_DATE_EPOCH` environment variable.
541 If set, it uses this value as the modification timestamp for the file
542 written into the ZIP archive, instead of using the current time.
543
544 .. method:: ZipFile.mkdir(zinfo_or_directory, mode=511)
545
546 Create a directory inside the archive. If *zinfo_or_directory* is a string,
547 a directory is created inside the archive with the mode that is specified in
548 the *mode* argument. If, however, *zinfo_or_directory* is
549 a :class:`ZipInfo` instance then the *mode* argument is ignored.
550
551 The archive must be opened with mode ``'w'``, ``'x'`` or ``'a'``.
552
553 .. versionadded:: 3.11
554
555
556 The following data attributes are also available:
557
558 .. attribute:: ZipFile.filename
559
560 Name of the ZIP file.
561
562 .. attribute:: ZipFile.debug
563
564 The level of debug output to use. This may be set from ``0`` (the default, no
565 output) to ``3`` (the most output). Debugging information is written to
566 ``sys.stdout``.
567
568 .. attribute:: ZipFile.comment
569
570 The comment associated with the ZIP file as a :class:`bytes` object.
571 If assigning a comment to a
572 :class:`ZipFile` instance created with mode ``'w'``, ``'x'`` or ``'a'``,
573 it should be no longer than 65535 bytes. Comments longer than this will be
574 truncated.
575
576
577 .. _path-objects:
578
579 Path objects
580 ------------
581
582 .. class:: Path(root, at='')
583
584 Construct a Path object from a ``root`` zipfile (which may be a
585 :class:`ZipFile` instance or ``file`` suitable for passing to
586 the :class:`ZipFile` constructor).
587
588 ``at`` specifies the location of this Path within the zipfile,
589 e.g. 'dir/file.txt', 'dir/', or ''. Defaults to the empty string,
590 indicating the root.
591
592 .. note::
593 The :class:`Path` class does not sanitize filenames within the ZIP archive. Unlike
594 the :meth:`ZipFile.extract` and :meth:`ZipFile.extractall` methods, it is the
595 caller's responsibility to validate or sanitize filenames to prevent path traversal
596 vulnerabilities (for example, absolute paths or paths with ".." components). When handling
597 untrusted archives, consider resolving filenames using :func:`os.path.abspath`
598 and checking against the target directory with :func:`os.path.commonpath`.
599
600 Path objects expose the following features of :mod:`pathlib.Path`
601 objects:
602
603 Path objects are traversable using the ``/`` operator or ``joinpath``.
604
605 .. attribute:: Path.name
606
607 The final path component.
608
609 .. method:: Path.open(mode='r', *, pwd, **)
610
611 Invoke :meth:`ZipFile.open` on the current path.
612 Allows opening for read or write, text or binary
613 through supported modes: 'r', 'w', 'rb', 'wb'.
614 Positional and keyword arguments are passed through to
615 :class:`io.TextIOWrapper` when opened as text and
616 ignored otherwise.
617 ``pwd`` is the ``pwd`` parameter to
618 :meth:`ZipFile.open`.
619
620 .. versionchanged:: 3.9
621 Added support for text and binary modes for open. Default
622 mode is now text.
623
624 .. versionchanged:: 3.11.2
625 The ``encoding`` parameter can be supplied as a positional argument
626 without causing a :exc:`TypeError`. As it could in 3.9. Code needing to
627 be compatible with unpatched 3.10 and 3.11 versions must pass all
628 :class:`io.TextIOWrapper` arguments, ``encoding`` included, as keywords.
629
630 .. method:: Path.iterdir()
631
632 Enumerate the children of the current directory.
633
634 .. method:: Path.is_dir()
635
636 Return ``True`` if the current context references a directory.
637
638 .. method:: Path.is_file()
639
640 Return ``True`` if the current context references a file.
641
642 .. method:: Path.is_symlink()
643
644 Return ``True`` if the current context references a symbolic link.
645
646 .. versionadded:: 3.12
647
648 .. versionchanged:: 3.13
649 Previously, ``is_symlink`` would unconditionally return ``False``.
650
651 .. method:: Path.exists()
652
653 Return ``True`` if the current context references a file or
654 directory in the zip file.
655
656 .. data:: Path.suffix
657
658 The last dot-separated portion of the final component, if any.
659 This is commonly called the file extension.
660
661 .. versionadded:: 3.11
662 Added :data:`Path.suffix` property.
663
664 .. data:: Path.stem
665
666 The final path component, without its suffix.
667
668 .. versionadded:: 3.11
669 Added :data:`Path.stem` property.
670
671 .. data:: Path.suffixes
672
673 A list of the path’s suffixes, commonly called file extensions.
674
675 .. versionadded:: 3.11
676 Added :data:`Path.suffixes` property.
677
678 .. method:: Path.read_text(*, **)
679
680 Read the current file as unicode text. Positional and
681 keyword arguments are passed through to
682 :class:`io.TextIOWrapper` (except ``buffer``, which is
683 implied by the context).
684
685 .. versionchanged:: 3.11.2
686 The ``encoding`` parameter can be supplied as a positional argument
687 without causing a :exc:`TypeError`. As it could in 3.9. Code needing to
688 be compatible with unpatched 3.10 and 3.11 versions must pass all
689 :class:`io.TextIOWrapper` arguments, ``encoding`` included, as keywords.
690
691 .. method:: Path.read_bytes()
692
693 Read the current file as bytes.
694
695 .. method:: Path.joinpath(*other)
696
697 Return a new Path object with each of the *other* arguments
698 joined. The following are equivalent::
699
700 >>> Path(...).joinpath('child').joinpath('grandchild')
701 >>> Path(...).joinpath('child', 'grandchild')
702 >>> Path(...) / 'child' / 'grandchild'
703
704 .. versionchanged:: 3.10
705 Prior to 3.10, ``joinpath`` was undocumented and accepted
706 exactly one parameter.
707
708 The :pypi:`zipp` project provides backports
709 of the latest path object functionality to older Pythons. Use
710 ``zipp.Path`` in place of ``zipfile.Path`` for early access to
711 changes.
712
713 .. _pyzipfile-objects:
714
715 PyZipFile objects
716 -----------------
717
718 The :class:`PyZipFile` constructor takes the same parameters as the
719 :class:`ZipFile` constructor, and one additional parameter, *optimize*.
720
721 .. class:: PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, \
722 optimize=-1)
723
724 .. versionchanged:: 3.2
725 Added the *optimize* parameter.
726
727 .. versionchanged:: 3.4
728 ZIP64 extensions are enabled by default.
729
730 Instances have one method in addition to those of :class:`ZipFile` objects:
731
732 .. method:: PyZipFile.writepy(pathname, basename='', filterfunc=None)
733
734 Search for files :file:`\*.py` and add the corresponding file to the
735 archive.
736
737 If the *optimize* parameter to :class:`PyZipFile` was not given or ``-1``,
738 the corresponding file is a :file:`\*.pyc` file, compiling if necessary.
739
740 If the *optimize* parameter to :class:`PyZipFile` was ``0``, ``1`` or
741 ``2``, only files with that optimization level (see :func:`compile`) are
742 added to the archive, compiling if necessary.
743
744 If *pathname* is a file, the filename must end with :file:`.py`, and
745 just the (corresponding :file:`\*.pyc`) file is added at the top level
746 (no path information). If *pathname* is a file that does not end with
747 :file:`.py`, a :exc:`RuntimeError` will be raised. If it is a directory,
748 and the directory is not a package directory, then all the files
749 :file:`\*.pyc` are added at the top level. If the directory is a
750 package directory, then all :file:`\*.pyc` are added under the package
751 name as a file path, and if any subdirectories are package directories,
752 all of these are added recursively in sorted order.
753
754 *basename* is intended for internal use only.
755
756 *filterfunc*, if given, must be a function taking a single string
757 argument. It will be passed each path (including each individual full
758 file path) before it is added to the archive. If *filterfunc* returns a
759 false value, the path will not be added, and if it is a directory its
760 contents will be ignored. For example, if our test files are all either
761 in ``test`` directories or start with the string ``test_``, we can use a
762 *filterfunc* to exclude them::
763
764 >>> zf = PyZipFile('myprog.zip')
765 >>> def notests(s):
766 ... fn = os.path.basename(s)
767 ... return (not (fn == 'test' or fn.startswith('test_')))
768 ...
769 >>> zf.writepy('myprog', filterfunc=notests)
770
771 The :meth:`writepy` method makes archives with file names like
772 this::
773
774 string.pyc # Top level name
775 test/__init__.pyc # Package directory
776 test/testall.pyc # Module test.testall
777 test/bogus/__init__.pyc # Subpackage directory
778 test/bogus/myfile.pyc # Submodule test.bogus.myfile
779
780 .. versionchanged:: 3.4
781 Added the *filterfunc* parameter.
782
783 .. versionchanged:: 3.6.2
784 The *pathname* parameter accepts a :term:`path-like object`.
785
786 .. versionchanged:: 3.7
787 Recursion sorts directory entries.
788
789
790 .. _zipinfo-objects:
791
792 ZipInfo objects
793 ---------------
794
795 Instances of the :class:`ZipInfo` class are returned by the :meth:`.getinfo` and
796 :meth:`.infolist` methods of :class:`ZipFile` objects. Each object stores
797 information about a single member of the ZIP archive.
798
799 There is one classmethod to make a :class:`ZipInfo` instance for a filesystem
800 file:
801
802 .. classmethod:: ZipInfo.from_file(filename, arcname=None, *, \
803 strict_timestamps=True)
804
805 Construct a :class:`ZipInfo` instance for a file on the filesystem, in
806 preparation for adding it to a zip file.
807
808 *filename* should be the path to a file or directory on the filesystem.
809
810 If *arcname* is specified, it is used as the name within the archive.
811 If *arcname* is not specified, the name will be the same as *filename*, but
812 with any drive letter and leading path separators removed.
813
814 The *strict_timestamps* argument, when set to ``False``, allows to
815 zip files older than 1980-01-01 at the cost of setting the
816 timestamp to 1980-01-01.
817 Similar behavior occurs with files newer than 2107-12-31,
818 the timestamp is also set to the limit.
819
820 .. versionadded:: 3.6
821
822 .. versionchanged:: 3.6.2
823 The *filename* parameter accepts a :term:`path-like object`.
824
825 .. versionchanged:: 3.8
826 Added the *strict_timestamps* keyword-only parameter.
827
828
829 Instances have the following methods and attributes:
830
831 .. method:: ZipInfo.is_dir()
832
833 Return ``True`` if this archive member is a directory.
834
835 This uses the entry's name: directories should always end with ``/``.
836
837 .. versionadded:: 3.6
838
839
840 .. attribute:: ZipInfo.filename
841
842 Name of the file in the archive.
843
844
845 .. attribute:: ZipInfo.date_time
846
847 The time and date of the last modification to the archive member. This is a
848 tuple of six values representing the "last [modified] file time" and "last [modified] file date"
849 fields from the ZIP file's central directory.
850
851 The tuple contains:
852
853 +-------+--------------------------+
854 | Index | Value |
855 +=======+==========================+
856 | ``0`` | Year (>= 1980) |
857 +-------+--------------------------+
858 | ``1`` | Month (one-based) |
859 +-------+--------------------------+
860 | ``2`` | Day of month (one-based) |
861 +-------+--------------------------+
862 | ``3`` | Hours (zero-based) |
863 +-------+--------------------------+
864 | ``4`` | Minutes (zero-based) |
865 +-------+--------------------------+
866 | ``5`` | Seconds (zero-based) |
867 +-------+--------------------------+
868
869 .. note::
870
871 The ZIP format supports multiple timestamp fields in different locations
872 (central directory, extra fields for NTFS/UNIX systems, etc.). This attribute
873 specifically returns the timestamp from the central directory. The central
874 directory timestamp format in ZIP files does not support timestamps before
875 1980. While some extra field formats (such as UNIX timestamps) can represent
876 earlier dates, this attribute only returns the central directory timestamp.
877
878 The central directory timestamp is interpreted as representing local
879 time, rather than UTC time, to match the behavior of other zip tools.
880
881
882 .. attribute:: ZipInfo.compress_type
883
884 Type of compression for the archive member.
885
886
887 .. attribute:: ZipInfo.comment
888
889 Comment for the individual archive member as a :class:`bytes` object.
890
891
892 .. attribute:: ZipInfo.extra
893
894 Expansion field data. The `PKZIP Application Note`_ contains
895 some comments on the internal structure of the data contained in this
896 :class:`bytes` object.
897
898
899 .. attribute:: ZipInfo.create_system
900
901 System which created ZIP archive.
902
903
904 .. attribute:: ZipInfo.create_version
905
906 PKZIP version which created ZIP archive.
907
908
909 .. attribute:: ZipInfo.extract_version
910
911 PKZIP version needed to extract archive.
912
913
914 .. attribute:: ZipInfo.reserved
915
916 Must be zero.
917
918
919 .. attribute:: ZipInfo.flag_bits
920
921 ZIP flag bits.
922
923
924 .. attribute:: ZipInfo.volume
925
926 Volume number of file header.
927
928
929 .. attribute:: ZipInfo.internal_attr
930
931 Internal attributes.
932
933
934 .. attribute:: ZipInfo.external_attr
935
936 External file attributes.
937
938
939 .. attribute:: ZipInfo.header_offset
940
941 Byte offset to the file header.
942
943
944 .. attribute:: ZipInfo.CRC
945
946 CRC-32 of the uncompressed file.
947
948
949 .. attribute:: ZipInfo.compress_size
950
951 Size of the compressed data.
952
953
954 .. attribute:: ZipInfo.file_size
955
956 Size of the uncompressed file.
957
958
959 .. _zipfile-commandline:
960 .. program:: zipfile
961
962 Command-line interface
963 ----------------------
964
965 The :mod:`!zipfile` module provides a simple command-line interface to interact
966 with ZIP archives.
967
968 If you want to create a new ZIP archive, specify its name after the :option:`-c`
969 option and then list the filename(s) that should be included:
970
971 .. code-block:: shell-session
972
973 $ python -m zipfile -c monty.zip spam.txt eggs.txt
974
975 Passing a directory is also acceptable:
976
977 .. code-block:: shell-session
978
979 $ python -m zipfile -c monty.zip life-of-brian_1979/
980
981 If you want to extract a ZIP archive into the specified directory, use
982 the :option:`-e` option:
983
984 .. code-block:: shell-session
985
986 $ python -m zipfile -e monty.zip target-dir/
987
988 For a list of the files in a ZIP archive, use the :option:`-l` option:
989
990 .. code-block:: shell-session
991
992 $ python -m zipfile -l monty.zip
993
994
995 Command-line options
996 ~~~~~~~~~~~~~~~~~~~~
997
998 .. option:: -l <zipfile>
999 --list <zipfile>
1000
1001 List files in a zipfile.
1002
1003 .. option:: -c <zipfile> <source1> ... <sourceN>
1004 --create <zipfile> <source1> ... <sourceN>
1005
1006 Create zipfile from source files.
1007
1008 .. option:: -e <zipfile> <output_dir>
1009 --extract <zipfile> <output_dir>
1010
1011 Extract zipfile into target directory.
1012
1013 .. option:: -t <zipfile>
1014 --test <zipfile>
1015
1016 Test whether the zipfile is valid or not.
1017
1018 .. option:: --metadata-encoding <encoding>
1019
1020 Specify encoding of member names for :option:`-l`, :option:`-e` and
1021 :option:`-t`.
1022
1023 .. versionadded:: 3.11
1024
1025
1026 Decompression pitfalls
1027 ----------------------
1028
1029 The extraction in zipfile module might fail due to some pitfalls listed below.
1030
1031 From file itself
1032 ~~~~~~~~~~~~~~~~
1033
1034 Decompression may fail due to incorrect password / CRC checksum / ZIP format or
1035 unsupported compression method / decryption.
1036
1037 File system limitations
1038 ~~~~~~~~~~~~~~~~~~~~~~~
1039
1040 Exceeding limitations on different file systems can cause decompression failed.
1041 Such as allowable characters in the directory entries, length of the file name,
1042 length of the pathname, size of a single file, and number of files, etc.
1043
1044 .. _zipfile-resources-limitations:
1045
1046 Resources limitations
1047 ~~~~~~~~~~~~~~~~~~~~~
1048
1049 The lack of memory or disk volume would lead to decompression
1050 failed. For example, decompression bombs (aka `ZIP bomb`_)
1051 apply to zipfile library that can cause disk volume exhaustion.
1052
1053 Interruption
1054 ~~~~~~~~~~~~
1055
1056 Interruption during the decompression, such as pressing control-C or killing the
1057 decompression process may result in incomplete decompression of the archive.
1058
1059 Default behaviors of extraction
1060 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1061
1062 Not knowing the default extraction behaviors
1063 can cause unexpected decompression results.
1064 For example, when extracting the same archive twice,
1065 it overwrites files without asking.
1066
1067
1068 .. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb
1069 .. _PKZIP Application Note: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT