classification
Title: Use C type names (PyUnicode etc;) in the C API docs
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4
process
Status: open Resolution: accepted
Dependencies: Superseder:
Assigned To: vstinner Nosy List: docs@python, eric.araujo, ezio.melotti, fdrake, lemburg, mark.dickinson, pitrou, stutzbach, vstinner
Priority: normal Keywords: patch

Created on 2010-06-08 13:14 by pitrou, last changed 2012-11-08 07:55 by ezio.melotti.

Files
File name Uploaded Description Edit
c_api_arg.patch vstinner, 2010-06-08 22:30 review
Messages (17)
msg107320 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-06-08 13:14
Following r81811 (and issue8925), 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.
msg107358 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-08 22:30
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.
msg107360 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-08 22:41
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.
msg107374 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2010-06-09 09:06
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.
msg107376 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-09 09:28
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.
msg107383 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2010-06-09 10:59
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.
msg107390 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-09 12:14
> 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. :)
msg107462 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2010-06-10 16:17
FWIW, I prefer PyLongObject* over PyLong.  (Though I'm sure I'm guilty of writing PyLong in comments.)
msg107606 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-11 23:34
I commited a first part of the patch: r81923 (3.2), r81924 (3.1).
msg107607 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-11 23:37
"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.
msg108155 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-19 00:06
r82084 (in 3.2 and r82085 in 3.1) fixes some of the reported issues.
msg108213 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-19 22:25
Shouldn’t “inside a :ctype:`Py_BEGIN_ALLOW_THREADS` block” rather use “:cmacro:”?
msg108227 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2010-06-20 08:54
> 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.
msg109054 - (view) Author: Daniel Stutzbach (stutzbach) (Python committer) Date: 2010-07-01 15:04
+1 on using the full name, PyUnicodeObject

The shorthand "PyUnicode" is too easy to confuse with Py_UNICODE (an actual type).
msg109056 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-07-01 15:42
To avoid the strange-looking “a PyUnicodeObject object”, one can write “an instance of PyUnicodeObject”.

Victor, have you kept the ```` around 0 and 1?
msg109057 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-07-01 16:03
> To avoid the strange-looking “a PyUnicodeObject object”, one can write
> “an instance of PyUnicodeObject”.

Or simply "a PyUnicodeObject".
msg175137 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-08 07:55
What's the status of this?
History
Date User Action Args
2012-11-08 07:55:04ezio.melottisettype: enhancement
messages: + msg175137
versions: + Python 3.3, Python 3.4, - Python 3.1
2010-07-01 16:03:31pitrousetmessages: + msg109057
2010-07-01 15:42:55eric.araujosetresolution: accepted
messages: + msg109056
stage: patch review
2010-07-01 15:04:49stutzbachsetnosy: + stutzbach
messages: + msg109054
2010-06-29 15:02:44ezio.melottisetnosy: + ezio.melotti
2010-06-20 08:54:47vstinnersetmessages: + msg108227
2010-06-19 22:25:55eric.araujosetmessages: + msg108213
2010-06-19 00:06:43vstinnersetmessages: + msg108155
2010-06-11 23:37:50vstinnersetmessages: + msg107607
2010-06-11 23:34:32vstinnersetmessages: + msg107606
2010-06-10 16:17:27mark.dickinsonsetnosy: + mark.dickinson
messages: + msg107462
2010-06-09 12:14:02eric.araujosetnosy: + eric.araujo
messages: + msg107390
2010-06-09 10:59:01lemburgsetmessages: + msg107383
2010-06-09 09:28:31vstinnersetmessages: + msg107376
2010-06-09 09:06:23lemburgsetmessages: + msg107374
2010-06-08 22:41:26vstinnersetmessages: + msg107360
2010-06-08 22:33:08fdrakesetnosy: + fdrake
2010-06-08 22:30:39vstinnersetfiles: + c_api_arg.patch
keywords: + patch
messages: + msg107358
2010-06-08 13:14:51pitrousetnosy: + docs@python
2010-06-08 13:14:33pitroucreate