https://github.com/python/cpython/commit/89a3087d40feed3ca78033319389437bb4b... commit: 89a3087d40feed3ca78033319389437bb4b5bcd7 branch: 3.7 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: GitHub <noreply@github.com> date: 2018-11-25T01:30:37-08:00 summary: bpo-32035: Fix words about strings and bytes in zipfile documentation. (GH-10592) (cherry picked from commit 4bb186d7e253ad4def875305e06690181e923dfd) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> files: M Doc/library/zipfile.rst M Lib/zipfile.py diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 7804e92e5374..e1f8b9a4a32a 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -378,13 +378,6 @@ ZipFile Objects given. The archive must be open with mode ``'w'``, ``'x'`` or ``'a'``. - .. note:: - - There is no official file name encoding for ZIP files. If you have unicode file - names, you must convert them to byte strings in your desired encoding before - passing them to :meth:`write`. WinZip interprets all file names as encoded in - CP437, also known as DOS Latin. - .. note:: Archive names should be relative to the archive root, that is, they should not @@ -404,7 +397,9 @@ ZipFile Objects .. 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 + Write a file into the archive. The contents is *data*, which may be either + a :class:`str` or a :class:`bytes` instance; if it is a :class:`str`, + it is encoded as UTF-8 first. *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. @@ -445,11 +440,11 @@ The following data attributes are also available: .. attribute:: ZipFile.comment - The comment text associated with the ZIP file. If assigning a comment to a + The comment associated with the ZIP file as a :class:`bytes` object. + If assigning a comment to a :class:`ZipFile` instance created with mode ``'w'``, ``'x'`` or ``'a'``, - this should be a - string no longer than 65535 bytes. Comments longer than this will be - truncated in the written archive when :meth:`close` is called. + it should be no longer than 65535 bytes. Comments longer than this will be + truncated. .. _pyzipfile-objects: @@ -606,13 +601,14 @@ Instances have the following methods and attributes: .. attribute:: ZipInfo.comment - Comment for the individual archive member. + Comment for the individual archive member as a :class:`bytes` object. .. attribute:: ZipInfo.extra Expansion field data. The `PKZIP Application Note`_ contains - some comments on the internal structure of the data contained in this string. + some comments on the internal structure of the data contained in this + :class:`bytes` object. .. attribute:: ZipInfo.create_system diff --git a/Lib/zipfile.py b/Lib/zipfile.py index a43878575db8..d2d3b693282d 100644 --- a/Lib/zipfile.py +++ b/Lib/zipfile.py @@ -402,7 +402,7 @@ def __repr__(self): return ''.join(result) def FileHeader(self, zip64=None): - """Return the per-file header as a string.""" + """Return the per-file header as a bytes object.""" dt = self.date_time dosdate = (dt[0] - 1980) << 9 | dt[1] << 5 | dt[2] dostime = dt[3] << 11 | dt[4] << 5 | (dt[5] // 2) @@ -1424,7 +1424,7 @@ def comment(self, comment): self._didModify = True def read(self, name, pwd=None): - """Return file bytes (as a string) for name.""" + """Return file bytes for name.""" with self.open(name, "r", pwd) as fp: return fp.read()