classification
Title: Not documented special names
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: open Resolution:
Dependencies: 14003 15436 22392 22456 Superseder:
Assigned To: docs@python Nosy List: IanLee1521, docs@python, eric.araujo, ezio.melotti, georg.brandl, martin.panter, peter.otten, rhettinger, serhiy.storchaka, terry.reedy
Priority: normal Keywords: patch

Created on 2015-03-11 11:15 by serhiy.storchaka, last changed 2015-09-02 18:13 by serhiy.storchaka.

Files
File name Uploaded Description Edit
index-special.patch martin.panter, 2015-06-24 04:14 Index existing documentation review
Messages (7)
msg237859 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-11 11:15
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.
msg237860 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-03-11 12:00
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.
msg237886 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2015-03-11 16:36
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.
msg238005 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-03-13 03:36
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:

* 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).
msg238063 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2015-03-14 00:05
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.
msg245716 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-06-24 04:14
index-special.patch is a patch that adds index entries to the existing documentation that I found above.
msg249385 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-08-31 06:49
> 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.
History
Date User Action Args
2015-09-02 18:13:56serhiy.storchakasetdependencies: + __self__ on built-in functions is not as documented, Clarify documentation of __getinitargs__
2015-08-31 06:49:58rhettingersetnosy: + rhettinger
messages: + msg249385
2015-08-31 04:54:43martin.pantersetdependencies: + __base__ undocumented
stage: needs patch -> patch review
2015-06-24 04:14:44martin.pantersetfiles: + index-special.patch
keywords: + patch
messages: + msg245716

versions: + Python 3.6
2015-03-14 00:05:19terry.reedysetnosy: + terry.reedy
messages: + msg238063
2015-03-13 07:21:50IanLee1521setnosy: + IanLee1521
2015-03-13 03:36:43martin.pantersetmessages: + msg238005
2015-03-11 23:38:57martin.pantersetnosy: + martin.panter
2015-03-11 16:45:25peter.ottensetnosy: + peter.otten
2015-03-11 16:36:13eric.araujosetmessages: + msg237886
2015-03-11 12:02:40serhiy.storchakasetdependencies: + __sizeof__ is not documented
2015-03-11 12:00:10ezio.melottisettype: enhancement
messages: + msg237860
2015-03-11 11:15:01serhiy.storchakacreate