Skip to content

bpo-41790: update error in documentation #22242

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+2 −2
Open

bpo-41790: update error in documentation #22242

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Doc/c-api/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -236,8 +236,8 @@ assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject*` can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static :c:type:`PyTypeObject` objects.
declared. The sole exception are the type objects; they may be static
:c:type:`PyTypeObject` objects.
Copy link
Member

Choose a reason for hiding this comment

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

"The sole exception are the type objects" looks wrong to me. Almost all types in Python are allocated on the heap.

Only static types are never deallocated.

I'm not sure why these kinds of technical details are giving in an introduction. It would be better to move them to https://docs.python.org/dev/c-api/refcounting.html no?
Copy link
Member

Choose a reason for hiding this comment

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

Or at least, copied there.
Copy link
Member

Choose a reason for hiding this comment

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

Hm, I am not find the docs of PyHeapTypeObject. Maybe add those description info in it.
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm not certain what to do with this change. The whole paragraph could be revisited, as Victor hints to. I'm not sure if this change makes things clearer for the reader.

@encukou: thoughts?
Copy link
Member

Choose a reason for hiding this comment

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

To be technically correct, it's not just types – PyModuleDef is also a PyObject* (though I assume that's for historical reasons only). But that's too much detail here.
Comment on lines +239 to +240
Copy link
Member

Choose a reason for hiding this comment

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

Would this work?

Suggested change
declared. The sole exception are the type objects; they may be static
:c:type:`PyTypeObject` objects.
declared. (There are a few exceptions, like static type objects, but even those
are usually manipulated via pointers.)

All Python objects (even Python integers) have a :dfn:`type` and a
:dfn:`reference count`. An object's type determines what kind of object it is
Expand Down