[issue18697] Unify arguments names in Unicode object C API documentation
New submission from Serhiy Storchaka: In declarations of Unicode object C API functions in Doc/c-api/unicode.rst the first Unicode object argument has different names: "unicode", "str", "u", "s". It will be good to unify these names. Of course there is no need to change reasonable argument names for such functions as PyUnicode_Concat() or PyUnicode_CopyCharacters(). ---------- assignee: docs@python components: Documentation, Unicode keywords: easy messages: 194755 nosy: docs@python, ezio.melotti, haypo, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Unify arguments names in Unicode object C API documentation type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Mark Lawrence added the comment: @Serhiy will you be proposing a patch for this? ---------- nosy: +BreamoreBoy versions: +Python 3.5 -Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Serhiy Storchaka added the comment:
@Serhiy will you be proposing a patch for this?
No, I am not. I have no opinion what name is better. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Serhiy Storchaka added the comment: The same issue exists for other types. E.g. PyLong_* functions have Python long argument named as p, obj and pylong, PyFloat_* -- p and pyfloat, PyList_* -- p and list, PyDict_* -- p, a and mapping, PyBytes_* -- o, obj, string and bytes. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Matheus Vieira Portela added the comment: Just checking, it would be required to update Objects/unicodeobject.c, Include/unicodeobject.h, and Doc/c-api/unicode.rst, right? As far as I saw, "unicode" means a Python object with unicode string, "u" is a UTF-8 encoded C string, "str" and "s" are encoded C strings (UTF-8, UTF-7, ASCII, Latin-1, among others). Is it alright to rename Python unicode objects to "unicode" and the others to simply "str"? These names are more meaningful than the single character alternatives. The same logic would be applied to the other types, always keeping the longer name rather than the single character ones. ---------- nosy: +matheus.v.portela _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Windson Yang <wiwindson@outlook.com> added the comment: I agreed with @Matheus, it would be better than the current implementation ---------- nosy: +Windson Yang versions: +Python 3.6, Python 3.7 -Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Windson Yang <wiwindson@outlook.com>: ---------- versions: +Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Windson Yang <wiwindson@outlook.com>: ---------- versions: -Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Rune Tynan <runetynan@gmail.com>: ---------- nosy: +Rune Tynan _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Rune Tynan <runetynan@gmail.com> added the comment: I have some interest in making a fix for this. From discussion, I'm thinking that, barring names that already have clear meaning (EG, left/right for things with two parameters): - PyObject* that is unknown type remains `obj` - PyObject* with unicode string is `unicode` - const char*, const Py_UNICODE*, and const wchar* becomes `str` - const char, const Py_UNICODE, and const wchar become `ch` Those seem to be the intersect of most common and most descriptive names already seen. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Rune Tynan <runetynan@gmail.com> added the comment: Another inconsistency I've noticed is that the code sometimes refers to Py_ssize_t instances as a 'length' and sometimes as a 'size'. It seems like 'size' is the more common one in the docs, but the headers more often use 'length'. Which would be the better one to keep for the common case? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Rune Tynan <runetynan@gmail.com>: ---------- keywords: +patch pull_requests: +12607 stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by STINNER Victor <vstinner@redhat.com>: ---------- nosy: -vstinner _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Rune Tynan <runetynan@gmail.com> added the comment: It has been over a month and I'm still waiting for an updated PR review. I understand if people are busy, but don't want this to just fall through the cracks. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Philip Dye <philip.h.dye@phd-solutions.com>: ---------- nosy: +Philip Dye _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Stéphane Wirtel <stephane@wirtel.be>: ---------- versions: +Python 3.8, Python 3.9 -Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by STINNER Victor <vstinner@python.org>: ---------- components: +C API nosy: +vstinner _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Mark Lawrence added the comment: @Serhiy will you be proposing a patch for this? ---------- nosy: +BreamoreBoy versions: +Python 3.5 -Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Serhiy Storchaka added the comment:
@Serhiy will you be proposing a patch for this?
No, I am not. I have no opinion what name is better. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Serhiy Storchaka added the comment: The same issue exists for other types. E.g. PyLong_* functions have Python long argument named as p, obj and pylong, PyFloat_* -- p and pyfloat, PyList_* -- p and list, PyDict_* -- p, a and mapping, PyBytes_* -- o, obj, string and bytes. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Matheus Vieira Portela added the comment: Just checking, it would be required to update Objects/unicodeobject.c, Include/unicodeobject.h, and Doc/c-api/unicode.rst, right? As far as I saw, "unicode" means a Python object with unicode string, "u" is a UTF-8 encoded C string, "str" and "s" are encoded C strings (UTF-8, UTF-7, ASCII, Latin-1, among others). Is it alright to rename Python unicode objects to "unicode" and the others to simply "str"? These names are more meaningful than the single character alternatives. The same logic would be applied to the other types, always keeping the longer name rather than the single character ones. ---------- nosy: +matheus.v.portela _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________
Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Windson Yang <wiwindson@outlook.com> added the comment: I agreed with @Matheus, it would be better than the current implementation ---------- nosy: +Windson Yang versions: +Python 3.6, Python 3.7 -Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Windson Yang <wiwindson@outlook.com>: ---------- versions: +Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Windson Yang <wiwindson@outlook.com>: ---------- versions: -Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Rune Tynan <runetynan@gmail.com>: ---------- nosy: +Rune Tynan _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Rune Tynan <runetynan@gmail.com> added the comment: I have some interest in making a fix for this. From discussion, I'm thinking that, barring names that already have clear meaning (EG, left/right for things with two parameters): - PyObject* that is unknown type remains `obj` - PyObject* with unicode string is `unicode` - const char*, const Py_UNICODE*, and const wchar* becomes `str` - const char, const Py_UNICODE, and const wchar become `ch` Those seem to be the intersect of most common and most descriptive names already seen. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Rune Tynan <runetynan@gmail.com> added the comment: Another inconsistency I've noticed is that the code sometimes refers to Py_ssize_t instances as a 'length' and sometimes as a 'size'. It seems like 'size' is the more common one in the docs, but the headers more often use 'length'. Which would be the better one to keep for the common case? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Rune Tynan <runetynan@gmail.com>: ---------- keywords: +patch pull_requests: +12607 stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by STINNER Victor <vstinner@redhat.com>: ---------- nosy: -vstinner _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Rune Tynan <runetynan@gmail.com> added the comment: It has been over a month and I'm still waiting for an updated PR review. I understand if people are busy, but don't want this to just fall through the cracks. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Philip Dye <philip.h.dye@phd-solutions.com>: ---------- nosy: +Philip Dye _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by Stéphane Wirtel <stephane@wirtel.be>: ---------- versions: +Python 3.8, Python 3.9 -Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
Change by STINNER Victor <vstinner@python.org>: ---------- components: +C API nosy: +vstinner _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue18697> _______________________________________
participants (8)
-
Mark Lawrence -
Matheus Vieira Portela
-
Philip Dye
-
Rune Tynan
-
Serhiy Storchaka
-
STINNER Victor
-
Stéphane Wirtel
-
Windson Yang