Description

jayaddison

opened on Dec 4, 2022

Issue body actions

Documentation

The are a couple of paragraphs about error-checking behaviour for str.encode and str.decode that appears in a few versions of Python and could potentially be improved in future versions.

As found in the Python 3.9.14 documentation for std.encode:

By default, the errors argument is not checked for best performances, but only used at the first encoding error. Enable the Python Development Mode, or use a debug build to check errors.

The paragraph before that is fairly dense - there could be an opportunity to improve both of them.

Linked PRs

• gh-99991: improve docs on str.encode and bytes.decode #100198
• [3.11] gh-99991: improve docs on str.encode and bytes.decode (GH-100198) #100382
• [3.10] gh-99991: improve docs on str.encode and bytes.decode (GH-100198) #100383

Activity

1. jayaddison

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Dec 4, 2022
2. bizzyvinci commented on Dec 9, 2022

   

   bizzyvinci

   on Dec 9, 2022

   Contributor

   More actions

   do you have recommendations on how to improve them
3. jayaddison commented on Dec 9, 2022

   

   jayaddison

   on Dec 9, 2022

   Author

   More actions

   It's not easy, but I'll try - here's an attempt for str.encode:

   str.encode(encoding="utf-8", errors="strict")

   Return a bytes object containing the string in the requested encoding.

   The default strict error handling raises a UnicodeError exception when an encoding error occurs. Other possible values include ignore, replace, xmlcharrefreplace, backslashreplace and any other name registered via codecs.register_error(), see section Error Handlers.

   For a list of possible encodings, see section Standard Encodings.

   For performance reasons, the value of the errors argument is not checked for validity unless Python Development Mode is enabled.

   Process used
   Thinking like refactoring, the important items to maintain (like creating unit tests) seemed to be:

   • That the documentation describes what the method does (encodes a string, handles errors)
   • That relevant entities are hyperlinked/emphasized
   • That the documentation is relatively concise (the time required to read and understand the description is similar or reduced)

   So looking at the text, there seemed to be a few steps to refactor it:

   • Break the dense paragraph into individual statements (usually individual sentences)
   • Apply consistent emphasis to entities (types, arguments, ...) that appear in the statements
   • Remove redundant/self-explanatory statements
   • It's a 2-argument method -- and each argument requires explanation -- so consolidate the statements into one paragraph per argument:
     • Move sentences describing encoding into the first paragraph
     • Move sentences describing errors into the second paragraph
     • Exception: some of the commentary appears to be about non-functional behaviour (performance) -- OK, that could move into a third paragraph
   • Re-read and refactor to remove unnecessary words and statements
   • Nitpick: error handling is important to understand, so let's move the list of codecs -- useful though it is -- to after the errors argument, in the hope that people will read about error-handling first

   Note:

   • https://docs.python.org/3.9/library/codecs.html#codecs.EncodedFile also has documentation for a similarly-behaved errors argument
4. bizzyvinci commented on Dec 9, 2022

   

   bizzyvinci

   on Dec 9, 2022

   Contributor

   More actions

   Thanks. I'll work on that.

   Reacted by James Addison
5. jayaddison commented on Dec 10, 2022

   

   jayaddison

   on Dec 10, 2022

   Author

   More actions

   For performance reasons, the value of the errors argument is not checked for validity unless Python Development Mode is enabled.

   Ah: I forgot to mention debug builds in this suggestion. Similar to development-mode, debug builds also validate the errors argument.

   A simple check to test whether error-handler-name-validation is enabled is to attempt encoding using an invalid error-handler-name. For example, "".encode('utf-8', errors='gh-99991').
6. CAM-Gerlach commented on Dec 16, 2022

   

   CAM-Gerlach

   on Dec 16, 2022

   Member

   More actions

   By the way, thanks for your comprehensive and insightful feedback, @jayaddison ! We'd love to have more of it elsewhere, and you're welcome to contribute the changes yourself if you like—you seem to have quite a knack for documentation writing, which makes a big positive impact on the community. Thanks again!

   Reacted by James Addison
7. jayaddison commented on Dec 16, 2022

   

   jayaddison

   on Dec 16, 2022

   Author

   More actions

   Thanks for the kind words @CAM-Gerlach! There are more than a few similarities between good code and good documentation, I think 😄 I'll do my best to help out where and when I can.

   Reacted by C.A.M. Gerlach
8. JelleZijlstra

   added a commit that references this issue on Dec 21, 2022

   gh-99991: improve docs on str.encode and bytes.decode (#100198)

   a2bb3b7
9. miss-islington

   added 4 commits that reference this issue on Dec 21, 2022

   pythongh-99991: improve docs on str.encode and bytes.decode (pythonGH…

   acbf2ac

   pythongh-99991: improve docs on str.encode and bytes.decode (pythonGH…

   0e2f5e7

   gh-99991: improve docs on str.encode and bytes.decode (GH-100198)

   b3d39c7

   gh-99991: improve docs on str.encode and bytes.decode (GH-100198)

   23fa166
10. hauntsaninja commented on Dec 21, 2022

    

    hauntsaninja

    on Dec 21, 2022

    Contributor

    More actions

    Thanks, looks like everything is merged!

    Reacted by James Addison and Bisola Olasehinde

    Reacted by James Addison
11. hauntsaninja

    closed this as completedon Dec 21, 2022
12. iritkatriel

    added a commit that references this issue on Dec 28, 2022

    Merged main into regmachine branch (#50)

    fdc73cb

Issue actions