On 28.11.2016 12:24, Serhiy Storchaka wrote:
>> Why are you removing the introductory section on how mappings work ?
> 
> Because it is not correct. I copied it to descriptions of concrete functions with correcting it according to the peculiarity of particular function.

The only part that is not correct is "single string characters".
This should read "single bytes" or "bytes strings of length 1".

I also don't see where you copied the description. Without some
description of what "mappings" are in the context of the charmap
codec, it's not easy to understand what the purpose of these
APIs is. Please just fix the bytes wording instead of removing the
whole intro.

>> Also, this wording needs to be corrected: "bytes (integers in the range from 0 to 255)". Bytes are not integers. I'd suggest to use the more correct wording "bytes strings of length 1".
> 
> The word "bytes" means here not Python bytes object, but is used in more common meaning: an integer in the range from 0 to 255.

That's confusing, since we use the term "bytes" as referring
to the bytes object in Python. Please use "integers in the range
0-255".

Aside: The deprecation of PyUnicode_EncodeCharmap() also seems misplaced
in this context, since only the Py_UNICODE version of the API is
deprecated. The functionality still exists and is useful. An API
similar to the _PyUnicode_EncodeCharmap() API should be made publicly
available to accommodate for the deprecation, since the mentioned
PyUnicode_AsCharmapString() and PyUnicode_AsEncodedString()
APIs are not suitable as replacement. PyUnicode_AsCharmapString()
doesn't support error handling (strange, BTW) and
PyUnicode_AsEncodedString() has a completely unrelated meaning (no
idea why it's mentioned here at all).