Operator overloading always looks like a clean solution, but complexity finds a way to leak through.

Avoid it, unless you're really overloading things that always behave.

Is it really overloading that's the problem here? Even if you used method names to do this, you'd still have to deal with the fact that the operation being performed is non-commutative.

I don't know that there is a way of expressing such a restriction even if you were using dependent types in such a way as to prevent shooting yourself in the foot here. Possibly you could not implement the month or year span elements altogether and only allow addition of days or seconds?

But nested method calls don't imply commutativity while addition does. So the code is misleading.

I don't follow. How do nested method calls fail to imply commutativity?

For example, using psuedo-Haskell notation:

    (+):: Int -> Int -> Int

    ; ncc short for non commutative combination
    ncc:: Time -> Time -> Time

    1 + 2 + 3

    ncc 03:00 (ncc 10:00 02:00)

It could be just me but I would expect something that looks like an addition to be commutative but not arbitrary function calls. But I see what you mean that the types are not much of a help here.

Agreed. Operator overloading of arithmetic is used as the tutorial example with complex numbers. But its utility starts and ends there.

I overload conversions of type, to simplify argument passing. Maybe I shouldn't even do that.

Vectors, Matrices count too I think.

There are some exceptions. For geometric primitives such as matrix addition I might allow it. For complex container types like a "month," it's definitely a show-stopper.

what are some specific disadvantages of operator overloading in the instance of subtracting or adding months together?

It's actually a pretty bad example, apologies. Python ships with a standard library that includes modules such as datetime, timedelta, and calendar. I've been guilty of using all of them.

I can say that when your date math becomes complex enough you might want to consider avoiding them and doing the calculations yourself. In a recent project I had to integrate several systems that stored metering data in UTC with various databases in different local time zones for the purposes of billing on that data. I can say that doing the math is easier and more clear than using objects that encapsulate the data in such complex scenarios.

There is no hard-and-fast rule for me to determine when operator-overloading is inappropriate. I only have a few "smells" I use that raise the hairs on the back of my neck when I encounter them:

1. If your object has one or more boolean members

2. If your operator has to dispatch on more than 1 type

3. If your operator breaks any of the associated identities

Any of these are just warnings. In the case of matrix addition it breaks the Commutative identity of addition but is a well-defined and known property of the operator for anyone who would be reading code involving those kinds of objects that it can be justified. Dates might be defined-enough but intuition clearly get the best of the OP.

It's just a trade-off that I haven't found valuable outside of certain special cases.