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 <[email protected]>
<http://bugs.python.org/issue23980>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
