Repository navigation
Not documented special names #67827
Description
| BPO | 23639 |
|---|---|
| Nosy | @birkenfeld, @rhettinger, @terryjreedy, @ezio-melotti, @merwok, @vadmium, @serhiy-storchaka, @IanLee1521 |
| Dependencies | |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2015-03-11.11:15:01.029>
labels = ['type-feature', 'docs']
title = 'Not documented special names'
updated_at = <Date 2015-09-02.18:13:56.514>
user = 'https://github.com/serhiy-storchaka'bugs.python.org fields:
activity = <Date 2015-09-02.18:13:56.514>
actor = 'serhiy.storchaka'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2015-03-11.11:15:01.029>
creator = 'serhiy.storchaka'
dependencies = ['14003', '15436', '22392', '22456']
files = ['39793']
hgrepos = []
issue_num = 23639
keywords = ['patch']
message_count = 7.0
messages = ['237859', '237860', '237886', '238005', '238063', '245716', '249385']
nosy_count = 10.0
nosy_names = ['georg.brandl', 'rhettinger', 'terry.reedy', 'peter.otten', 'ezio.melotti', 'eric.araujo', 'docs@python', 'martin.panter', 'serhiy.storchaka', 'IanLee1521']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23639'
versions = ['Python 3.4', 'Python 3.5', 'Python 3.6']
Activity
serhiy-storchaka commentedon Mar 11, 2015
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.
ezio-melotti commentedon Mar 11, 2015
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.
merwok commentedon Mar 11, 2015
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.
vadmium commentedon Mar 13, 2015
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-itself
__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-descriptors
type.__prepare__ → https://docs.python.org/dev/reference/datamodel.html#preparing-the-class-namespace
__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-examined
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_weaklistoffset
Others that are referenced by the documentation, but not explained anywhere that I can tell:
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).
terryjreedy commentedon Mar 14, 2015
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.
vadmium commentedon Jun 24, 2015
index-special.patch is a patch that adds index entries to the existing documentation that I found above.
rhettinger commentedon Aug 31, 2015
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.
erlend-aasland commentedon Jun 9, 2022
See also:
bharel commentedon Jul 6, 2022
Question is, which ones are supposed to be private and which ones aren't?
__signature__for example is documented in a PEP, but is it supposed to be private? public? only used for caching?skirpichev commentedon Dec 25, 2023
It's documented now:
https://docs.python.org/3.13/library/inspect.html#inspect.signature
olekskrav commentedon Nov 11, 2025
IMHO, it would be nice to have
__build_class__documentation somewhere and explain what this function does briefly, even if it's an implementation detail. (Thedismodule only mentions its existence.)Currently, the
execdocumentation mentions that you can control your builtins in globals, so one might want to exclude all builtins by doing the following:However, this will surprisingly fail with the following error:
NameError: __build_class__ not found.Maybe it should be mentioned at least in both the data model documentation that
__build_class__is used during the class creation (and hence can be customized), and also in theexec-function documentation that certain statements (likeclass) might fail if the corresponding built-in functions are missing.Maybe,
__build_class__could be also listed in the official list of built-ins.PS. An
importstatement would also fail inexec("...", globals=ns)without a global__import__method available, but__import__is at least a documented built-in function. It seems that__build_class__is the only undocumented built-in object.