bpo-17045: Improve C-API doc for PyTypeObject. #7413

ericsnowcurrently · 2018-06-05T00:54:09Z

This is a quick port to git of a patch I wrote for the issue several years ago. I'm sure I have it mostly okay, but haven't had time yet to check it closely.

https://bugs.python.org/issue17045

serhiy-storchaka · 2018-06-05T04:36:55Z

Doc/c-api/typeobj.rst

+PyTypeObject Slot [#slots]_                 Inherited [#inh]_ Type
+=========================================== ================= ======================
+:c:member:`~PyTypeObject.tp_name`           ..                char *
+:c:member:`~PyTypeObject.tp_basicsize`      X                 int


Py_ssize_t

serhiy-storchaka · 2018-06-05T04:37:16Z

Doc/c-api/typeobj.rst

+=========================================== ================= ======================
+PyTypeObject Slot [#slots]_                 Inherited [#inh]_ Type
+=========================================== ================= ======================
+:c:member:`~PyTypeObject.tp_name`           ..                char *


const char *tp_name

serhiy-storchaka · 2018-06-05T04:41:42Z

Doc/c-api/typeobj.rst

+:c:member:`~PyTypeObject.tp_setattro`       X                 :c:type:`setattrofunc`
+:c:member:`~PyTypeObject.tp_as_buffer`      \*                PyBufferProcs *
+:c:member:`~PyTypeObject.tp_flags`          ?                 long
+:c:member:`~PyTypeObject.tp_doc`            ..                char *


const char *

serhiy-storchaka · 2018-06-05T04:41:57Z

Doc/c-api/typeobj.rst

+=========================================== ================= ======================
+:c:member:`~PyTypeObject.tp_name`           ..                char *
+:c:member:`~PyTypeObject.tp_basicsize`      X                 int
+:c:member:`~PyTypeObject.tp_itemsize`       ?                 int


Py_ssize_t

serhiy-storchaka · 2018-06-05T04:42:16Z

Doc/c-api/typeobj.rst

+:c:member:`~PyTypeObject.tp_getattro`       X                 :c:type:`getattrofunc`
+:c:member:`~PyTypeObject.tp_setattro`       X                 :c:type:`setattrofunc`
+:c:member:`~PyTypeObject.tp_as_buffer`      \*                PyBufferProcs *
+:c:member:`~PyTypeObject.tp_flags`          ?                 long


unsigned long

serhiy-storchaka · 2018-06-05T05:49:52Z

Doc/c-api/typeobj.rst

@@ -732,19 +1025,45 @@ type objects) *must* have the :attr:`ob_size` field.
   For each entry in the array, an entry is added to the type's dictionary (see
   :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor.

+   .. XXX belongs elsewhere
+
+   Docs for PyGetSetDef::


Described in structures.rst.

serhiy-storchaka · 2018-06-05T05:50:41Z

Doc/c-api/typeobj.rst

+
+   **Default:**
+
+   PyBaseObject_Type provides a tp_richcompare.  However, if only


Add markup for PyBaseObject_Type and tp_richcompare.

serhiy-storchaka · 2018-06-05T05:52:22Z

Doc/c-api/typeobj.rst

+   **Default:**
+
+   This slot has no default.  For static types, if the field is
+   NULL then no __dict__ gets created for instances.


Add markup for NULL and __dict__.

serhiy-storchaka · 2018-06-05T05:52:50Z

Doc/c-api/typeobj.rst

+   :c:func:`PyType_GenericAlloc`, to force a standard heap
+   allocation strategy.
+
+   For static subtypess, PyBaseObject_Type uses


Add markup for PyBaseObject_Type.

Also, subtypess -> subtypes

serhiy-storchaka · 2018-06-05T05:53:17Z

Doc/c-api/typeobj.rst

+   **Default:**
+
+   For static types this field has no default.  This means if the
+   slot is defined as NULL, the type cannot be called to create new


Add markup for NULL.

serhiy-storchaka · 2018-06-05T06:55:30Z

I'm not sure about usefulness of Default: notes. If the slot is inherited, then the default is the parent's value. It looks to me that Inheritane: notes cover this, and Default: notes don't add new information.

ericsnowcurrently · 2018-06-05T23:48:33Z

If I recall correctly, there are a few slots with defaults. Would it be better to omit the "default" section in the rest of the cases? FWIW, I added the "default" section because the defaults aren't always clear.

ericsnowcurrently · 2018-06-07T14:20:36Z

Ah, I need to run "make suspicious". :/

vadmium · 2018-06-09T12:41:22Z

Doc/c-api/typeobj.rst

+   A slot name in parentheses indicates it is (effectively) deprecated.
+   Names in angle brackets should be treated as read-only.
+   Names in square brackets are for internal use only.
+   An asterisk means the field must be non-*NULL*.


Can you find another notation that doesn’t look like a pointer type or dereferencing a pointer?

Sure. I was following the existing convention in the file, but agree it's less clear.

Oh, you're talking about the notation in the table. :) I'll change it to something else.

vadmium · 2018-06-09T12:46:11Z

Doc/c-api/typeobj.rst

+
+   .. code-block:: none
+
+      X - *PyType_Ready* always sets this value (if *NULL*)


The always and brackets confuse me. Would this be more correct: “PyTypeReady sets this value if it is NULL”?

I agree that it's not as clear as I want. My goal was to emphasize that it does get set by PyType_Ready(). I'll make it more clear.

vadmium · 2018-06-09T12:54:22Z

Doc/c-api/typeobj.rst


   This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype
   inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
-   the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.
+   THE SUBTYpe's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.


This line looks like a mistake

Yep. I'll fix it.

vadmium · 2018-06-09T13:00:57Z

Doc/c-api/typeobj.rst

+
+   **Default:**
+
+   :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare`.


Drop a or add a real noun, i.e. “provides tp_richcompare” or “provides a tp_richcompare implementation”

ericsnowcurrently · 2018-06-13T15:31:51Z

I've addressed all review comments.

Improve C-API doc for PyTypeObject.

27612d1

ericsnowcurrently added the docs Documentation in the Doc dir label Jun 5, 2018

the-knights-who-say-ni added the CLA signed label Jun 5, 2018

bedevere-bot added the awaiting merge label Jun 5, 2018

serhiy-storchaka reviewed Jun 5, 2018

View reviewed changes

ericsnowcurrently added 13 commits June 5, 2018 16:36

Fix up the quick reference table.

04b4852

Avoid accidental bold.

e1aced8

Fix typos.

337c932

Add markup for NULL.

af5733d

Add markup for __dict__.

4c923e8

Add markup in the typedefs table.

3dbba8c

Add missing markup.

490b6ab

Do not worry about tp_del.

ea81fc2

Fix inheritance for tp_as_async.

0e591e6

Fix inheritance for tp_hash.

46233dc

Clarify tp_hash when NULL.

414448f

Do not refer to _Py_HashPointer.

356012d

Drop duplicate info about PyGetSetDef.

f4d6500

ericsnowcurrently added 10 commits June 6, 2018 08:55

Fix the anchor for tp_as_async.

a3021d1

Move the quick-ref table legend up below the table.

39a19c8

Add links to typedef names in the summary table.

305468b

Move the slot typedefs table to the quick reference section.

221181c

Fix the table of contents.

c35b627

Add more "info" columns to the tp slots table.

6759ac7

tp_finalize is not internal-only.

e4994d3

Fix table info and add columns.

cd276bd

Fix table column widths.

df5f9ae

Fix the note about inheritance through attr lookup.

ce81b38

ericsnowcurrently added 8 commits June 6, 2018 12:56

Add a placeholder for common cases in the quick ref.

5264f37

Stub out the type slot typedefs.

7f66703

Add the missing type slot descriptions.

7ba9e24

Drop the "Default" section from type slots that do not need it.

8ad1cbe

Add a column for corresponding special method names.

95af724

Add a table for the "sub-slots".

bbbbae0

minor cleanup

c67b704

Fill out the slot typedef descriptions.

3b7c312

ericsnowcurrently force-pushed the typeobj-doc branch from 722cc7f to 3b7c312 Compare June 7, 2018 00:25

Drop trailing parens in pseudo-call.

00852e5

ericsnowcurrently added 6 commits June 7, 2018 08:26

Do not use a ref in a code block.

9d02687

Add a NEWS entry.

71dfb1d

Add examples.

3d74a2c

Move the examples to the bottom.

c30dec3

Add a section about heap types.

ae3ad3d

Add a note about tp_base initialization.

349e245

vadmium reviewed Jun 9, 2018

View reviewed changes

ericsnowcurrently added 4 commits June 13, 2018 09:22

Use a better convention for required type slots in the table.

cef58ea

Use less confusing phrasing in the table legend.

6af25b7

Fix accidental upper-cases.

8d685e7

Use less awkward working for the tp_richcompare default.

f2df61d

ericsnowcurrently merged commit 9e7c921 into python:master Jun 14, 2018

bedevere-bot removed the awaiting merge label Jun 14, 2018

ericsnowcurrently deleted the typeobj-doc branch June 14, 2018 21:46


		Default:

		PyBaseObject_Type provides a tp_richcompare. However, if only


		.. code-block:: none

		X - PyType_Ready always sets this value (if NULL)


		Default:

		:c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare`.

bpo-17045: Improve C-API doc for PyTypeObject. #7413

bpo-17045: Improve C-API doc for PyTypeObject. #7413

Conversation

ericsnowcurrently commented Jun 5, 2018 • edited by bedevere-bot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

serhiy-storchaka commented Jun 5, 2018

ericsnowcurrently commented Jun 5, 2018

ericsnowcurrently commented Jun 7, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericsnowcurrently commented Jun 13, 2018

ericsnowcurrently commented Jun 5, 2018 •

edited by bedevere-bot

Loading