ENH: improve doctest class item discovery to include members

Feature or enhancement

Proposal:

>>> import numpy as np
>>> import doctest, pprint
>>> finder = doctest.DocTestFinder()
>>> pprint.pprint(finder.find(np.dtype))
[<DocTest dtype from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (11 examples)>,
 <DocTest dtype.__bool__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__class_getitem__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (2 examples)>,
 <DocTest dtype.__eq__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__ge__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__getitem__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__gt__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__hash__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__le__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__len__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__lt__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__mul__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__ne__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__repr__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__rmul__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.__str__ from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (no examples)>,
 <DocTest dtype.newbyteorder from /home/matti/oss/numpy/build-install/usr/lib/python3.11/site-packages/numpy/__init__.py:None (17 examples)>]

But this does not discover many other items in np.dtype.__dict__ since they are members:

>>> pprint.pprint([(v, type(v)) for k, v in np.dtype.__dict__.items() if k not in ('__doc__',) ])
[(<built-in method __new__ of numpy._DTypeMeta object at 0x74f8bcb40920>,
  <class 'builtin_function_or_method'>),
 (<slot wrapper '__repr__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__hash__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__str__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__lt__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__le__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__eq__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__ne__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__gt__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__ge__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__bool__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__len__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__getitem__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__mul__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<slot wrapper '__rmul__' of 'numpy.dtype' objects>,
  <class 'wrapper_descriptor'>),
 (<method '__reduce__' of 'numpy.dtype' objects>, <class 'method_descriptor'>),
 (<method '__setstate__' of 'numpy.dtype' objects>,
  <class 'method_descriptor'>),
 (<method 'newbyteorder' of 'numpy.dtype' objects>,
  <class 'method_descriptor'>),
 (<method '__class_getitem__' of 'numpy.dtype' objects>,
  <class 'classmethod_descriptor'>),
 (<member 'type' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<member 'kind' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<member 'char' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<member 'num' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<member 'byteorder' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<member 'itemsize' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<member 'alignment' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<member 'flags' of 'numpy.dtype' objects>, <class 'member_descriptor'>),
 (<attribute 'subdtype' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'descr' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'str' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'name' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'base' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'shape' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'ndim' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'isbuiltin' of 'numpy.dtype' objects>,
  <class 'getset_descriptor'>),
 (<attribute 'isnative' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'isalignedstruct' of 'numpy.dtype' objects>,
  <class 'getset_descriptor'>),
 (<attribute 'fields' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'metadata' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'names' of 'numpy.dtype' objects>, <class 'getset_descriptor'>),
 (<attribute 'hasobject' of 'numpy.dtype' objects>,
  <class 'getset_descriptor'>)]

I think the problem is here where only certain kinds of items are checked. Adding inspect.isdatadescriptor() I think would fix this.

Has this already been discussed elsewhere?

No response given

Links to previous discussion of this feature:

numpy/numpy#28002
scipy/scipy_doctest#178

DocTestFinder がどのクラス項目を検出するかを確認している Lib/doctest.py の 1064 行目付近から始めます。現在の項目チェックを、提案されている inspect.isdatadescriptor() の追加と比較し、リンクされた NumPy と SciPy の議論を確認します。既存の検出動作を壊すことなく、doctest の検出に該当するクラスメンバーが含まれれば完了です。