summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
Diffstat (limited to 'Doc')
-rw-r--r--Doc/library/zipfile.rst44
1 files changed, 32 insertions, 12 deletions
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 5b8c776..d58efe0 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -130,10 +130,12 @@ ZipFile Objects
---------------
-.. class:: ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True)
+.. class:: ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, \
+ compresslevel=None)
Open a ZIP file, where *file* can be a path to a file (a string), a
file-like object or a :term:`path-like object`.
+
The *mode* parameter should be ``'r'`` to read an existing
file, ``'w'`` to truncate and write a new file, ``'a'`` to append to an
existing file, or ``'x'`` to exclusively create and write a new file.
@@ -145,16 +147,27 @@ ZipFile Objects
adding a ZIP archive to another file (such as :file:`python.exe`). If
*mode* is ``'a'`` and the file does not exist at all, it is created.
If *mode* is ``'r'`` or ``'a'``, the file should be seekable.
+
*compression* is the ZIP compression method to use when writing the archive,
and should be :const:`ZIP_STORED`, :const:`ZIP_DEFLATED`,
:const:`ZIP_BZIP2` or :const:`ZIP_LZMA`; unrecognized
- values will cause :exc:`NotImplementedError` to be raised. If :const:`ZIP_DEFLATED`,
- :const:`ZIP_BZIP2` or :const:`ZIP_LZMA` is specified but the corresponding module
- (:mod:`zlib`, :mod:`bz2` or :mod:`lzma`) is not available, :exc:`RuntimeError`
- is raised. The default is :const:`ZIP_STORED`. If *allowZip64* is
- ``True`` (the default) zipfile will create ZIP files that use the ZIP64
- extensions when the zipfile is larger than 4 GiB. If it is false :mod:`zipfile`
- will raise an exception when the ZIP file would require ZIP64 extensions.
+ values will cause :exc:`NotImplementedError` to be raised. If
+ :const:`ZIP_DEFLATED`, :const:`ZIP_BZIP2` or :const:`ZIP_LZMA` is specified
+ but the corresponding module (:mod:`zlib`, :mod:`bz2` or :mod:`lzma`) is not
+ available, :exc:`RuntimeError` is raised. The default is :const:`ZIP_STORED`.
+
+ If *allowZip64* is ``True`` (the default) zipfile will create ZIP files that
+ use the ZIP64 extensions when the zipfile is larger than 4 GiB. If it is
+ ``false`` :mod:`zipfile` will raise an exception when the ZIP file would
+ require ZIP64 extensions.
+
+ The *compresslevel* parameter controls the compression level to use when
+ writing files to the archive.
+ When using :const:`ZIP_STORED` or :const:`ZIP_LZMA` it has no effect.
+ When using :const:`ZIP_DEFLATED` integers ``0`` through ``9`` are accepted
+ (see :class:`zlib <zlib.compressobj>` for more information).
+ When using :const:`ZIP_BZIP2` integers ``1`` through ``9`` are accepted
+ (see :class:`bz2 <bz2.BZ2File>` for more information).
If the file is created with mode ``'w'``, ``'x'`` or ``'a'`` and then
:meth:`closed <close>` without adding any files to the archive, the appropriate
@@ -187,6 +200,9 @@ ZipFile Objects
.. versionchanged:: 3.6.2
The *file* parameter accepts a :term:`path-like object`.
+ .. versionchanged:: 3.7
+ Add the *compresslevel* parameter.
+
.. method:: ZipFile.close()
@@ -351,13 +367,15 @@ ZipFile Objects
:exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised.
-.. method:: ZipFile.write(filename, arcname=None, compress_type=None)
+.. method:: ZipFile.write(filename, arcname=None, compress_type=None, \
+ compresslevel=None)
Write the file named *filename* to the archive, giving it the archive name
*arcname* (by default, this will be the same as *filename*, but without a drive
letter and with leading path separators removed). If given, *compress_type*
overrides the value given for the *compression* parameter to the constructor for
- the new entry.
+ the new entry. Similarly, *compresslevel* will override the constructor if
+ given.
The archive must be open with mode ``'w'``, ``'x'`` or ``'a'``.
.. note::
@@ -383,7 +401,8 @@ ZipFile Objects
a :exc:`RuntimeError` was raised.
-.. method:: ZipFile.writestr(zinfo_or_arcname, data[, compress_type])
+.. method:: ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, \
+ compresslevel=None)
Write the string *data* to the archive; *zinfo_or_arcname* is either the file
name it will be given in the archive, or a :class:`ZipInfo` instance. If it's
@@ -393,7 +412,8 @@ ZipFile Objects
If given, *compress_type* overrides the value given for the *compression*
parameter to the constructor for the new entry, or in the *zinfo_or_arcname*
- (if that is a :class:`ZipInfo` instance).
+ (if that is a :class:`ZipInfo` instance). Similarly, *compresslevel* will
+ override the constructor if given.
.. note::