[docs] [issue19548] 'codecs' module docs improvements

[Martin Panter]

Martin Panter added the comment:

Here is a patch addressing many of the points raised. Please have a look and give any feedback. Beware I am not very familiar with the Restructured Text markup and haven’t tried compiling it.

1. Mentioned bytes-to-bytes and text-to-text in general right at the top. Any APIs (e.g. see Issue 20132) that don't support them should be pointed out as exceptions to the rule.

8. The underlying mode is forced to binary, so 'r' is the same as 'rb'. I removed the 'b' from the signature for clarity.

## Jan’s points not yet addressed: ##

3. I expect the built-in open() function would already be much more obvious and advertised, so I didn't add any cross-reference from codecs.open().

5. Both points still need addressing:
  * Lack of requirement for implementing incremental codecs
  * Responsibility of implementing error handlers

9. First point left unaddressed:
  * register_error() error_handler replacement data type (unsure of details)

## Numbering Nick’s points: ##

12. Codec name normalization: Not addressed; what should be written?

[13. Registration not reversible: Added in patch]

[14. Added CodecInfo class, pulling out some existing details from register().]

15. “encodings” module: not done

16. Import system: not done

## My (Martin’s) point: ##

[17. IncrementalEncoder.reset(): done]

## Zoinkity’s points, not addressed: ##

18. Multibyte codecs

19. register() usage example

## Some new points of my own that need fixing: ##

20. The doc string for register() says the search function is also allowed to return a tuple of functions, but the reference manual does not mention this. Which is more accurate? (I notice CodecInfo is a subclass of “tuple”.)

21. EncodedFile() seems to return StreamRecoder instances. Perhaps move them closer together? Should probably warn that EncodedFile's data_encoding is handled by a stateless codec.

22. The Codec.encode() and decode() methods return a length consumed, but I suspect they have to consume everything they are supplied because the code I have seen ignores this return value.

----------
keywords: +patch
Added file: http://bugs.python.org/file37485/codecs-doc.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue19548>
_______________________________________