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