[New-bugs-announce] [issue23980] Documentation for format units starting with 'e' is inconsistent

[Larry Hastings]

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>
_______________________________________