PyArg_ParseTuple y* documentation is incorrect

[terrence]

BPO	9158
Nosy	@vstinner
Files	PyArgs_ParseTuple_ystar_doc_fix.patch: trivial patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2010-07-05.03:29:35.125>
created_at = <Date 2010-07-05.01:44:19.763>
labels = ['type-feature', 'docs']
title = 'PyArg_ParseTuple y* documentation is incorrect'
updated_at = <Date 2010-07-05.22:51:12.309>
user = 'https://bugs.python.org/terrence'

bugs.python.org fields:

activity = <Date 2010-07-05.22:51:12.309>
actor = 'terrence'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-07-05.03:29:35.125>
closer = 'vstinner'
components = ['Documentation']
creation = <Date 2010-07-05.01:44:19.763>
creator = 'terrence'
dependencies = []
files = ['17862']
hgrepos = []
issue_num = 9158
keywords = ['patch']
message_count = 5.0
messages = ['109285', '109290', '109349', '109357', '109361']
nosy_count = 3.0
nosy_names = ['vstinner', 'terrence', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'patch review'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue9158'
versions = ['Python 3.2']

[terrence]

The documented C type for y* should be [Py_buffer], not [Py_buffer *], as with the documentation for z* and the convention followed by the other types.

I'm not sure what 'type' this issue should have. I've set it at 'crash' initially, since that's how the bug manifested for me.

[vstinner]

y* and z* result is a Py_buffer, but in C you have to pass a reference to the result variable using &result. Full example:

static PyObject *
getargs_y_star(PyObject *self, PyObject *args)
{
    Py_buffer buffer;
    PyObject *bytes;
    if (!PyArg_ParseTuple(args, "y*", &buffer))
        return NULL;
    bytes = PyBytes_FromStringAndSize(buffer.buf, buffer.len);
    PyBuffer_Release(&buffer);
    return bytes;
}

Another example: "s" format result is char* (and not char**). You also have to pass a reference using &:

static PyObject *
getargs_s(PyObject *self, PyObject *args)
{
    char *str;
    if (!PyArg_ParseTuple(args, "s", &str))
        return NULL;
    return PyBytes_FromString(str);
}

[terrence]

@victor: "y* and z* result is a Py_buffer"

Correct, so why is z* documented as [Py_buffer] and y* documented as [Py_buffer*]? If I make 'buffer' from your example a Py_buffer*, as documented, then python puts writes sizeof(Py_buffer) bytes into a random spot in memory. Thus the attached patch.

Thanks for giving this a look, but I don't think this issue is closed -- the documentation for y* is still wrong.

[vstinner]

Oh ok, sorry. Fixed in r82597 (3.x) and r82598 (3.1).

[terrence]

Awesome! Thanks, and sorry for communicating the problem so poorly initially.