Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Overhaul Error Handlers section in codecs documentation #82237

Closed
animalize mannequin opened this issue Sep 8, 2019 · 3 comments
Closed

Overhaul Error Handlers section in codecs documentation #82237

animalize mannequin opened this issue Sep 8, 2019 · 3 comments
Assignees
@JelleZijlstra
Labels
3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes docs Documentation in the Doc dir topic-unicode

Comments

@animalize
Copy link
Mannequin

animalize mannequin commented Sep 8, 2019

BPO 38056
Nosy @vstinner, @ezio-melotti, @animalize
PRs
  • bpo-38056: overhaul Error Handlers section in codecs documentation #15732
    		•
    Files
  • effect.png
    		•

    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 2019-09-08.14:14:30.087>
labels = ['3.7', '3.8', '3.9', 'expert-unicode', 'docs']
title = 'Overhaul Error Handlers section in codecs documentation'
updated_at = <Date 2019-10-13.03:14:27.838>
user = 'https://github.com/animalize'

    bugs.python.org fields:

    activity = <Date 2019-10-13.03:14:27.838>
actor = 'malin'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Unicode']
creation = <Date 2019-09-08.14:14:30.087>
creator = 'malin'
dependencies = []
files = ['48599']
hgrepos = []
issue_num = 38056
keywords = ['patch']
message_count = 2.0
messages = ['351329', '354564']
nosy_count = 4.0
nosy_names = ['vstinner', 'ezio.melotti', 'docs@python', 'malin']
pr_nums = ['15732']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue38056'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']
    @animalize
    Copy link
    Mannequin Author

    animalize mannequin commented Sep 8, 2019

    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+00DF
    ♬ https://www.compart.com/en/unicode/U+266C

    @animalize animalize mannequin added 3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes labels Sep 8, 2019
    @animalize animalize mannequin assigned docspython Sep 8, 2019
    @animalize animalize mannequin added the docs Documentation in the Doc dir label Sep 8, 2019
    @animalize
    Copy link
    Mannequin Author

    animalize mannequin commented Oct 13, 2019

    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.

    @animalize animalize mannequin added the topic-unicode label Oct 13, 2019
    @animalize animalize mannequin changed the title Add examples for common text encoding Error Handlers Overhaul Error Handlers section in codecs documentation Oct 13, 2019
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @JelleZijlstra JelleZijlstra self-assigned this May 8, 2022
    @JelleZijlstra
    Copy link
    Member

    PRs were merged, thanks for your contribution!

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees

    @JelleZijlstra JelleZijlstra

    Labels
    3.7 (EOL) end of life 3.8 only security fixes 3.9 only security fixes docs Documentation in the Doc dir topic-unicode
    Projects
    Codecs and encodings issues
    Status: Done
    Milestone
    No milestone
    Development

    No branches or pull requests
    1 participant
    @JelleZijlstra