classification
Title: Documentation of zipfile.ZipFile().writestr() fails to mention that 'data' may also be bytes
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: CuriousLearner, Daniel5148, docs@python, miss-islington, miss-islington, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2017-11-15 14:54 by Daniel5148, last changed 2018-11-25 10:16 by serhiy.storchaka. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 4698 closed chirag.rathod, 2017-12-04 13:54
PR 4757 closed chirag.rathod, 2017-12-08 11:41
PR 10592 merged serhiy.storchaka, 2018-11-18 19:08
PR 10694 merged miss-islington, 2018-11-25 07:51
PR 10695 merged miss-islington, 2018-11-25 07:52
Messages (5)
msg306271 - (view) Author: Daniel (Daniel5148) Date: 2017-11-15 14:54
The documentation for "ZipFile.writestr(zinfo_or_arcname, data[, compress_type])" says: "Write the string data to the archive; [...]"
--> https://docs.python.org/3/library/zipfile.html

I fails to mention that data could also be bytes.

The source code does mention it however, that is how I found out:

def writestr(self, zinfo_or_arcname, data, compress_type=None):
        """Write a file into the archive.  The contents is 'data', which
        may be either a 'str' or a 'bytes' instance; if it is a 'str',
        it is encoded as UTF-8 first.
        'zinfo_or_arcname' is either a ZipInfo instance or
        the name of the file in the archive."""

I believe this should be added to the documentation as it's an important information to those who try to add non-UTF8 StringIO data to in-memory ZipFiles using BytesIO.
msg330057 - (view) Author: Sanyam Khurana (CuriousLearner) * (Python triager) Date: 2018-11-18 17:45
The change in current PR is very minor and looks good enough that aligns the docs with the docstring and functionality of `ZipFile.writestr` as described.

Can a core-contributor, please look at this?

Also, I'm adding 3.8 for this change.
msg330059 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-11-18 19:11
Since the docstring contains more information, it is better to just copy words from the docstring to the documentation.

There are also other places where string is improperly used instead of bytes or the type is not specified. The note about file name encoding doesn't make sense in Python 3, since ZipFile.write() doesn't support bytes as a file name.

PR 10592 fixed this.
msg330384 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-11-25 07:51
New changeset 4bb186d7e253ad4def875305e06690181e923dfd by Serhiy Storchaka in branch 'master':
bpo-32035: Fix words about strings and bytes in zipfile documentation. (GH-10592)
https://github.com/python/cpython/commit/4bb186d7e253ad4def875305e06690181e923dfd
msg330386 - (view) Author: miss-islington (miss-islington) Date: 2018-11-25 09:30
New changeset af009fbcdb00fffced653792eb7af6b72f2521e3 by Miss Islington (bot) in branch '3.6':
bpo-32035: Fix words about strings and bytes in zipfile documentation. (GH-10592)
https://github.com/python/cpython/commit/af009fbcdb00fffced653792eb7af6b72f2521e3
msg330387 - (view) Author: miss-islington (miss-islington) Date: 2018-11-25 09:30
New changeset 89a3087d40feed3ca78033319389437bb4b5bcd7 by Miss Islington (bot) in branch '3.7':
bpo-32035: Fix words about strings and bytes in zipfile documentation. (GH-10592)
https://github.com/python/cpython/commit/89a3087d40feed3ca78033319389437bb4b5bcd7
History
Date User Action Args
2019-02-06 18:25:03cheryl.sabellalinkissue27344 superseder
2018-11-25 10:16:20serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-11-25 09:30:49miss-islingtonsetnosy: + miss-islington
messages: + msg330387
2018-11-25 09:30:49miss-islingtonsetnosy: + miss-islington
messages: + msg330386
2018-11-25 07:52:02miss-islingtonsetpull_requests: + pull_request9948
2018-11-25 07:51:48miss-islingtonsetpull_requests: + pull_request9947
2018-11-25 07:51:22serhiy.storchakasetmessages: + msg330384
2018-11-18 19:11:19serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg330059
2018-11-18 19:08:59serhiy.storchakasetpull_requests: + pull_request9838
2018-11-18 17:45:32CuriousLearnersetnosy: + CuriousLearner

messages: + msg330057
versions: + Python 3.8
2017-12-08 11:41:44chirag.rathodsetpull_requests: + pull_request4660
2017-12-04 13:54:46chirag.rathodsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request4610
2017-11-15 15:05:45serhiy.storchakasetkeywords: + easy
stage: needs patch
type: enhancement
versions: - Python 3.4, Python 3.5, Python 3.8
2017-11-15 14:54:20Daniel5148create