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

Created on 2013-08-09 18:48 by serhiy.storchaka, last changed 2019-12-09 16:13 by vstinner.

Pull Requests
URL Status Linked Edit
PR 12680 open Rune Tynan, 2019-04-04 01:15
Messages (9)
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
msg339088 - (view) Author: Rune Tynan (Rune Tynan) * Date: 2019-03-29 01:16
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.
msg339420 - (view) Author: Rune Tynan (Rune Tynan) * Date: 2019-04-04 00:53
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?
msg347171 - (view) Author: Rune Tynan (Rune Tynan) * Date: 2019-07-02 23:43
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.
History
Date User Action Args
2019-12-09 16:13:02vstinnersetnosy: + vstinner
components: + C API
2019-09-11 13:29:42matrixisesetversions: + Python 3.8, Python 3.9, - Python 3.4, Python 3.5, Python 3.6
2019-08-08 23:58:05Philip Dyesetnosy: + Philip Dye
2019-07-02 23:43:09Rune Tynansetmessages: + msg347171
2019-04-11 13:20:50vstinnersetnosy: - vstinner
2019-04-04 01:15:23Rune Tynansetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request12607
2019-04-04 00:53:24Rune Tynansetmessages: + msg339420
2019-03-29 01:16:42Rune Tynansetmessages: + msg339088
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