list.__add__ raises instead of returning NotImplemented

[Gouvernathor]

Bug report

list.__add__([], ()) raises a TypeError instead of returning NotImplemented

Your environment

• CPython versions tested on: "Python 3.11.2 (tags/v3.11.2:878ead1) [MSC v.1934 64 bit (AMD64)] on win32" (hope this helps)
• Operating system and architecture: Win10 64

I asked a question about this on Discourse, and tbh I only partially understood the answer but it still doesn't seem to square with what the documentation says.
To quote the section about __add__ :

If one of those methods does not support the operation with the supplied arguments, it should return NotImplemented.

The sentence seems clear enough, in my opinion, not to leave much room to interpretation about whether to consider this behavior a bug or not.
This seems to be an edge case failure of an optimization.

---

If this is not deemed to be an important bug, here is my use-case and why I believe it yields an inconsistent behavior (no need to read if you already think it's a bug).
I'm creating a frozenlist - a tuple that adds and equals with lists, basically - in an environment where there's a subclass of list called RevertableList. Little is necessary to know about it, apart that its __add__ is overridden but calls list.__add__.

Here is a short-ish reproducing code :

python_list = list

class RevertableList(list):
    def __add__(self, other):
        rv = list.__add__(self, other)
        if rv == NotImplemented:
            return rv
        return type(self)(rv)

    def __repr__(self):
        return type(self).__name__ + super().__repr__()

class frozenlist(tuple):
    __slots__ = ()

    def __eq__(self, other):
        if isinstance(other, frozenlist):
            return super().__eq__(other)
        elif isinstance(other, python_list):
            return super().__eq__(tuple(other))
        else:
            return False

    def __getitem__(self, key):
        rv = super().__getitem__(key)
        if isinstance(key, slice):
            return type(self)(rv)
        return rv

    def __add__(self, other):
        if isinstance(other, tuple) and not isinstance(other, frozenlist):
            return NotImplemented
        if isinstance(other, python_list):
            other = tuple(other)
        return type(self)(super().__add__(other))

    def __radd__(self, other):
        print("radd", other)
        if isinstance(other, python_list):
            return other + python_list(self)
        return NotImplemented

    def __mul__(self, other):
        return type(self)(super().__mul__(other))

    def __rmul__(self, other):
        return type(self)(super().__rmul__(other))

    def __repr__(self):
        return type(self).__name__ + super().__repr__()

# assert list.__add__(python_list(), ()) is NotImplemented # fails
assert RevertableList() + python_list() == RevertableList()
assert frozenlist() + python_list() == frozenlist()
assert python_list() + frozenlist() == python_list() # __radd__ gets called, triggers the print
assert python_list() + RevertableList() == python_list()
assert frozenlist() + RevertableList() == frozenlist()
assert RevertableList() + frozenlist() == RevertableList() # fails before __radd__ gets called

As you can see, RevertableList should behave like list in all but repr, direct type checking and maybe performances. However, the order in which methods get called is not the same, for no reason I was able to find in the doc.
NB : I know sometimes the datamodel allows for the method call to be reversed, calling __radd__ on the right object before trying __add__ on the left object, but 1) if it applied here it would save the bug from being triggered 2) RevertableList and frozenlist's only common base class is object, since frozenlist is not a real nor virtual subclass of list.

[rhettinger]

This behavior has been around for three decades. I say that we should let it be.

[ethanfurman]

According to the docs it's a bug. Bugs should be fixed.

[rhettinger]

You could just edit the docs to make a note. We are under no obligation to change long standing behavior especially given that no one else has ever cared about this before. The time is redesign an API is before it is deployed, not decades afterward. It the docs aren't correctly describing reality, then a simple doc edit is all that is warranted.

[Gouvernathor]

The behavior currently in the documentation is specified by PEP 208, which introduces the NotImplemented singleton. It's supposed to apply to "handling of numeric operations", which + definitely is (in my view). So, the design has been settled in the PEP, 20 years ago. The current behavior is an implementation mistake, failing to comply with the PEP, rather than an old design making sense in its own right which I would want to reform.
Im taking the liberty to mention @malemburg who wrote that PEP and answered in a Discuss thread where I was mentioning this behavior. Maybe you can share your view about this, Marc ?

Raymond, if you think the currently implemented API should be supported and documented, then how does that API work ? What's the rationale behind it, how does it make sense, how would you describe it in a hypothetical doc change ? I don't see another way than adding a warning block (like an implementation detail) for each exception to the described common behavior for each builtin type dunder. That looks messy.

Also, before choosing to change the doc, we should check how other implementations of Python work, maybe they did it the datamodel way, and in that case your solution would be asking them to change their implementation. I'll start looking in that direction myself but if someone has other Python implems close at hand, help would be welcome.
Update : Pypy does it the documented way, and returns NotImplemented.

[rhettinger]

Guido, I believe this may have been your code. Do you prefer to have it changed or to be documented as-is?

My recommendation is to leave it alone. This behavior is very old and until now, no one has ever had a need to change it. However, PyPy has apparently gone a different way and no one ever noticed until now.

If you do want it changed, do you want it to be treated as a bug and backported?

[gvanrossum]

I'd rather be left out of the loop for this.

[erlend-aasland]

You could just edit the docs to make a note. We are under no obligation to change long standing behavior especially given that no one else has ever cared about this before. The time is redesign an API is before it is deployed, not decades afterward. It the docs aren't correctly describing reality, then a simple doc edit is all that is warranted.

+1 to all Raymond has said in this issue. Restyled as a docs issue.

[Gouvernathor]

So, you want to document a behavior that has been ruled against 20 years ago by a PEP, and which is not supported in other implementations of Python, a behavior which - as far as I know, but feel free to show me wrong - is not supported by any cogent rationale within Python as it exists now (and has since that PEP) ; just because of precedent ?

It's probably far beyond my reach as it's written in C, but I don't think it would be very hard to transition this to regular behavior with a normal deprecation cycle, if you don't want to change that overnight.
Assuming the current code is equivalent to this:

def __add__(self, other, /):
    if isinstance(other, list):
        ...
    raise TypeError(f"can only concatenate list (not {type(other).__name__!r}) to list")

Just before the raise, it could check for the calling frame, using something like sys._getframe, and figure out whether the instruction that called it is a function call, or anything else.
And if so, emit a deprecation warning before raising the exception, or add a supplementary message to the exception, or both.
I must confess I'm not a pro of frame manipulation but shouldn't it be doable by accessing sys._getframe(1).f_code or f_lasti ? (or their C equivalent, obviously)
That processing would take a bit of time, but so does raising an exception anyway. And it would be relatively dirty, but accomodating obsolete behavior will be anyway.

Also, I don't think a majority of people here agree with you that this is only a doc issue and not a bug. @erlend-aasland please remove the "docs" tag.