classification
Title: Py_TPFLAGS_LONG_SUBCLASS is not documented
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, docs@python, pitrou, python-dev, vstinner, zaytsev
Priority: normal Keywords: patch

Created on 2010-07-19 17:50 by belopolsky, last changed 2014-04-28 23:39 by pitrou. This issue is now closed.

Files
File name Uploaded Description Edit
tpflags-doc.patch zaytsev, 2013-07-17 15:30 review
Messages (7)
msg110787 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-19 17:50
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.
msg110789 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-19 18:07
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.
msg110791 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-07-19 18:17
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.
msg110794 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-07-19 18:32
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().
msg193234 - (view) Author: Yury V. Zaytsev (zaytsev) Date: 2013-07-17 15:30
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.
msg217446 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-04-28 23:39
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
msg217447 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-04-28 23:39
This is committed, thank you.
History
Date User Action Args
2014-04-28 23:39:58pitrousetstatus: open -> closed
versions: + Python 3.4, - Python 3.1, Python 2.7, Python 3.2
messages: + msg217447

resolution: fixed
stage: needs patch -> resolved
2014-04-28 23:39:32python-devsetnosy: + python-dev
messages: + msg217446
2014-01-07 13:09:48vstinnersetnosy: + vstinner
2013-07-17 15:30:37zaytsevsetfiles: + tpflags-doc.patch

nosy: + zaytsev
messages: + msg193234

keywords: + patch
2011-03-09 02:13:19terry.reedysetnosy: belopolsky, pitrou, docs@python
versions: + Python 3.3
2010-07-19 18:32:20belopolskysetmessages: + msg110794
2010-07-19 18:17:23pitrousetnosy: + pitrou

messages: + msg110791
versions: + Python 3.1
2010-07-19 18:07:56belopolskysetnosy: belopolsky, docs@python
messages: + msg110789
components: + Library (Lib)
versions: + Python 2.7, Python 3.2
2010-07-19 17:55:29belopolskylinkissue5476 superseder
2010-07-19 17:50:21belopolskycreate