Skip to content

gh-135913: Document ob_refcnt, ob_type, ob_size #135914

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 5 commits into from
Jul 7, 2025
Merged

gh-135913: Document ob_refcnt, ob_type, ob_size #135914

merged 5 commits into from
Jul 7, 2025

Conversation

encukou
Copy link
Member

@encukou encukou commented Jun 25, 2025 •
edited by github-actions bot
Loading

@bedevere-app bedevere-app bot added awaiting core review docs Documentation in the Doc dir skip news labels Jun 25, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Jun 25, 2025
@bedevere-app bedevere-app bot mentioned this pull request Jun 25, 2025
Closed
colesbury
colesbury reviewed Jun 25, 2025
View reviewed changes
Doc/c-api/structures.rst
Comment on lines +36 to +40
.. c:member:: Py_ssize_t ob_refcnt

The object's reference count, as returned by :c:macro:`Py_REFCNT`.
Do not use this field directly; instead use functions and macros such as
:c:macro:`!Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is accurate anymore:

cpython/Include/object.h

Lines 128 to 146 in a88b49c

union {
#if SIZEOF_VOID_P > 4
PY_INT64_T ob_refcnt_full; /* This field is needed for efficient initialization with Clang on ARM */
struct {
# if PY_BIG_ENDIAN
uint16_t ob_flags;
uint16_t ob_overflow;
uint32_t ob_refcnt;
# else
uint32_t ob_refcnt;
uint16_t ob_overflow;
uint16_t ob_flags;
# endif
};
#else
Py_ssize_t ob_refcnt;
#endif
_Py_ALIGNED_DEF(_PyObject_MIN_ALIGNMENT, char) _aligner;
};

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, yes, the type isn't Py_ssize_t any more.
That's an issue in the current documentation too; guess it's time to reopen #125174 for a docs update.
Similarly, a lot of the docs talk about PyObject_HEAD_INIT setting the refcount to 1. I can't fix everything in this PR...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sphinx needs a type for .. c:member:. I don't think I can do better than the note below.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You may mention Py_SET_REFCNT() as well.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all of the others from the refcounting page (Py_XINCREF, Py_CLEAR, etc.) should be mentioned before Py_SET_REFCNT. The “such as” is intended to cover these.

@encukou encukou added the needs backport to 3.14 bugs and security fixes label Jun 26, 2025
vstinner
vstinner reviewed Jul 3, 2025
View reviewed changes
Doc/c-api/structures.rst
Comment on lines +36 to +40
.. c:member:: Py_ssize_t ob_refcnt

The object's reference count, as returned by :c:macro:`Py_REFCNT`.
Do not use this field directly; instead use functions and macros such as
:c:macro:`!Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You may mention Py_SET_REFCNT() as well.

vstinner
vstinner approved these changes Jul 7, 2025
View reviewed changes
Copy link
Member

@vstinner vstinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@encukou encukou merged commit 73e1207 into python:main Jul 7, 2025
29 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Jul 7, 2025
@miss-islington-app
Copy link

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

@encukou encukou deleted the document-pyobject-fields branch July 7, 2025 12:05
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jul 7, 2025
@encukou @miss-islington
pythongh-135913: Document ob_refcnt, ob_type, ob_size (pythonGH-135914)
157c0f9 
* pythongh-135913: Document ob_refcnt, ob_type, ob_size

In `typeobj.rst`, instead of `:c:member:` it would be better to
use `.. c:member::` with a `:no-index:` option, see:

See ref. https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup

However, `c:member` currently does not support `:no-index:`.
(cherry picked from commit 73e1207)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
@bedevere-app
Copy link

bedevere-app bot commented Jul 7, 2025

GH-136377 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jul 7, 2025
encukou added a commit that referenced this pull request Jul 8, 2025
@miss-islington @encukou
[3.14] gh-135913: Document ob_refcnt, ob_type, ob_size (GH-135914) (G…
78e5d10 
…H-136377)

gh-135913: Document ob_refcnt, ob_type, ob_size (GH-135914)

* gh-135913: Document ob_refcnt, ob_type, ob_size

In `typeobj.rst`, instead of `:c:member:` it would be better to
use `.. c:member::` with a `:no-index:` option, see:

See ref. https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup

However, `c:member` currently does not support `:no-index:`.
(cherry picked from commit 73e1207)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
AndPuQing pushed a commit to AndPuQing/cpython that referenced this pull request Jul 11, 2025
@encukou @AndPuQing
pythongh-135913: Document ob_refcnt, ob_type, ob_size (pythonGH-135914)
5c1b4be 
* pythongh-135913: Document ob_refcnt, ob_type, ob_size

In `typeobj.rst`, instead of `:c:member:` it would be better to
use `.. c:member::` with a `:no-index:` option, see:

See ref. https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup

However, `c:member` currently does not support `:no-index:`.
Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
@encukou @Pranjal095
pythongh-135913: Document ob_refcnt, ob_type, ob_size (pythonGH-135914)
c1d5b84 
* pythongh-135913: Document ob_refcnt, ob_type, ob_size

In `typeobj.rst`, instead of `:c:member:` it would be better to
use `.. c:member::` with a `:no-index:` option, see:

See ref. https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup

However, `c:member` currently does not support `:no-index:`.
picnixz pushed a commit to picnixz/cpython that referenced this pull request Jul 13, 2025
@encukou @picnixz
pythongh-135913: Document ob_refcnt, ob_type, ob_size (pythonGH-135914)
d5c1112 
* pythongh-135913: Document ob_refcnt, ob_type, ob_size

In `typeobj.rst`, instead of `:c:member:` it would be better to
use `.. c:member::` with a `:no-index:` option, see:

See ref. https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup

However, `c:member` currently does not support `:no-index:`.
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
@encukou @taegyunkim
pythongh-135913: Document ob_refcnt, ob_type, ob_size (pythonGH-135914)
6a7e029 
* pythongh-135913: Document ob_refcnt, ob_type, ob_size

In `typeobj.rst`, instead of `:c:member:` it would be better to
use `.. c:member::` with a `:no-index:` option, see:

See ref. https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup

However, `c:member` currently does not support `:no-index:`.
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
@encukou @Agent-Hellboy
pythongh-135913: Document ob_refcnt, ob_type, ob_size (pythonGH-135914)
60b13bb 
* pythongh-135913: Document ob_refcnt, ob_type, ob_size

In `typeobj.rst`, instead of `:c:member:` it would be better to
use `.. c:member::` with a `:no-index:` option, see:

See ref. https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup

However, `c:member` currently does not support `:no-index:`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@colesbury colesbury colesbury left review comments

@vstinner vstinner vstinner approved these changes

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@encukou @vstinner @colesbury