homepage

Is there a reason for not documenting Py_TPFLAGS_LONG_SUBCLASS (Py_TPFLAGS_INT_SUBCLASS in 2.x)?
This flag is used in PyLong_Check, but neither this flag or its inheritance properties are explained anywhere in the docs.
See also issue5476.

Here are other similar flags that are not documented:
/* These flags are used to determine if a type is a subclass. */
#define Py_TPFLAGS_INT_SUBCLASS (1L<<23)
#define Py_TPFLAGS_LONG_SUBCLASS (1L<<24)
#define Py_TPFLAGS_LIST_SUBCLASS (1L<<25)
#define Py_TPFLAGS_TUPLE_SUBCLASS (1L<<26)
#define Py_TPFLAGS_BYTES_SUBCLASS (1L<<27)
#define Py_TPFLAGS_UNICODE_SUBCLASS (1L<<28)
#define Py_TPFLAGS_DICT_SUBCLASS (1L<<29)
#define Py_TPFLAGS_BASE_EXC_SUBCLASS (1L<<30)
#define Py_TPFLAGS_TYPE_SUBCLASS (1L<<31)
On a similar note, TPFLAGS_IS_ABSTRACT is exposed in the inspect module, but is not documented in either inspect module documentation or C API documentation.
I believe that as long as these flags are available from the type objects as __flags__, all valid bits should be exposed in inspect module and properly documented.

It would probably be more useful to document them in the C API and put a reference to that in the inspect module docs. These flags are primarily useful for C extension developers, there's little point checking them from Python code.

On Mon, Jul 19, 2010 at 2:17 PM, Antoine Pitrou <report@bugs.python.org> wrote:
> .. These flags are primarily useful for C extension developers, there's little point checking them from Python code.
Of course there is: it helps debugging problems in types implemented
in C. For example, someone working on the numpy issue described in
msg110788, would probably appreciate having
inspect.TPFLAGS_INT_SUBCLASS and would probaly use it in his or hers
unit tests.
My point is: we have __flags__ attribute on type objects exposed in
python there should be a way to interpret what it means without
looking up object.h or C API documentation.
BTW, __flags__ itself could grow a docstring and deserves to be
mentioned in the docs. Note that copyreg.py uses it to determine
wither a class is dynamically allocated. Maybe this should also go
to inspect as inspect.isheaptype().

Hi,
I agree with Alexander, I've been recently investigating a related problem and I found the lack of documentation on the subject quite frustrating; I therefore propose the attached patch to the docs.
Hope that helps,
--Yury.

New changeset 37786ae8cc1c by Antoine Pitrou in branch '3.4':
Issue #9307: document the various Py_TPFLAGS_*_SUBCLASS flags. Patch by Yury V. Zaytsev.
http://hg.python.org/cpython/rev/37786ae8cc1c
New changeset d1a03834cec7 by Antoine Pitrou in branch 'default':
Issue #9307: document the various Py_TPFLAGS_*_SUBCLASS flags. Patch by Yury V. Zaytsev.
http://hg.python.org/cpython/rev/d1a03834cec7 

This is committed, thank you.