[issue9014] Incorrect documentation of the PyObject_HEAD macro
New submission from Renato Cunha renato@renatocunha.com:
PyObject_HEAD's documentation in py3k (http://docs.python.org/dev/py3k/c-api/structures.html#PyObject_HEAD) uses the same content used in the python 2.x's docs which is wrong, as there were some API changes.
PyObject_HEAD is actually defined as
#define PyObject_HEAD PyObject ob_base;
with PyObject defined as
typedef struct _object { _PyObject_HEAD_EXTRA Py_ssize_t ob_refcnt; struct _typeobject *ob_type; } PyObject;
(The PyTRACE_REFS discussion is still valid, though.)
Additionally, it'd be nice to mention that the Py_REFCNT(ob) and Py_TYPE(ob) macros should be used to access the PyObject members.
---------- assignee: docs@python components: Documentation messages: 107953 nosy: docs@python, trovao priority: normal severity: normal status: open title: Incorrect documentation of the PyObject_HEAD macro type: behavior versions: Python 3.1, Python 3.2, Python 3.3
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
Ray.Allen ysj.ray@gmail.com added the comment:
Additionally, I prefer move the discussion of Py_TRACE_REFS under the documentation of PyObject: http://docs.python.org/dev/py3k/c-api/structures.html?highlight=pyobject_hea..., since they'are connected directly. The doc of PyObject_HEAD should only saying like "expands to a PyObject variable".
---------- nosy: +ysj.ray
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
Arnon Yaari added the comment:
PEP 3123 is the one that describes this change. I'm submitting a file with the proposed changes to the docs.
---------- keywords: +patch nosy: +wiggin15 Added file: http://bugs.python.org/file38991/issue9014.diff
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
A.M. Kuchling added the comment:
Did you intend to remove the discussion of Py_TRACE_REFS completely? (I've reworked your patch a little bit, adding some markup such as :c:macro:`Py_REFCNT`.)
---------- nosy: +akuchling Added file: http://bugs.python.org/file39000/issue.txt
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
Roundup Robot added the comment:
New changeset 760c5cfacbaa by Gregory P. Smith in branch '3.4': issue9014: Properly document PyObject_HEAD and friends post-PEP-3123. https://hg.python.org/cpython/rev/760c5cfacbaa
New changeset 7dc8f0075d60 by Gregory P. Smith in branch 'default': issue9014: Properly document PyObject_HEAD and friends post-PEP-3123. https://hg.python.org/cpython/rev/7dc8f0075d60
---------- nosy: +python-dev
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
Gregory P. Smith added the comment:
i used wiggin15's patch to start with. I'm now looking at akuchling's patch and will incorporate any additional things it adds (I missed that earlier).
---------- assignee: docs@python -> gregory.p.smith nosy: +gregory.p.smith
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
A.M. Kuchling added the comment:
The markup is not a huge deal, I think. I also did some bits of rewording that can probably be ignored. The TRACE_REFS question is the only important one, I think.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
Roundup Robot added the comment:
New changeset 752ea0acc37e by Gregory P. Smith in branch '3.4': issue9014: Include more formatting on :c:type:`PyObject` etc. https://hg.python.org/cpython/rev/752ea0acc37e
New changeset 78a2d1169be1 by Gregory P. Smith in branch 'default': issue9014: Include more formatting on :c:type:`PyObject` etc. https://hg.python.org/cpython/rev/78a2d1169be1
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
Gregory P. Smith added the comment:
We no longer describe the contents of PyObject in the docs so mentioning Py_TRACE_REFS does not seem worth it as that just changes Py_HEAD_EXTRA which adds the doubly linked list to PyObject (today).
Py_TRACE_REFS isn't useful for anyone to know about IMNSHO as it's a compile time define that normally comes from choosing to do a pydebug build. (I believe we have or have at least had bugs in our code where Py_TRACE_REFS won't work if Py_DEBUG is not also defined as we never test in such a mixed non-DEBUG but with TRACE_REFS configuration)
---------- resolution: -> fixed stage: -> commit review status: open -> closed versions: +Python 3.4, Python 3.5
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
Changes by Berker Peksag berker.peksag@gmail.com:
---------- stage: commit review -> resolved
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9014 _______________________________________
participants (7)
-
A.M. Kuchling -
Arnon Yaari
-
Berker Peksag
-
Gregory P. Smith
-
Ray.Allen
-
Renato Cunha
-
Roundup Robot