Inplace dunders can return NotImplemented, and that's not documented

[Gouvernathor]

See this discussion.
Normal NotImplemented situation : A() + B() is resolved in A.__add__(A(), B()) which if returning NotImplemented, falls back to B.__radd__(B(), A()).
Now this behavior means there can be a double fallback : in a += b, if A.__iadd__ exists but returns NotImplemented, it will first fall back to A.__add__ and then to B.__radd__.
This is a great feature, but it's not currently documented.

Linked PRs

• gh-104219: Document that idunders can return NotImplemented #104220
• [3.12] gh-104219: Document that idunders can return NotImplemented (GH-104220) #116210
• [3.11] gh-104219: Document that idunders can return NotImplemented (GH-104220) #116211

[Gouvernathor]

For ye of little faith :

class A:
    def __init__(self, val):
        self.val = val
    def __str__(self):
        return f"A<{self.val}>"
    def __add__(self, other):
        print("add", self, other)
        return NotImplemented
    def __iadd__(self, other):
        print("iadd", self, other)
        return NotImplemented

class B:
    def __init__(self, val):
        self.val = val
    def __str__(self):
        return f"B<{self.val}>"
    def __radd__(self, other):
        print("radd", self, other)
        return NotImplemented

a, b = A("a"), B("b") then a += b calls the three methods in order (then fails).

[erlend-aasland]

Resolved by:

• gh-104219: Document that idunders can return NotImplemented #104220
• [3.12] gh-104219: Document that idunders can return NotImplemented (GH-104220) #116210
• [3.11] gh-104219: Document that idunders can return NotImplemented (GH-104220) #116211

(Auto-merge enabled for backports.)