codecs.charmap_build is untested and undocumented

[fijal]

BPO	3931
Nosy	@malemburg, @loewis, @birkenfeld, @terryjreedy, @merwok, @MojoVampire

^{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 2008-09-22.12:06:14.954>
labels = ['type-bug', 'library', 'docs']
title = 'codecs.charmap_build is untested and undocumented'
updated_at = <Date 2019-03-15.22:35:04.722>
user = 'https://bugs.python.org/fijal'

bugs.python.org fields:

activity = <Date 2019-03-15.22:35:04.722>
actor = 'BreamoreBoy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2008-09-22.12:06:14.954>
creator = 'fijal'
dependencies = []
files = []
hgrepos = []
issue_num = 3931
keywords = []
message_count = 7.0
messages = ['73569', '75012', '112747', '120987', '220400', '220407', '237006']
nosy_count = 7.0
nosy_names = ['lemburg', 'loewis', 'georg.brandl', 'terry.reedy', 'fijal', 'eric.araujo', 'josh.r']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue3931'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

Linked PRs

• gh-48181: Document codecs.charmap_build #135997

[fijal]

Although it doesn't start with _ and is definitely necessary as codecs
call it.

[malemburg]

AFAIR, this code was added by Martin as optimization.

The function is a direct interface to PyUnicode_BuildEncodingMap() which
builds either a dictionary or EncodingMap object for use by the charmap
codec.

It is primarily used by the gencodec.py script.

[terryjreedy]

There are numerous undocumented implementation objects that are either private and probably should start with _ but do not, or are semi-private and perhaps left public for the expert user willing to read code. But, being undocumented, it is hard to tell. codecs.charmap_build strikes me as rather private, hence should not be documented. So I would be inclined to close this.

[merwok]

I see charmap_build used in encodings too, so it may be useful to make it officially public for the use of third-party encodings.

[BreamoreBoy]

msg120987 states the opposite to msg112747 so what do we do with this issue?

[MojoVampire]

I've found it rather ugly to even understand from the lack of code comments for the C level API it's wrapping. If nothing else, comments explaining the usage and purpose might be helpful.

[BreamoreBoy]

I do not see much purpose in documenting and testing this one function alone. I think that all functions in _codecsmodule.c should be looked at to see if they are private or public, but I'm certainly not volunteering to do it.