email.header.decode_header return type is not consistent

[SebastianKreft]

BPO	24797
Nosy	@warsaw, @bitdancer
Superseder	bpo-21492: email.header.decode_header sometimes returns bytes, sometimes str

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2015-08-05.15:49:44.577>
created_at = <Date 2015-08-05.15:18:45.131>
labels = ['type-bug', 'expert-email']
title = 'email.header.decode_header return type is not consistent'
updated_at = <Date 2015-08-17.16:10:37.946>
user = 'https://bugs.python.org/SebastianKreft'

bugs.python.org fields:

activity = <Date 2015-08-17.16:10:37.946>
actor = 'r.david.murray'
assignee = 'none'
closed = True
closed_date = <Date 2015-08-05.15:49:44.577>
closer = 'r.david.murray'
components = ['email']
creation = <Date 2015-08-05.15:18:45.131>
creator = 'Sebastian Kreft'
dependencies = []
files = []
hgrepos = []
issue_num = 24797
keywords = []
message_count = 4.0
messages = ['248047', '248049', '248734', '248735']
nosy_count = 3.0
nosy_names = ['barry', 'r.david.murray', 'Sebastian Kreft']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '21492'
type = 'behavior'
url = 'https://bugs.python.org/issue24797'
versions = ['Python 3.4', 'Python 3.5', 'Python 3.6']

[SebastianKreft]

The return type of email.header.decode_header is not consistent. When there are encoded parts the return type is a list of (bytes, charset or None) (Note that the documentation says it is a list of (str, charset)). However, when there are no encoded parts the return type is [(str, None)]. Note that, at the end of the function, there is a routine that converts everything to bytes.

Compare:
In [01]: email.header.decode_header('=?UTF-8?Q?foo?=bar')
Out[01]: [(b'foo', 'utf-8'), (b'bar', None)]

In [02]: email.header.decode_header('foobar')
Out[02]: [('foobar', None)]

[bitdancer]

Yeah, don't use that, use the new APIs.

[SebastianKreft]

And what would the new API be?

There is nothing pointing to it either in the documentation https://docs.python.org/3.4/library/email.header.html or source code.

[bitdancer]

Right, it's provisional in 3.4. I'm working on the doc rewrite now (although I suppose there's a chance it won't get accepted for 3.5, I expect it to).

Take a look at https://docs.python.org/3/library/email.policy.html. Basically, if you use EmailMessage instead of Message (and therefore policy.default instead of policy.compat32) header parsing and decoding is handled for you.