| 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*, e.g. members |
| 418 |
that have absolute filenames starting with ``"/"`` or filenames with two |
| 419 |
dots ``".."``. 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 (e.g., filenames containing ".." or absolute paths). 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 |