Uh oh!
There was an error while loading. Please reload this page.
gh-46236: PyUnicode docs improvements - #129966
Conversation
Move Py_UNICODE to a new "Deprecated API" section. Formally soft-deprecate PyUnicode_READY, and move it Document and soft-deprecate PyUnicode_IS_READY, and move it
encukou
commented
Feb 26, 2025
@vstinner@serhiy-storchaka Do these changes look OK to you? |
| .. c:function:: unsigned int PyUnicode_IS_ASCII(PyObject *unicode) | ||
| Return true if the string only contains ASCII characters. |
There was a problem hiding this comment.
| Return true if the string only contains ASCII characters. | |
| Return non-zero if the string only contains ASCII characters. |
There was a problem hiding this comment.
"Return true" is common for such functions (see for example PyUnicode_Check()).
Uh oh!
There was an error while loading. Please reload this page.
serhiy-storchaka
left a comment
There was a problem hiding this comment.
I have a couple of suggestion, but in general LGTM. 👍
Uh oh!
There was an error while loading. Please reload this page.
| .. c:function:: unsigned int PyUnicode_IS_ASCII(PyObject *unicode) | ||
| Return true if the string only contains ASCII characters. |
There was a problem hiding this comment.
"Return true" is common for such functions (see for example PyUnicode_Check()).
| .. c:function:: unsigned int PyUnicode_CHECK_INTERNED(PyObject *str) | ||
| Return a non-zero value if *str* is interned, zero if not. |
There was a problem hiding this comment.
Most documentation uses "Return true" (60 occurrences), some use "Return non-zero" (13 occurrences) and one uses "Return a non-zero".
In this case using "Return a non-zero" looks justified, as it may encode additional information.
Uh oh!
There was an error while loading. Please reload this page.
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
encukou
commented
Feb 28, 2025
Thank you for the reviews! |
While planning to deprecate the
PyASCIIObjectstructs, I found some docs improvements. IMO, these should be applied (and backported) regardless of what happens toPyASCIIObject.Move deprecated PyUnicode API docs to new section
I intend to add more here. IMO, it's good practice to separate deprecated API out like this.
Document PyUnicode_IS_ASCII, PyUnicode_CHECK_INTERNED
PyUnicode_New: Clarify requirements for "fresh" strings
Also, refer to PyUnicode_New wrom all the "writers" for which you need to follow the requirements
PyUnicodeWriter_DecodeUTF8Stateful: Link "error-handlers"
📚 Documentation preview 📚: https://cpython-previews--129966.org.readthedocs.build/