Use C type names (PyUnicode etc;) in the C API docs

[pitrou]

BPO	8939
Nosy	@malemburg, @freddrake, @mdickinson, @pitrou, @vstinner, @ezio-melotti, @merwok
Files	c_api_arg.patch

^{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 = 'https://github.com/vstinner'
closed_at = None
created_at = <Date 2010-06-08.13:14:33.681>
labels = ['expert-C-API', 'type-feature', 'docs']
title = 'Use C type names (PyUnicode etc;) in the C API docs'
updated_at = <Date 2020-06-25.09:40:47.110>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2020-06-25.09:40:47.110>
actor = 'vstinner'
assignee = 'vstinner'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'C API']
creation = <Date 2010-06-08.13:14:33.681>
creator = 'pitrou'
dependencies = []
files = ['17593']
hgrepos = []
issue_num = 8939
keywords = ['patch']
message_count = 17.0
messages = ['107320', '107358', '107360', '107374', '107376', '107383', '107390', '107462', '107606', '107607', '108155', '108213', '108227', '109054', '109056', '109057', '175137']
nosy_count = 9.0
nosy_names = ['lemburg', 'fdrake', 'mark.dickinson', 'pitrou', 'vstinner', 'stutzbach', 'ezio.melotti', 'eric.araujo', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue8939'
versions = ['Python 3.2', 'Python 3.3', 'Python 3.4']

Linked PRs

• gh-53185: Use C type names in c-api/args.rst #132833

[pitrou]

Following r81811 (and bpo-8925), perhaps we should start using e.g. PyUnicode, PyBytes, PyLong, etc. in the C API docs to more closely follow the C API rather than use the type names you see at the Python level.

[vstinner]

Big patch:

• replace Python types by C Python types (eg. str => PyUnicodeObject* and None => Py_None)
• fix "w" / "w*" / "w#" doc: similar to "y" / "y*" / "y#" (and not "s" / "s*" / "s#")
• add quotes to the formats, eg. s => "s"
• use :ctype: to add links to some terms (eg. Py_BEGIN_ALLOW_THREADS) and use a fixed width font
• replace "the default encoding" by "'utf-8' encoding"
• replace true by 1, and false by 0 (C API of Python doesn't use stdbool.h but classic int)
• use a list for the two modes of "es#"
• Py_BuildValue(), "s" and "s#" formats: specify that the Python object is a str

1 and 0 were formatted with 1 and 0. I don't understand why, so I removed the italic style.

Sorry for the length of the patch, but it was easy to work on only one aspect.

[vstinner]

Other changes of the patch:

• "u#": remove "Non-Unicode objects are handled by interpreting their read-buffer pointer ...", it's no more true
• "es", "es#": remove "... and objects convertible to Unicode into a character buffer", it's no more true
• Py_BuildValue(), "K" and "L" formats: specify the name of the C type on Windows (_int64 / unsigned _int64) as done for PyArg_Parse*() long long types

If the patch is too long, I can try to split it into smaller parts.

[malemburg]

STINNER Victor wrote:

STINNER Victor <victor.stinner@haypocalc.com> added the comment:

Big patch:

• replace Python types by C Python types (eg. str => PyUnicodeObject* and None => Py_None)

I was thinking of e.g. "PyUnicode", not "PyUnicodeObject*".

• add quotes to the formats, eg. s => "s"

Why do you put the parser codes in double quotes ?

• use :ctype: to add links to some terms (eg. Py_BEGIN_ALLOW_THREADS) and use a fixed width font
• replace "the default encoding" by "'utf-8' encoding"
• replace true by 1, and false by 0 (C API of Python doesn't use stdbool.h but classic int)

That's not necessarily correct: true in C means non-zero. Only
false equates to 0. You can however, make that change if the
function actually does always return 1.

In general, most C functions in Python use these integer
return values:

1 - success
0 - no success
-1 - error

Some of them also return a positive integer >1 for success or
a negative integer <-1 for error, but those are exceptions.

[vstinner]

Le mercredi 09 juin 2010 11:06:25, vous avez écrit :

> - replace Python types by C Python types (eg. str => PyUnicodeObject*
> and None => Py_None)

I was thinking of e.g. "PyUnicode", not "PyUnicodeObject*".

I don't know PyUnicode, only "unicode" (Python type) or "PyUnicodeObject*" (C
Python type). :ctype:`PyUnicodeObject*` creates a link in the HTML
documentation.

> - add quotes to the formats, eg. s => "s"

Why do you put the parser codes in double quotes ?

It's easier to search a format: try to search s or b format in the current
documentation, you will see :-)

I think that it's also more readable and closer to the "real" source code (eg.
a call to PyArg_ParseTuple() uses quotes).

> - replace true by 1, and false by 0 (C API of Python doesn't use
> stdbool.h but classic int)

That's not necessarily correct: true in C means non-zero. Only
false equates to 0. You can however, make that change if the
function actually does always return 1.

There are only 2 possible results: 0 or 1.

[malemburg]

STINNER Victor wrote:
> 
> STINNER Victor <victor.stinner@haypocalc.com> added the comment:
> 
> Le mercredi 09 juin 2010 11:06:25, vous avez écrit :
>>>  - replace Python types by C Python types (eg. str => PyUnicodeObject*
>>>  and None => Py_None)
>>
>> I was thinking of e.g. "PyUnicode", not "PyUnicodeObject*".
> 
> I don't know PyUnicode, only "unicode" (Python type) or "PyUnicodeObject*" (C 
> Python type). :ctype:`PyUnicodeObject*` creates a link in the HTML 
> documentation.

The "PyUnicode" style is just an abbreviated version of the longer
"PyUnicodeObject", that we sometimes use, since writing "Pass
a PyUnicodeObject object to this function" looks a bit silly.

I don't have a strong opinion about this, though. The longer
version is fine as well.

>> - add quotes to the formats, eg. s => "s"
>
> Why do you put the parser codes in double quotes ?

It's easier to search a format: try to search s or b format in the current
documentation, you will see :-)

I think that it's also more readable and closer to the "real" source code (eg.
a call to PyArg_ParseTuple() uses quotes).

It could lead developers into thinking that they have to use
those quotes in their code.

Perhaps you should add a note about this typographic addition
to docs.

>> - replace true by 1, and false by 0 (C API of Python doesn't use
>> stdbool.h but classic int)
>
> That's not necessarily correct: true in C means non-zero. Only
> false equates to 0. You can however, make that change if the
> function actually does always return 1.

There are only 2 possible results: 0 or 1.

I wouldn't count on this. It may be the case now, but it's both
hard to check by reading the code and knowing that only 1 can
be returned doesn't buy a developer much.

In fact, this has
bitten us before with the cmp() function: users starting writing
code like this because we documented the return codes as -1, 0, 1:

a = b + z * cmp(x, y)

Please use "non-zero" instead.

[merwok]

1 and 0 were formatted with 1 and 0. I don't understand why,
so I removed the italic style.

This reST construct marks up code. Please revert this change. :)

[mdickinson]

FWIW, I prefer PyLongObject* over PyLong. (Though I'm sure I'm guilty of writing PyLong in comments.)

[vstinner]

I commited a first part of the patch: r81923 (3.2), r81924 (3.1).

[vstinner]

"PyUnicodeObject*" is not the best choice for the description of the function, and I don't really like "PyUnicode". Can't we use C types in the function prototype and Python types in the description?

Example:
-------
s (PyUnicodeObject* or None) [char *]
Convert a null-terminated C string to a Python unicode object using 'utf-8' encoding. If the C string pointer is NULL, None is used.
-----
PyUnicodeObject will be a link to the C type, and unicode a link to the Python type.

[vstinner]

r82084 (in 3.2 and r82085 in 3.1) fixes some of the reported issues.

[merwok]

Shouldn’t “inside a :ctype:`Py_BEGIN_ALLOW_THREADS` block” rather use “:cmacro:”?

[vstinner]

Shouldn’t “inside a :ctype:`Py_BEGIN_ALLOW_THREADS` block” rather use “:cmacro:”?

Same remark on IRC: "Taggnostr> haypo, in r82084: "Add :ctype: to Py_BEGIN_ALLOW_THREADS and int", maybe :cfunc: (or :cmacro:)?"

I don't know :cmacro:. I will fix it in my next patch.