[issue8939] Use C type names (PyUnicode etc; ) in the C API docs
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) - 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. ---------- keywords: +patch Added file: http://bugs.python.org/file17593/c_api_arg.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8939> _______________________________________
Marc-Andre Lemburg <mal@egenix.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8939> _______________________________________
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.
- 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8939> _______________________________________
Marc-Andre Lemburg <mal@egenix.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8939> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
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. :) ---------- nosy: +merwok _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue8939> _______________________________________
participants (3)
-
Marc-Andre Lemburg -
STINNER Victor
-
Éric Araujo