[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