[issue22780] NotImplemented doc section needs update
Roundup Robot added the comment: New changeset ebb8865dcf54 by Ethan Furman in branch '3.4': (3.4) Issue22780: reword NotImplemented docs to emphasise should https://hg.python.org/cpython/rev/ebb8865dcf54 New changeset b6ee02acaae9 by Ethan Furman in branch 'default': Issue22780: reword NotImplemented docs to emphasise should https://hg.python.org/cpython/rev/b6ee02acaae9 -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: Thank you, Berker. -- resolution: - fixed stage: patch review - resolved status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: Here's the latest patch. Thoughts? -- keywords: +patch stage: resolved - patch review Added file: http://bugs.python.org/file37254/issue22780.stoneleaf.01.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
R. David Murray added the comment: try the reflected operation is not our standard terminology. There is a reason I suggested *copying* the parenthetical statement. We essentially have two places where NotImplemented is described (language reference and library reference), and the parenthetical is the only substantial piece of information present in one that is not present in the other. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Changes by Arfrever Frehtes Taifersar Arahesis arfrever@gmail.com: -- nosy: +Arfrever ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: R. David Murray said: try the reflected operation is not our standard terminology. Parenthetical under discussion: --- (The interpreter will then try the reflected operation, or some other fallback, depending on the operator.) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
R. David Murray added the comment: OK, you got me there :) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: Whew! If a different wording is better, I'm happy to change both places. :) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: + Special value which should be returned by the special methods + (:meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, etc.) to indicate + that the operation is not implemented with respect to the other type. After a discussion on python-dev, I think this wording could be even clearer. How about: Special value which should be returned by the binary special methods (e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__rsub__`, etc.) to indicate that the operation is not implemented with respect to the other type; may be returned by the in-place binary special methods (e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose. -- status: closed - open ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
R. David Murray added the comment: Sounds OK to me. There should already be a discussion of the consequences of returning it (I don't remember where, though), and it would be nice to link to that discussion. Note that any doc change should be applied to 3.4 first, and then merged to 3.5. -- versions: +Python 3.4 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: I found these items: Doc/c-api/object.rst .. c:var:: PyObject* Py_NotImplemented The ``NotImplemented`` singleton, used to signal that an operation is not implemented for the given type combination. Doc/extending/newtypes.rst --- where the operator is one of ``Py_EQ``, ``Py_NE``, ``Py_LE``, ``Py_GT``, ``Py_LT`` or ``Py_GT``. It should compare the two objects with respect to the specified operator and return ``Py_True`` or ``Py_False`` if the comparison is successful, ``Py_NotImplemented`` to indicate that comparison is not implemented and the other object's comparison method should be tried, or *NULL* if an exception was set. Doc/Library/numbers.rst --- Implementing the arithmetic operations ~~ We want to implement the arithmetic operations so that mixed-mode operations either call an implementation whose author knew about the types of both arguments, or convert both to the nearest built in type and do the operation there. For subtypes of :class:`Integral`, this means that :meth:`__add__` and :meth:`__radd__` should be defined as:: class MyIntegral(Integral): def __add__(self, other): if isinstance(other, MyIntegral): return do_my_adding_stuff(self, other) elif isinstance(other, OtherTypeIKnowAbout): return do_my_other_adding_stuff(self, other) else: return NotImplemented def __radd__(self, other): if isinstance(other, MyIntegral): return do_my_adding_stuff(other, self) elif isinstance(other, OtherTypeIKnowAbout): return do_my_other_adding_stuff(other, self) elif isinstance(other, Integral): return int(other) + int(self) elif isinstance(other, Real): return float(other) + float(self) elif isinstance(other, Complex): return complex(other) + complex(self) else: return NotImplemented There are 5 different cases for a mixed-type operation on subclasses of :class:`Complex`. I'll refer to all of the above code that doesn't refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as boilerplate. ``a`` will be an instance of ``A``, which is a subtype of :class:`Complex` (``a : A : Complex``), and ``b : B : Complex``. I'll consider ``a + b``: 1. If ``A`` defines an :meth:`__add__` which accepts ``b``, all is well. 2. If ``A`` falls back to the boilerplate code, and it were to return a value from :meth:`__add__`, we'd miss the possibility that ``B`` defines a more intelligent :meth:`__radd__`, so the boilerplate should return :const:`NotImplemented` from :meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at all.) 3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts ``a``, all is well. 4. If it falls back to the boilerplate, there are no more possible methods to try, so this is where the default implementation should live. 5. If ``B : A``, Python tries ``B.__radd__`` before ``A.__add__``. This is ok, because it was implemented with knowledge of ``A``, so it can handle those instances before delegating to :class:`Complex`. Doc/library/datetime.rst In other words, ``date1 date2`` if and only if ``date1.toordinal() date2.toordinal()``. In order to stop comparison from falling back to the default scheme of comparing object addresses, date comparison normally raises :exc:`TypeError` if the other comparand isn't also a :class:`date` object. However, ``NotImplemented`` is returned instead if the other comparand has a :meth:`timetuple` attribute. This hook gives other kinds of date objects a chance at implementing mixed-type comparison. If not, when a :class:`date` object is compared to an object of a different type, :exc:`TypeError` is raised unless the comparison is ``==`` or ``!=``. The latter cases return :const:`False` or :const:`True`, respectively. Doc/reference/expressions.rst - Comparisions ... Comparison of objects of differing types depends on whether either of the types provide explicit support for the comparison. Most numeric types can be compared with one another. When cross-type comparison is not supported, the comparison method returns ``NotImplemented``. Ahha! I think I found it (nearly at the end, of course): Doc/reference/datamodel.rst --- The standard type hierarchy === ... NotImplemented .. index:: object: NotImplemented This type has a single value. There is a single object with this value. This object is accessed through the built-in name ``NotImplemented``. Numeric methods and rich comparison
[issue22780] NotImplemented doc section needs update
R. David Murray added the comment: I was actually thinking of the Implementing the arithmetic operations section. Maybe we should copy the parenthetical from the datamodel description into the text you are modifying, and then link to the implementing section. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Raymond Hettinger added the comment: FWIW, I think doc changes like this need to be made by the people most familiar with the implementation details and with the original design intent (i.e. the authors of PEP 207). The knowledge here is fragile and it would be easy to accidentally make-up new normative rules that aren't actually true or necessary, or to subtly misrepresent what was trying to be accomplished originally. The risk is greatest when the OP is just now learning the ins and outs of NotImplemented (i.e. whether in-place operations can or should return NotImplemeted or whether those operations can be duck typed). Changing can be returned to should be returned is normative (making-up a new rule without sufficient discussion). This doesn't add explanation; instead, instead, it make a rule change about how a feature should be used. https://hg.python.org/cpython/rev/26d0a17affb5 -- nosy: +gvanrossum, rhettinger, tim.peters ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Changes by Raymond Hettinger raymond.hettin...@gmail.com: -- Removed message: http://bugs.python.org/msg230579 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: Thank you, Raymond, both for your concern and your discretion. My interest in changing the can or may to should is that, whatever the original intent of the PEP, the way Python works /now/ is that any class that doesn't return NotImplemented when it /should/ is not going to interoperate well with other compatible classes. At the heart of the issue is what happens when def bin_op(self, other): ... is called, but the left-hand operand doesn't know how to work with the right-hand operand? We have three choices: - do nothing, letting any exceptions boil up or errors propagate - do a check on 'other' to determine if it's usable, and raise an exception if it is not - do a check on 'other' to determine if it's usable, and return NotImplemented if it is not Only the last choice allows 'other' to also try the operation. Except for the special-case of in-place bin-ops, why would we not want choice three? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: How about: Special value which should be returned by the binary special methods (e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__rsub__`, etc.) to indicate that the operation is not implemented with respect to the other type; may be returned by the in-place binary special methods (e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose. Its truth value is true. Note:: When NotImplemented is returned, the interpreter will then try the reflected operation on the other type, or some other fallback, depending on the operator. If all attempted operations return NotImplemented, the interpreter will raise an appropriate exception. I have no idea how to create a link to the 'Implementing the arithmetic operations' section. Any clues? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Georg Brandl added the comment: You add a label before that section and then reference it with :ref:. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Ethan Furman added the comment: Here's the actual change: + Special value which should be returned by the special methods + (:meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, etc.) to indicate + that the operation is not implemented with respect to the other type. I'll update the Enum docs as well. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
New submission from Ethan Furman: https://docs.python.org/3/library/constants.html current --- Special value which can be returned by the “rich comparison” special methods (__eq__(), __lt__(), and friends), to indicate that the comparison is not implemented with respect to the other type. more accurate - Special value which should be returned by the __dunder__ methods to indicate the requested operation is not implemented with respect to the other type. -- messages: 230412 nosy: eric.araujo, ethan.furman, ezio.melotti, georg.brandl priority: normal severity: normal stage: needs patch status: open title: NotImplemented doc section needs update ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Roundup Robot added the comment: New changeset 26d0a17affb5 by Ethan Furman in branch 'default': issue22780: update NotImplemented description https://hg.python.org/cpython/rev/26d0a17affb5 -- nosy: +python-dev ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
Changes by Ethan Furman et...@stoneleaf.us: -- stage: needs patch - resolved status: open - closed versions: +Python 3.5 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue22780] NotImplemented doc section needs update
R. David Murray added the comment: The replacement of the term 'special methods' and the examples with the jargon (used nowhere else in the docs that I'm aware of) of '__dunder__' makes the text very confusing. Please restore 'special methods' and the examples...you could include non-comparision methods in the list of examples. Oh, I see, you use __dunder__ in the enum docs as well. It should be replaced with our standard terminology there, as well. -- nosy: +r.david.murray ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue22780 ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
