[issue23710] C API doc for PyObject_HEAD is outdated
New submission from Tomi Pieviläinen: https://docs.python.org/3/c-api/structures.html#c.PyObject_HEAD says that the macro should be used for creating new types and that it has ob_type. Unfortunately at some point (@61466 perhaps) that definition in object.h was changed. This affects other pages too (at least https://docs.python.org/3/extending/newtypes.html). I encountered this while checking if a C extension (imposm.parser) could be trivially ported for Python 3. Unfortunately not. I suppose self->ob_type should be replaced with Py_TYPE(self) but that isn't really clear from the docs. ---------- assignee: docs@python components: Documentation messages: 238530 nosy: docs@python, tpievila priority: normal severity: normal status: open title: C API doc for PyObject_HEAD is outdated _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Berker Peksag added the comment: Docs of PyObject_HEAD and friends have already been fixed in 760c5cfacbaa. https://docs.python.org/3/extending/newtypes.html still needs to be updated to mention ob_base: This is what a Noddy object will contain—in this case, nothing more than what every Python object contains—a refcount and a pointer to a type object. These are the fields the PyObject_HEAD macro brings in. ---------- keywords: +easy nosy: +berker.peksag stage: -> needs patch type: -> behavior versions: +Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Ammar Askar added the comment: This diff amends the documentation to point out that PyObject_HEAD includes the ob_base field, gives a brief overview of it and points to the PyObject/structures page for more information. It also changes the semicolon part to a warning for clarity. ---------- keywords: +patch nosy: +ammar2 Added file: http://bugs.python.org/file43649/capidocs.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
R. David Murray added the comment: Warnings are big red boxes, and we try to only use those for really critical info. The current text is what we want as far as that goes. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Ammar Askar added the comment:
The current text is what we want as far as that goes.
Roger that, I've reverted the change to make that a warning in the newest diff. ---------- Added file: http://bugs.python.org/file43657/capidocs.diff-2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
R. David Murray added the comment: Looks good to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Evelyn Mitchell added the comment: There is a patch, and it looks good to me. This should be moved into 'commit review' state. ---------- nosy: +Evelyn Mitchell _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Evelyn Mitchell added the comment: Changed to commit review. ---------- stage: needs patch -> commit review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Changes by Stéphane Wirtel <stephane@wirtel.be>: ---------- nosy: +matrixise _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Roundup Robot added the comment: New changeset 92b468020e07 by Berker Peksag in branch '3.5': Issue #23710: Update PyObject_HEAD documentation https://hg.python.org/cpython/rev/92b468020e07 New changeset 26dd6e7f1733 by Berker Peksag in branch 'default': Issue #23710: Merge from 3.5 https://hg.python.org/cpython/rev/26dd6e7f1733 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
Berker Peksag added the comment: Thanks for the patch. Committed capidocs.diff-2 with some tweaks. ---------- resolution: -> fixed stage: commit review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________
participants (7)
-
Ammar Askar -
Berker Peksag
-
Evelyn Mitchell
-
R. David Murray
-
Roundup Robot
-
Stéphane Wirtel
-
Tomi Pieviläinen