[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
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
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
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
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
Change by Mark Lawrence
Windson Yang
Change by Windson Yang
Change by Windson Yang
Change by Rune Tynan
Rune Tynan
Rune Tynan
Change by Rune Tynan
Change by STINNER Victor
Rune Tynan
Change by Philip Dye
Change by Stéphane Wirtel
Change by STINNER Victor
participants (8)
-
Mark Lawrence
-
Matheus Vieira Portela
-
Philip Dye
-
Rune Tynan
-
Serhiy Storchaka
-
STINNER Victor
-
Stéphane Wirtel
-
Windson Yang