[docs] [issue31042] Inconsistency in documentation of operator.index

[Terry J. Reedy]

Terry J. Reedy added the comment:

To me, 'roughly' is wrong.  Either the equivalence is exact, or it is completely absent .  There is no 'nearly' or 'roughly' about this situation.

This is difference from  iterator_class_x(args) being mathematically equivalent to generator_function_y(args) in the sense of yielding *exactly* the same sequence of objects, but being different in the Python sense that type(iterator_class_x) != type(generator_function_y).  

Note: even in this case, I was once in favor of changing 'equivalent' to 'roughly equivalent' in the itertools doc.  I now regret that because 'roughly' could be misunderstood.  I think that 'mathematically equivalent' or 'equivalent when iterated' or 'equivalent*' would be better, with an explanatory note at the top.

As for this issue, __index__ is a reserved name.  https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers

a.__index__ = <whatever> is an unauthorized use of a *reserved* word and the effect of such usage is not and need not be documented.  

The entry for __*__ does include "*Any* use of __*__ names, in any context, that does not follow explicitly documented use, is subject to breakage without warning."  To me, that says that the effect of the reserved-word assignment is undefined.  It could be made to raise an exception.

To be even clearer, I believe we should explicitly state what I consider implicit: something like "Any such use breaks these manuals, in the sense that it may make statements herein untrue.  These manuals assume that reserved names are used as specified."

----------
nosy: +terry.reedy
stage:  -> needs patch
type:  -> enhancement
versions:  -Python 3.3, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue31042>
_______________________________________