[issue23639] Not documented special names
New submission from Serhiy Storchaka: Here are lists of special names used in Python core and the stdlib, but absent in documentation index. Module level names used in pydoc: __author__ __credits__ __date__ __version__ Module level name used in doctest: __test__ Other module level names: __about__ (heapq only) __copyright__ (many modules) __cvsid__ (tarfile only) __docformat__ (doctest only) __email__ (test_with and test_keywordonlyarg only) __libmpdec_version__ (decimal only) __status__ (logging only) type attributes (mostly used in tests): __abstractmethods__ (used in abc, functools) __base__ __basicsize__ __dictoffset__ __flags__ (used in inspect, copyreg) __itemsize__ __weakrefoffset__ super() attributes: __self_class__ __thisclass__ Used in sqlite: __adapt__ __conform__ Used in ctypes: __ctype_be__ __ctype_le__ __ctypes_from_outparam__ Used in unittest: __unittest_expecting_failure__ __unittest_skip__ __unittest_skip_why__ float methods, for testing: __getformat__ __setformat__ Used in IDLE RPC: __attributes__ __methods__ Others: __alloc__ (bytearray method) __args__ (used in bdb) __build_class__ (builtins function, used in eval loop) __builtins__ (module attribute) __decimal_context__ (used in decimal) __exception__ (used in pdb) __getinitargs__ (used in pickle, datetime) __initializing__ (used in importlib) __isabstractmethod__ (function/method/descriptor attribute, used in abc, functools, types) __ltrace__ (used in eval loop, never set) __members__ (Enum attribute, used in many modules) __mp_main__ (used in multiprocessing) __new_member__ (Enum attribute, used in enum internally) __newobj__ (copyreg function, used in pickle, object.__reduce_ex__) __newobj_ex__ (copyreg function, used in pickle, object.__reduce_ex__) __objclass__ (descriptor/enum attribute, used in inspect, pydoc, doctest, multiprocessing) __prepare__ (metaclass method, used in builtins.__build_class__, types) __pycache__ (cache directory name) __return__ (used in pdb) __signature__ (used in inspect, never set) __sizeof__ (standard method, used in sys.getsizeof) __slotnames__ (used in object.__getstate__ for caching) __text_signature__ (function/method/descriptor attribute, used in inspect) __trunc__ (used in math.trunc, int, etc) __warningregistry__ (used in warnings) __weakref__ (used in weakref) __wrapped__ (used in inspect, functools, contextlib, asyncio) Needed a patch or a set of patches that will add theses names to the index and document them if they are not documented. ---------- assignee: docs@python components: Documentation messages: 237859 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Not documented special names versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Ezio Melotti added the comment: I think most of these are either implementation details or "private" names, so there is no need to document them. The ones that are intended to be used by developers or that are useful to understand the functioning of a public API should be documented. If these names are already in the documentation but not in the index, then an index entry should be added. ---------- type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +__sizeof__ is not documented _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Éric Araujo added the comment: I think like Ezio does. Python covers itself by saying that all names starting and ending with two underscores are reserved, and documents those that are interesting for users. On the other hand, many third-party frameworks/libs/apps invent their own __names__ (often for metadata, sometimes for custom protocols); I don’t know if a full list of existing names in the doc would have dissuaded them. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Peter Otten <__peter__@web.de>: ---------- nosy: +peter.otten _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- nosy: +vadmium _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Martin Panter added the comment: Some of these that I believe are at least partially documented, so could be added to the index. But the index for these is not very good anyway, because they are listed in a funny (ASCII-betical?) order in a special section called “symbols”, rather than alphabetically as you would expect. But that would be a separate issue. Potential index entries: builtins.__build_class__() → https://docs.python.org/dev/library/dis.html#opcode-LOAD_BUILD_CLASS __builtins__ global variable → https://docs.python.org/dev/reference/executionmodel.html#naming-and-binding __conform__() method → https://docs.python.org/dev/library/sqlite3.html#letting-your-object-adapt-i... __isabstractmethod__ → https://docs.python.org/dev/library/abc.html#abc.abstractmethod Enum.__members__ → https://docs.python.org/dev/library/enum.html#iteration __objclass__ → https://docs.python.org/dev/reference/datamodel.html#implementing-descriptor... type.__prepare__ → https://docs.python.org/dev/reference/datamodel.html#preparing-the-class-nam... __pycache__/ directory → https://docs.python.org/dev/tutorial/modules.html#compiled-python-files object.__signature__ → https://docs.python.org/dev/library/inspect.html#inspect.unwrap object.__sizeof__() → https://docs.python.org/dev/library/sys.html#sys.getsizeof module.__test__ → https://docs.python.org/dev/library/doctest.html#which-docstrings-are-examin... Real.__trunc__ → https://docs.python.org/dev/library/math.html#math.trunc module.__warningregistry__ → https://docs.python.org/dev/library/warnings.html#warnings.warn_explicit object.__weakref__ → https://docs.python.org/dev/c-api/typeobj.html#c.PyTypeObject.tp_weaklistoff... Others that are referenced by the documentation, but not explained anywhere that I can tell: * module.__version__, referenced as an attribute in a few modules and also in sample code * __getformat__(), __setformat__(), __getinitargs__() methods, referenced in “unittest.mock” documentation Regarding __base__, I always assumed this was a leftover from Python 2 from some time before multiple inheritance, so maybe __bases__ could be used instead now (unless testing backwards compatibility). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Ian Lee <ianlee1521@gmail.com>: ---------- nosy: +IanLee1521 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Terry J. Reedy added the comment: Idlelib.rpc uses the somewhat arbitrary *strings* '__methods__' and '__attributes__' as private signals in its protocol. They are not object or attribute names, special or otherwise, in the sense used here. The use of '__methods__' in idlelib.rpc (line 176) harkens back to pre 2.2 days when __methods__ was officially used in the type introspection api. That class attribute was "a list of method names supported by the object.". See PEP 252. Its complement was __members__, a list of non-method attributes (other than itself, I presume). rpc uses '__attributes__' instead. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Martin Panter added the comment: index-special.patch is a patch that adds index entries to the existing documentation that I found above. ---------- keywords: +patch versions: +Python 3.6 Added file: http://bugs.python.org/file39793/index-special.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- dependencies: +__base__ undocumented stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Raymond Hettinger added the comment:
I think most of these are either implementation details or "private" names, so there is no need to document them.
Also, we want to be careful to not guarantee implementation details that are subject to change. Most of these are not intended for users to base their code on. IIRC, Guido already opined on some of these (preferring to keep most of them undocumented) in some other tracker item this year. As one data point, I worked on the decimal module and defined the public API. The __decimal_context__ method is not part of the public API. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Clarify documentation of __getinitargs__, __self__ on built-in functions is not as documented _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Ezio Melotti added the comment: I think most of these are either implementation details or "private" names, so there is no need to document them. The ones that are intended to be used by developers or that are useful to understand the functioning of a public API should be documented. If these names are already in the documentation but not in the index, then an index entry should be added. ---------- type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +__sizeof__ is not documented _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Éric Araujo added the comment: I think like Ezio does. Python covers itself by saying that all names starting and ending with two underscores are reserved, and documents those that are interesting for users. On the other hand, many third-party frameworks/libs/apps invent their own __names__ (often for metadata, sometimes for custom protocols); I don’t know if a full list of existing names in the doc would have dissuaded them. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Peter Otten <__peter__@web.de>: ---------- nosy: +peter.otten _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- nosy: +vadmium _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Martin Panter added the comment: Some of these that I believe are at least partially documented, so could be added to the index. But the index for these is not very good anyway, because they are listed in a funny (ASCII-betical?) order in a special section called “symbols”, rather than alphabetically as you would expect. But that would be a separate issue. Potential index entries: builtins.__build_class__() → https://docs.python.org/dev/library/dis.html#opcode-LOAD_BUILD_CLASS __builtins__ global variable → https://docs.python.org/dev/reference/executionmodel.html#naming-and-binding __conform__() method → https://docs.python.org/dev/library/sqlite3.html#letting-your-object-adapt-i... __isabstractmethod__ → https://docs.python.org/dev/library/abc.html#abc.abstractmethod Enum.__members__ → https://docs.python.org/dev/library/enum.html#iteration __objclass__ → https://docs.python.org/dev/reference/datamodel.html#implementing-descriptor... type.__prepare__ → https://docs.python.org/dev/reference/datamodel.html#preparing-the-class-nam... __pycache__/ directory → https://docs.python.org/dev/tutorial/modules.html#compiled-python-files object.__signature__ → https://docs.python.org/dev/library/inspect.html#inspect.unwrap object.__sizeof__() → https://docs.python.org/dev/library/sys.html#sys.getsizeof module.__test__ → https://docs.python.org/dev/library/doctest.html#which-docstrings-are-examin... Real.__trunc__ → https://docs.python.org/dev/library/math.html#math.trunc module.__warningregistry__ → https://docs.python.org/dev/library/warnings.html#warnings.warn_explicit object.__weakref__ → https://docs.python.org/dev/c-api/typeobj.html#c.PyTypeObject.tp_weaklistoff... Others that are referenced by the documentation, but not explained anywhere that I can tell: * module.__version__, referenced as an attribute in a few modules and also in sample code * __getformat__(), __setformat__(), __getinitargs__() methods, referenced in “unittest.mock” documentation Regarding __base__, I always assumed this was a leftover from Python 2 from some time before multiple inheritance, so maybe __bases__ could be used instead now (unless testing backwards compatibility). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Ian Lee <ianlee1521@gmail.com>: ---------- nosy: +IanLee1521 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Terry J. Reedy added the comment: Idlelib.rpc uses the somewhat arbitrary *strings* '__methods__' and '__attributes__' as private signals in its protocol. They are not object or attribute names, special or otherwise, in the sense used here. The use of '__methods__' in idlelib.rpc (line 176) harkens back to pre 2.2 days when __methods__ was officially used in the type introspection api. That class attribute was "a list of method names supported by the object.". See PEP 252. Its complement was __members__, a list of non-method attributes (other than itself, I presume). rpc uses '__attributes__' instead. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Martin Panter added the comment: index-special.patch is a patch that adds index entries to the existing documentation that I found above. ---------- keywords: +patch versions: +Python 3.6 Added file: http://bugs.python.org/file39793/index-special.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- dependencies: +__base__ undocumented stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Raymond Hettinger added the comment:
I think most of these are either implementation details or "private" names, so there is no need to document them.
Also, we want to be careful to not guarantee implementation details that are subject to change. Most of these are not intended for users to base their code on. IIRC, Guido already opined on some of these (preferring to keep most of them undocumented) in some other tracker item this year. As one data point, I worked on the decimal module and defined the public API. The __decimal_context__ method is not part of the public API. ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Clarify documentation of __getinitargs__, __self__ on built-in functions is not as documented _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23639> _______________________________________
participants (8)
-
Ezio Melotti -
Ian Lee
-
Martin Panter
-
Peter Otten
-
Raymond Hettinger
-
Serhiy Storchaka
-
Terry J. Reedy
-
Éric Araujo