[issue9307] Py_TPFLAGS_LONG_SUBCLASS is not documented
New submission from Alexander Belopolsky belopolsky@users.sourceforge.net:
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.
---------- assignee: docs@python components: Documentation messages: 110787 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Py_TPFLAGS_LONG_SUBCLASS is not documented type: feature request
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
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.
---------- components: +Library (Lib) versions: +Python 2.7, Python 3.2
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Antoine Pitrou pitrou@free.fr added the comment:
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.
---------- nosy: +pitrou versions: +Python 3.1
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
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().
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Changes by Terry J. Reedy tjreedy@udel.edu:
---------- versions: +Python 3.3
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Yury V. Zaytsev added the comment:
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.
---------- keywords: +patch nosy: +zaytsev Added file: http://bugs.python.org/file30952/tpflags-doc.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Changes by STINNER Victor victor.stinner@gmail.com:
---------- nosy: +haypo
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Roundup Robot added the comment:
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
---------- nosy: +python-dev
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
Antoine Pitrou added the comment:
This is committed, thank you.
---------- resolution: -> fixed stage: needs patch -> resolved status: open -> closed versions: +Python 3.4 -Python 2.7, Python 3.1, Python 3.2
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9307 _______________________________________
participants (6)
-
Alexander Belopolsky -
Antoine Pitrou
-
Roundup Robot
-
STINNER Victor
-
Terry J. Reedy
-
Yury V. Zaytsev