GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — bpo-17045: Improve C-API doc for PyTypeObject. by ericsnowcurrently · Pull Request #7413 · python/cpython

Conversation

@ericsnowcurrently

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

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@ericsnowcurrently
Improve C-API doc for PyTypeObject.
27612d1
@ericsnowcurrently ericsnowcurrently added the docs Documentation in the Doc dir label Jun 5, 2018
@the-knights-who-say-ni the-knights-who-say-ni added the CLA signed label Jun 5, 2018
@bedevere-bot bedevere-bot added the awaiting merge label Jun 5, 2018
serhiy-storchaka
serhiy-storchaka reviewed Jun 5, 2018
View reviewed changes
Comment thread Doc/c-api/typeobj.rst Outdated
PyTypeObject Slot [#slots]_ Inherited [#inh]_ Type
=========================================== ================= ======================
:c:member:`~PyTypeObject.tp_name` .. char *
:c:member:`~PyTypeObject.tp_basicsize` X int

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Py_ssize_t

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
=========================================== ================= ======================
PyTypeObject Slot [#slots]_ Inherited [#inh]_ Type
=========================================== ================= ======================
:c:member:`~PyTypeObject.tp_name` .. char *

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

const char *tp_name

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
: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 *

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

const char *

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
=========================================== ================= ======================
:c:member:`~PyTypeObject.tp_name` .. char *
:c:member:`~PyTypeObject.tp_basicsize` X int
:c:member:`~PyTypeObject.tp_itemsize` ? int

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Py_ssize_t

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
: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

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

unsigned long

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated

.. XXX belongs elsewhere

Docs for PyGetSetDef::

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Described in structures.rst.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated

**Default:**

PyBaseObject_Type provides a tp_richcompare. However, if only

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Add markup for PyBaseObject_Type and tp_richcompare.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
**Default:**

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

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Add markup for NULL and __dict__.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
:c:func:`PyType_GenericAlloc`, to force a standard heap
allocation strategy.

For static subtypess, PyBaseObject_Type uses

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Add markup for PyBaseObject_Type.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@csabella csabella Jun 5, 2018

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Also, subtypess -> subtypes

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

typo fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
**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

@serhiy-storchaka serhiy-storchaka Jun 5, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Add markup for NULL.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 5, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

fixed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@serhiy-storchaka

serhiy-storchaka commented Jun 5, 2018

Copy link
Copy Markdown
Member

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
ericsnowcurrently added 13 commits June 5, 2018 16:36
@ericsnowcurrently
Fix up the quick reference table.
04b4852
@ericsnowcurrently
Avoid accidental bold.
e1aced8
@ericsnowcurrently
Fix typos.
337c932
@ericsnowcurrently
Add markup for NULL.
af5733d
@ericsnowcurrently
Add markup for __dict__.
4c923e8
@ericsnowcurrently
Add markup in the typedefs table.
3dbba8c
@ericsnowcurrently
Add missing markup.
490b6ab
@ericsnowcurrently
Do not worry about tp_del.
ea81fc2
@ericsnowcurrently
Fix inheritance for tp_as_async.
0e591e6
@ericsnowcurrently
Fix inheritance for tp_hash.
46233dc
@ericsnowcurrently
Clarify tp_hash when NULL.
414448f
@ericsnowcurrently
Do not refer to _Py_HashPointer.
356012d
@ericsnowcurrently
Drop duplicate info about PyGetSetDef.
f4d6500
@ericsnowcurrently

ericsnowcurrently commented Jun 5, 2018

Copy link
Copy Markdown
Member Author

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.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
ericsnowcurrently added 10 commits June 6, 2018 08:55
@ericsnowcurrently
Fix the anchor for tp_as_async.
a3021d1
@ericsnowcurrently
Move the quick-ref table legend up below the table.
39a19c8
@ericsnowcurrently
Add links to typedef names in the summary table.
305468b
@ericsnowcurrently
Move the slot typedefs table to the quick reference section.
221181c
@ericsnowcurrently
Fix the table of contents.
c35b627
@ericsnowcurrently
Add more "info" columns to the tp slots table.
6759ac7
@ericsnowcurrently
tp_finalize is not internal-only.
e4994d3
@ericsnowcurrently
Fix table info and add columns.
cd276bd
@ericsnowcurrently
Fix table column widths.
df5f9ae
@ericsnowcurrently
Fix the note about inheritance through attr lookup.
ce81b38
ericsnowcurrently added 8 commits June 6, 2018 12:56
@ericsnowcurrently
Add a placeholder for common cases in the quick ref.
5264f37
@ericsnowcurrently
Stub out the type slot typedefs.
7f66703
@ericsnowcurrently
Add the missing type slot descriptions.
7ba9e24
@ericsnowcurrently
Drop the "Default" section from type slots that do not need it.
8ad1cbe
@ericsnowcurrently
Add a column for corresponding special method names.
95af724
@ericsnowcurrently
Add a table for the "sub-slots".
bbbbae0
@ericsnowcurrently
minor cleanup
c67b704
@ericsnowcurrently
Fill out the slot typedef descriptions.
3b7c312
@ericsnowcurrently
ericsnowcurrently force-pushed the typeobj-doc branch from 722cc7f to 3b7c312 Compare June 7, 2018 00:25
@ericsnowcurrently
Drop trailing parens in pseudo-call.
00852e5
@ericsnowcurrently

ericsnowcurrently commented Jun 7, 2018

Copy link
Copy Markdown
Member Author

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
ericsnowcurrently added 6 commits June 7, 2018 08:26
@ericsnowcurrently
Do not use a ref in a code block.
9d02687
@ericsnowcurrently
Add a NEWS entry.
71dfb1d
@ericsnowcurrently
Add examples.
3d74a2c
@ericsnowcurrently
Move the examples to the bottom.
c30dec3
@ericsnowcurrently
Add a section about heap types.
ae3ad3d
@ericsnowcurrently
Add a note about tp_base initialization.
349e245
vadmium
vadmium reviewed Jun 9, 2018
View reviewed changes
Comment thread Doc/c-api/typeobj.rst Outdated
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*.

@vadmium vadmium Jun 9, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 13, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 13, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated

.. code-block:: none

X - *PyType_Ready* always sets this value (if *NULL*)

@vadmium vadmium Jun 9, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 13, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated
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*.

@vadmium vadmium Jun 9, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

This line looks like a mistake

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 13, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Yep. I'll fix it.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread Doc/c-api/typeobj.rst Outdated

**Default:**

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

@vadmium vadmium Jun 9, 2018

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@ericsnowcurrently ericsnowcurrently Jun 13, 2018

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

agreed

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
ericsnowcurrently added 4 commits June 13, 2018 09:22
@ericsnowcurrently
Use a better convention for required type slots in the table.
cef58ea
@ericsnowcurrently
Use less confusing phrasing in the table legend.
6af25b7
@ericsnowcurrently
Fix accidental upper-cases.
8d685e7
@ericsnowcurrently
Use less awkward working for the tp_richcompare default.
f2df61d
@ericsnowcurrently

ericsnowcurrently commented Jun 13, 2018

Copy link
Copy Markdown
Member Author

I've addressed all review comments.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@ericsnowcurrently
ericsnowcurrently merged commit 9e7c921 into python:master Jun 14, 2018
@bedevere-bot bedevere-bot removed the awaiting merge label Jun 14, 2018
@ericsnowcurrently
ericsnowcurrently deleted the typeobj-doc branch June 14, 2018 21:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vadmium vadmium vadmium left review comments
@serhiy-storchaka serhiy-storchaka serhiy-storchaka left review comments
@csabella csabella csabella left review comments

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

docs Documentation in the Doc dir

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

6 participants

@ericsnowcurrently @serhiy-storchaka @vadmium @csabella @the-knights-who-say-ni @bedevere-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.