classification
Title: imaplib: wrong return type documented
Type: Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: corona10, docs@python, eric.smith, miss-islington, norbertcyran
Priority: normal Keywords: newcomer friendly, patch

Created on 2020-08-31 09:41 by norbertcyran, last changed 2020-09-12 11:05 by corona10. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 22207 merged norbertcyran, 2020-09-11 23:26
PR 22217 merged miss-islington, 2020-09-12 07:59
PR 22218 merged miss-islington, 2020-09-12 07:59
Messages (11)
msg376143 - (view) Author: Norbert Cyran (norbertcyran) * Date: 2020-08-31 09:41
Documentation on IMAP4 class specifies wrong return type of its commands:

    Each command returns a tuple: (type, [data, ...]) where type is 
    usually 'OK' or 'NO', and data is either the text from the command 
    response, or mandated results from the command. Each data is either a 
    string, or a tuple. If a tuple, then the first part is the header of 
    the response, and the second part contains the data (ie: ‘literal’ 
    value).

That's not valid for Python 3, as IMAP4 commands return bytes-like objects in data, what's shown in the example before::
  >>> from imaplib import IMAP4
  >>> with IMAP4("domain.org") as M:
  ...     M.noop()
  ...
  ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

That of course can cause a lot of trouble due to incompatibility of strings and bytes. Suggested change is to replace string occurences to bytes-like object. I don't know what types are returned in case when tuple is returned though.
msg376304 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-09-03 14:31
@eric

What do you think about?
msg376331 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-09-03 23:15
For the case of returning a list of non-tuples, all of my code assumes bytes, so I think changing the docs to say bytes is good. "bytes-like" might be overkill. Unfortunately, I don't know enough to say what encoding is returned: I just assume utf-8, although everything I'm using is probably ascii.

My code doesn't handle any case where a list of tuples is returned, so I can't really comment on that.
msg376458 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-09-06 05:09
@norbertcyran

Do you want to sand a patch that it update string to byte for this documentation?
msg376466 - (view) Author: Norbert Cyran (norbertcyran) * Date: 2020-09-06 16:39
@ericsmith

Sure, I can create a PR and link it here when I'm done.
msg376671 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-09-10 04:41
Please ping me when you submit the PR
msg376750 - (view) Author: Norbert Cyran (norbertcyran) * Date: 2020-09-11 23:28
@corona10 PR added: https://github.com/python/cpython/pull/22207
msg376792 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-09-12 07:59
New changeset c75330605d4795850ec74fdc4d69aa5d92f76c00 by Norbert Cyran in branch 'master':
bpo-41672: Fix type mismatches in imaplib docs (GH-22207)
https://github.com/python/cpython/commit/c75330605d4795850ec74fdc4d69aa5d92f76c00
msg376793 - (view) Author: miss-islington (miss-islington) Date: 2020-09-12 08:14
New changeset 98f6e67a3d6e57727177ec2fb5cb68ef9a468aca by Miss Islington (bot) in branch '3.9':
bpo-41672: Fix type mismatches in imaplib docs (GH-22207)
https://github.com/python/cpython/commit/98f6e67a3d6e57727177ec2fb5cb68ef9a468aca
msg376799 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-09-12 11:04
New changeset 3a150c77c31da240f1b92cab9ec74f1fa701b869 by Miss Islington (bot) in branch '3.8':
bpo-41672: Fix type mismatches in imaplib docs (GH-22207) (#22218)
https://github.com/python/cpython/commit/3a150c77c31da240f1b92cab9ec74f1fa701b869
msg376800 - (view) Author: Dong-hee Na (corona10) * (Python committer) Date: 2020-09-12 11:05
Thanks Norbert for the contribution!
History
Date User Action Args
2020-09-12 11:05:47corona10setstatus: open -> closed
resolution: fixed
messages: + msg376800

stage: patch review -> resolved
2020-09-12 11:04:53corona10setmessages: + msg376799
2020-09-12 08:14:41miss-islingtonsetmessages: + msg376793
2020-09-12 07:59:43corona10setversions: - Python 3.5, Python 3.6, Python 3.7
2020-09-12 07:59:20miss-islingtonsetpull_requests: + pull_request21273
2020-09-12 07:59:13miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request21272
2020-09-12 07:59:04corona10setmessages: + msg376792
2020-09-11 23:28:32norbertcyransetmessages: + msg376750
2020-09-11 23:26:33norbertcyransetkeywords: + patch
stage: patch review
pull_requests: + pull_request21261
2020-09-10 04:41:33corona10setmessages: + msg376671
2020-09-06 16:39:06norbertcyransetmessages: + msg376466
2020-09-06 05:09:24corona10setkeywords: + newcomer friendly

messages: + msg376458
2020-09-03 23:15:21eric.smithsetmessages: + msg376331
2020-09-03 14:31:00corona10setnosy: + eric.smith, corona10
messages: + msg376304
2020-08-31 09:41:11norbertcyrancreate