homepage

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.

New changeset 26d0a17affb5 by Ethan Furman in branch 'default':
issue22780: update NotImplemented description
https://hg.python.org/cpython/rev/26d0a17affb5 

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.

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.

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

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.

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 methods may return this value if they do not implement the
 operation for the operands provided. (The interpreter will then try the
 reflected operation, or some other fallback, depending on the operator.) Its
 truth value is true.

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.

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?

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?

You add a label before that section and then reference it with :ref:.

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

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

OK, you got me there :)

Whew!
If a different wording is better, I'm happy to change both places. :)

Here's the latest patch. Thoughts?

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 

Thank you, Berker.