classification
Title: C API doc for PyObject_HEAD is outdated
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Evelyn Mitchell, ammar2, berker.peksag, docs@python, matrixise, python-dev, r.david.murray, tpievila
Priority: normal Keywords: easy, patch

Created on 2015-03-19 14:41 by tpievila, last changed 2016-08-03 09:59 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
capidocs.diff ammar2, 2016-07-06 22:39 review
capidocs.diff-2 ammar2, 2016-07-07 18:16 review
Messages (10)
msg238530 - (view) Author: Tomi Pieviläinen (tpievila) Date: 2015-03-19 14:41
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.
msg263735 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-04-19 13:09
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.
msg269912 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2016-07-06 22:39
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.
msg269936 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-07 14:32
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.
msg269955 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2016-07-07 18:16
>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.
msg269956 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2016-07-07 18:46
Looks good to me.
msg271858 - (view) Author: Evelyn Mitchell (Evelyn Mitchell) * (Python triager) Date: 2016-08-02 21:45
There is a patch, and it looks good to me. This should be moved into 'commit review' state.
msg271860 - (view) Author: Evelyn Mitchell (Evelyn Mitchell) * (Python triager) Date: 2016-08-02 21:58
Changed to commit review.
msg271886 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-08-03 09:58
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
msg271887 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-08-03 09:59
Thanks for the patch. Committed capidocs.diff-2 with some tweaks.
History
Date User Action Args
2016-08-03 09:59:23berker.peksagsetstatus: open -> closed
resolution: fixed
messages: + msg271887

stage: commit review -> resolved
2016-08-03 09:58:20python-devsetnosy: + python-dev
messages: + msg271886
2016-08-02 22:55:10matrixisesetnosy: + matrixise
2016-08-02 21:58:27Evelyn Mitchellsetmessages: + msg271860
stage: needs patch -> commit review
2016-08-02 21:45:04Evelyn Mitchellsetnosy: + Evelyn Mitchell
messages: + msg271858
2016-07-07 18:46:49r.david.murraysetmessages: + msg269956
2016-07-07 18:16:34ammar2setfiles: + capidocs.diff-2

messages: + msg269955
2016-07-07 14:32:42r.david.murraysetnosy: + r.david.murray
messages: + msg269936
2016-07-06 22:39:45ammar2setfiles: + capidocs.diff

nosy: + ammar2
messages: + msg269912

keywords: + patch
2016-04-19 13:09:54berker.peksagsettype: behavior
versions: + Python 3.5, Python 3.6
keywords: + easy
nosy: + berker.peksag

messages: + msg263735
stage: needs patch
2015-03-19 14:41:38tpievilacreate