classification
Title: Unify arguments names in Unicode object C API documentation
Type: enhancement Stage: needs patch
Components: Documentation, Unicode Versions: Python 3.7, Python 3.6, Python 3.4, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Rune Tynan, Windson Yang, docs@python, ezio.melotti, matheus.v.portela, serhiy.storchaka, vstinner
Priority: normal Keywords: easy

Created on 2013-08-09 18:48 by serhiy.storchaka, last changed 2019-03-27 01:15 by Rune Tynan.

Messages (6)
msg194755 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2013-08-09 18:48
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().
msg224600 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-08-03 00:34
@Serhiy will you be proposing a patch for this?
msg224609 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-08-03 06:18
> @Serhiy will you be proposing a patch for this?

No, I am not. I have no opinion what name is better.
msg231274 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2014-11-17 08:50
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.
msg249437 - (view) Author: Matheus Vieira Portela (matheus.v.portela) * Date: 2015-08-31 23:03
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.
msg337589 - (view) Author: Windson Yang (Windson Yang) * Date: 2019-03-10 02:41
I agreed with @Matheus, it would be better than the current implementation
History
Date User Action Args
2019-03-27 01:15:00Rune Tynansetnosy: + Rune Tynan
2019-03-10 02:41:57Windson Yangsetversions: - Python 2.7
2019-03-10 02:41:26Windson Yangsetversions: + Python 2.7, Python 3.4, Python 3.5
2019-03-10 02:41:12Windson Yangsetnosy: + Windson Yang

messages: + msg337589
versions: + Python 3.6, Python 3.7, - Python 2.7, Python 3.4, Python 3.5
2019-02-24 22:42:34BreamoreBoysetnosy: - BreamoreBoy
2015-08-31 23:03:57matheus.v.portelasetnosy: + matheus.v.portela
messages: + msg249437
2014-11-17 08:50:52serhiy.storchakasetmessages: + msg231274
2014-08-03 06:18:28serhiy.storchakasetmessages: + msg224609
2014-08-03 00:34:57BreamoreBoysetnosy: + BreamoreBoy

messages: + msg224600
versions: + Python 3.5, - Python 3.3
2013-08-09 18:48:46serhiy.storchakacreate