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.