Documentation for email.charset confusing about the location of constants

[FrancoisLabelle]

BPO	33449
Nosy	@bitdancer

^{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 = None
created_at = <Date 2018-05-09.17:38:58.133>
labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
title = 'Documentation for email.charset confusing about the location of constants'
updated_at = <Date 2021-12-19.00:41:56.401>
user = 'https://bugs.python.org/FrancoisLabelle'

bugs.python.org fields:

activity = <Date 2021-12-19.00:41:56.401>
actor = 'AlexWaygood'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-05-09.17:38:58.133>
creator = 'Francois Labelle'
dependencies = []
files = []
hgrepos = []
issue_num = 33449
keywords = []
message_count = 4.0
messages = ['316327', '316364', '316374', '316378']
nosy_count = 3.0
nosy_names = ['r.david.murray', 'docs@python', 'quantum.omega']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue33449'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[FrancoisLabelle]

When mentioning the constants contained in the module email.charset, the documentation prefixes them with "Charset", for example: Charset.QP, Charset.BASE64, Charset.SHORTEST. This suggests that the constants can be found on the class "Charset" (uppercase first letter) in the module, while they are in fact contained in the the "charset" (lowercase first letter) module itself.

This is probably a left-over from when the module was called email.Charset (in 2.2 I believe). Under Python 2.7, while the documentation uses the same nomenclature, at least the module is also importable under the name email.Charset so it makes more sense.

[bitdancer]

Can you provide an example of where this occurs in the docs?

[quantumomega]

Original poster here (OpenID just wouldn't work anymore).

For instance: https://docs.python.org/2/library/email.charset.html

Under "class email.charset.Charset"

Under "header_encoding"

"If the character set must be encoded before it can be used in an email header, this attribute will be set to Charset.QP (for quoted-printable), Charset.BASE64 (for base64 encoding), or Charset.SHORTEST for the shortest of QP or BASE64 encoding. Otherwise, it will be None."

[bitdancer]

Ah, I see. Yes, those strings are actually hardcoded in the documentation source instead of being references. You are correct, they should be fixed. Note, however, that Charset is part of the legacy API and isn't actually used if you use the new API in python3.