[issue23980] Documentation for format units starting with 'e' is inconsistent
Larry Hastings
report at bugs.python.org
Fri Apr 17 01:38:46 CEST 2015
New submission from Larry Hastings:
Documentation is here:
https://docs.python.org/3/c-api/arg.html#arg-parsing
The first line of documentation for each format unit follows this convention:
formatunit (pythontype) [arguments, to, pyarg_parsetuple]
These represent the format unit itself, followed by the Python type it consumes in parentheses, followed by the C types it outputs in square brackets. Thus
i (int) [int]
means the format unit is 'i', it consumes a Python 'int', and it produces a C 'int'. Similarly,
s (str) [const char *]
means the format unit is 's', it consumes a Python 'str', and it produces a C 'const char *'.
When you call PyArg_ParseTuple (AndKeywords), you pass in a pointer to the thing you expect. If it gives you an int, you pass in &my_int. So the type of the expression you pass in for 'i' is actually "int *". And the type you pass in for 's' is actually "char **".
The format units that deal with encodings are a bit weirder. You actually pass in a const char * string first, followed by the buffer you want to write data too. Technically the types of the values you pass in for "es" are "const char *, char **". But the documentation for es says
es (str) [const char *encoding, char **buffer]
This led me to believe that I actually had to pass in a "char ***" for buffer! Which is wrong and doing so makes your programs explode-y.
The documentation should
* explain this first-line convention precisely, and
* use the types consistently.
My suspicion is that the things in brackets have to be the precise C type, e.g. "int *" for i, "char **" for s, "const char *, char **" for es.
----------
assignee: larry
components: Documentation
messages: 241292
nosy: benjamin.peterson, georg.brandl, larry
priority: normal
severity: normal
stage: needs patch
status: open
title: Documentation for format units starting with 'e' is inconsistent
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue23980>
_______________________________________
More information about the Python-bugs-list
mailing list