Unify arguments names in Unicode object C API documentation

[serhiy-storchaka]

BPO	18697
Nosy	@vstinner, @ezio-melotti, @serhiy-storchaka, @matheusportela, @Windsooon, @CraftSpider
PRs	gh-62897: Update PyUnicode parameter names #12680

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2013-08-09.18:48:46.553>
labels = ['easy', '3.7', '3.8', '3.9', 'expert-C-API', 'type-feature', 'expert-unicode', 'docs']
title = 'Unify arguments names in Unicode object C API documentation'
updated_at = <Date 2019-12-09.16:13:02.233>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2019-12-09.16:13:02.233>
actor = 'vstinner'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Unicode', 'C API']
creation = <Date 2013-08-09.18:48:46.553>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 18697
keywords = ['patch', 'easy']
message_count = 9.0
messages = ['194755', '224600', '224609', '231274', '249437', '337589', '339088', '339420', '347171']
nosy_count = 8.0
nosy_names = ['vstinner', 'ezio.melotti', 'docs@python', 'serhiy.storchaka', 'matheus.v.portela', 'Windson Yang', 'Rune Tynan', 'Philip Dye']
pr_nums = ['12680']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue18697'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

Linked PRs

• [3.12] gh-62897: Update PyUnicode C API parameter names (GH-12680) #112744
• [3.11] gh-62897: Update PyUnicode C API parameter names (GH-12680) #112745

[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().

[BreamoreBoy]

@serhiy will you be proposing a patch for this?

[serhiy-storchaka]

@serhiy will you be proposing a patch for this?

No, I am not. I have no opinion what name is better.

[serhiy-storchaka]

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.

[matheusportela]

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.

[Windsooon]

I agreed with @matheus, it would be better than the current implementation

[CraftSpider]

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.

[CraftSpider]

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?

[CraftSpider]

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.