classification
Title: Overhaul Error Handlers section in codecs documentation
Type: Stage: patch review
Components: Documentation, Unicode Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ma Lin, docs@python, ezio.melotti, vstinner
Priority: normal Keywords: patch

Created on 2019-09-08 14:14 by Ma Lin, last changed 2019-10-13 03:14 by Ma Lin.

Files
File name Uploaded Description Edit
effect.png Ma Lin, 2019-09-08 14:14
Pull Requests
URL Status Linked Edit
PR 15732 open Ma Lin, 2019-09-08 14:16
Messages (2)
msg351329 - (view) Author: Ma Lin (Ma Lin) * Date: 2019-09-08 14:14
Text descriptions about `Error Handlers` are not very friendly to novices.
https://docs.python.org/3/library/codecs.html#error-handlers

For example:

    'xmlcharrefreplace'
    Replace with the appropriate XML character reference (only for encoding).  Implemented in :func:`xmlcharrefreplace_errors`. 

    'backslashreplace'
    Replace with backslashed escape sequences. Implemented in :func:`backslashreplace_errors`.

    'namereplace'
    Replace with ``\N{...}`` escape sequences (only for encoding).  Implemented in :func:`namereplace_errors`.

Novices may not know what these are.
Giving some examples may help the reader to understand more intuitively.
The effect picture is attached.

I picked two characters:
ß  https://www.compart.com/en/unicode/U+00DFhttps://www.compart.com/en/unicode/U+266C
msg354564 - (view) Author: Ma Lin (Ma Lin) * Date: 2019-10-13 03:14
PR 15732 became an overhaul:

- replace/backslashreplace/surrogateescape were wrongly described as encoding only, in fact they can also be used in decoding.
- clarify the description of surrogatepass.
- add more descriptions to each handler.
- add two REPL examples.
- add indexes for Error Handler's name.
- add default parameter values in codecs.rst
- improve term "text encoding".

PR 15732 has a screenshot of the Error Handlers section.
History
Date User Action Args
2019-10-13 03:14:27Ma Linsettitle: Add examples for common text encoding Error Handlers -> Overhaul Error Handlers section in codecs documentation
nosy: + ezio.melotti, vstinner

messages: + msg354564

components: + Unicode
2019-09-08 14:16:34Ma Linsetkeywords: + patch
stage: patch review
pull_requests: + pull_request15386
2019-09-08 14:14:30Ma Lincreate