[issue23639] Not documented special names

[Serhiy Storchaka]

Changes by Serhiy Storchaka :


--
dependencies: +Clarify documentation of __getinitargs__, __self__ on built-in 
functions is not as documented

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Raymond Hettinger]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Martin Panter]

Changes by Martin Panter vadmium...@gmail.com:


--
dependencies: +__base__ undocumented
stage: needs patch - patch review

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Terry J. Reedy]

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 rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Ian Lee]

Changes by Ian Lee ianlee1...@gmail.com:


--
nosy: +IanLee1521

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Martin Panter]

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-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).

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Éric Araujo]

É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 rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Peter Otten]

Changes by Peter Otten __pete...@web.de:


--
nosy: +peter.otten

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Serhiy Storchaka]

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 rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Ezio Melotti]

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 rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Serhiy Storchaka]

Changes by Serhiy Storchaka storch...@gmail.com:


--
dependencies: +__sizeof__ is not documented

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue23639] Not documented special names

[Martin Panter]

Changes by Martin Panter vadmium...@gmail.com:


--
nosy: +vadmium

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue23639
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com