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>

diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 7804e92e5374712123269cb705649600caf0c0c8..e1f8b9a4a32a6ea0d65d252757a5e07b628973fb 100644 (file)
--- 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 a43878575db86ed979bff166c8097f8fd6d1f158..d2d3b693282d3f9d83bb926fccb99c9a677f1a7e 100644 (file)
--- a/Lib/zipfile.py
+++ b/Lib/zipfile.py
@@ -402,7 +402,7 @@ class ZipInfo (object):
         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 @@ class ZipFile:
         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()