diff options
author | Serhiy Storchaka <storchaka@gmail.com> | 2016-09-10 18:28:07 (GMT) |
---|---|---|
committer | Serhiy Storchaka <storchaka@gmail.com> | 2016-09-10 18:28:07 (GMT) |
commit | b0d497c0726c118d40dfadea807b32077f067100 (patch) | |
tree | 4f4d8502ad09d2197f22d0e86b3c2635fe1ce739 /Doc | |
parent | b32e869eb1f63907c54aacf725601d637f1171c1 (diff) | |
download | cpython-b0d497c0726c118d40dfadea807b32077f067100.zip cpython-b0d497c0726c118d40dfadea807b32077f067100.tar.gz cpython-b0d497c0726c118d40dfadea807b32077f067100.tar.bz2 |
Issue #24693: Changed some RuntimeError's in the zipfile module to more
appropriate types. Improved some error messages and debugging output.
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/library/zipfile.rst | 58 |
1 files changed, 43 insertions, 15 deletions
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 6c9d207..4b92e44 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -147,10 +147,10 @@ ZipFile Objects *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:`RuntimeError` to be raised. If :const:`ZIP_DEFLATED`, + 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 also raised. The default is :const:`ZIP_STORED`. If *allowZip64* is + 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 2 GiB. If it is false :mod:`zipfile` will raise an exception when the ZIP file would require ZIP64 extensions. @@ -179,6 +179,10 @@ ZipFile Objects Added support for writing to unseekable streams. Added support for the ``'x'`` mode. + .. versionchanged:: 3.6 + Previously, a plain :exc:`RuntimeError` was raised for unrecognized + compression values. + .. method:: ZipFile.close() @@ -211,7 +215,6 @@ ZipFile Objects can be either the name of a file within the archive or a :class:`ZipInfo` object. The *mode* parameter, if included, must be ``'r'`` (the default) or ``'w'``. *pwd* is the password used to decrypt encrypted ZIP files. - Calling :meth:`.open` on a closed ZipFile will raise a :exc:`RuntimeError`. :meth:`~ZipFile.open` is also a context manager and therefore supports the :keyword:`with` statement:: @@ -230,7 +233,7 @@ ZipFile Objects With ``mode='w'``, a writable file handle is returned, which supports the :meth:`~io.BufferedIOBase.write` method. While a writable file handle is open, attempting to read or write other files in the ZIP file will raise a - :exc:`RuntimeError`. + :exc:`ValueError`. When writing a file, if the file size is not known in advance but may exceed 2 GiB, pass ``force_zip64=True`` to ensure that the header format is @@ -252,6 +255,11 @@ ZipFile Objects :meth:`open` can now be used to write files into the archive with the ``mode='w'`` option. + .. versionchanged:: 3.6 + Calling :meth:`.open` on a closed ZipFile will raise a :exc:`ValueError`. + Previously, a :exc:`RuntimeError` was raised. + + .. method:: ZipFile.extract(member, path=None, pwd=None) Extract a member from the archive to the current working directory; *member* @@ -272,6 +280,10 @@ ZipFile Objects characters (``:``, ``<``, ``>``, ``|``, ``"``, ``?``, and ``*``) replaced by underscore (``_``). + .. versionchanged:: 3.6 + Calling :meth:`extract` on a closed ZipFile will raise a + :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised. + .. method:: ZipFile.extractall(path=None, members=None, pwd=None) @@ -288,6 +300,10 @@ ZipFile Objects dots ``".."``. This module attempts to prevent that. See :meth:`extract` note. + .. versionchanged:: 3.6 + Calling :meth:`extractall` on a closed ZipFile will raise a + :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised. + .. method:: ZipFile.printdir() @@ -305,18 +321,24 @@ ZipFile Objects file in the archive, or a :class:`ZipInfo` object. The archive must be open for read or append. *pwd* is the password used for encrypted files and, if specified, it will override the default password set with :meth:`setpassword`. Calling - :meth:`read` on a closed ZipFile will raise a :exc:`RuntimeError`. Calling :meth:`read` on a ZipFile that uses a compression method other than :const:`ZIP_STORED`, :const:`ZIP_DEFLATED`, :const:`ZIP_BZIP2` or :const:`ZIP_LZMA` will raise a :exc:`NotImplementedError`. An error will also be raised if the corresponding compression module is not available. + .. versionchanged:: 3.6 + Calling :meth:`read` on a closed ZipFile will raise a :exc:`ValueError`. + Previously, a :exc:`RuntimeError` was raised. + .. method:: ZipFile.testzip() Read all the files in the archive and check their CRC's and file headers. - Return the name of the first bad file, or else return ``None``. Calling - :meth:`testzip` on a closed ZipFile will raise a :exc:`RuntimeError`. + Return the name of the first bad file, or else return ``None``. + + .. versionchanged:: 3.6 + Calling :meth:`testfile` on a closed ZipFile will raise a + :exc:`ValueError`. Previously, a :exc:`RuntimeError` was raised. .. method:: ZipFile.write(filename, arcname=None, compress_type=None) @@ -326,10 +348,7 @@ ZipFile Objects 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 archive must be open with mode ``'w'``, ``'x'`` or ``'a'`` -- calling - :meth:`write` on a ZipFile created with mode ``'r'`` will raise a - :exc:`RuntimeError`. Calling :meth:`write` on a closed ZipFile will raise a - :exc:`RuntimeError`. + The archive must be open with mode ``'w'``, ``'x'`` or ``'a'``. .. note:: @@ -348,16 +367,19 @@ ZipFile Objects If ``arcname`` (or ``filename``, if ``arcname`` is not given) contains a null byte, the name of the file in the archive will be truncated at the null byte. + .. versionchanged:: 3.6 + Calling :meth:`write` on a ZipFile created with mode ``'r'`` or + a closed ZipFile will raise a :exc:`ValueError`. Previously, + a :exc:`RuntimeError` was raised. + + .. method:: ZipFile.writestr(zinfo_or_arcname, data[, compress_type]) 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 an instance, at least the filename, date, and time must be given. If it's a name, the date and time is set to the current date and time. - The archive must be opened with mode ``'w'``, ``'x'`` or ``'a'`` -- calling - :meth:`writestr` on a ZipFile created with mode ``'r'`` will raise a - :exc:`RuntimeError`. Calling :meth:`writestr` on a closed ZipFile will - raise a :exc:`RuntimeError`. + The archive must be opened with mode ``'w'``, ``'x'`` or ``'a'``. 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* @@ -373,6 +395,12 @@ ZipFile Objects .. versionchanged:: 3.2 The *compress_type* argument. + .. versionchanged:: 3.6 + Calling :meth:`writestr` on a ZipFile created with mode ``'r'`` or + a closed ZipFile will raise a :exc:`ValueError`. Previously, + a :exc:`RuntimeError` was raised. + + The following data attributes are also available: |