bpo-37864: Correct and deduplicate "isprintable" docs; add test. #15300
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
We had the definition of what makes a character "printable" documented in three places, giving two different definitions. The definition in the comment on `_PyUnicode_IsPrintable` was inverted; correct that. With that correction, the two definitions turn out to be equivalent -- but to confirm that, you have to go look up, or happen to know, that those are the only five "Other" categories and only three "Separator" categories in the Unicode character database. That makes it hard for the reader to tell whether they really are the same, or if there's some subtle difference in the intended semantics. Fix that by cutting the C API docs' and the C comment's copies of the subtle details, in favor of referring to the Python-level docs. That ensures it's explicit that these are all meant to agree, and also lets us concentrate improvements to the wording in one place. Speaking of which, borrow some ideas from the C comment, along with other tweaks, to hopefully add a bit more clarity to that one newly-centralized copy in the docs. Also add a thorough test that the implementation agrees with this definition.
|
"Generated files not up to date I believe you have to regenerate these files and include the new versions in the branch and the new diffs in this PR. If 'how' is not in the devguide, ask on core-mentorship list. |
|
@terryjreedy Ah, thanks for spotting that! Indeed, |
|
(I also just added a NEWS entry, which should turn that red X into a happy green check-mark.) |
|
Merged in #130118, with another regen-all. Sorry for the wait! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
We had the definition of what makes a character "printable"
documented in three places, giving two different definitions.
The definition in the comment on
_PyUnicode_IsPrintablewasinverted; correct that.
With that correction, the two definitions turn out to be equivalent --
but to confirm that, you have to go look up, or happen to know, that
those are the only five "Other" categories and only three "Separator"
categories in the Unicode character database. That makes it hard for
the reader to tell whether they really are the same, or if there's
some subtle difference in the intended semantics.
Fix that by cutting the C API docs' and the C comment's copies of
the subtle details, in favor of referring to the Python-level docs.
That ensures it's explicit that these are all meant to agree, and
also lets us concentrate improvements to the wording in one place.
Speaking of which, borrow some ideas from the C comment, along with
other tweaks, to hopefully add a bit more clarity to that one
newly-centralized copy in the docs.
Also add a thorough test that the implementation agrees with
this definition.
https://bugs.python.org/issue37864