API: make '+' and '-' for Index either do numeric operations of raise TypeError (instead of setops)

[jreback]

see comments at the end of #8184

so this type of syntax

index1 + index2
would be replaced by
index1.union(index2)

and

index1 - index2
by
index1.diff(index2)

Their is some internal code to fix but not a lot.

This would go a long ways toward simplifying the user API for index ops. I think.

[jreback]

cc @shoyer
@TomAugspurger @cpcloud @jorisvandenbossche
cc @immerrr
cc @sinhrks

[jreback]

can easily just deprecate this in 0.15.0 (and then start raising in say 0.16.0), or could raise in 0.15.0.

[shoyer]

+1 from me (obviously, this was sort of my idea).

There are a few other issues where this has come up (including a bug report/complaint) but I can't find them now.

[jreback]

I have a PR for this, its really a tiny change (internally was only used in 2 routines). I honestly don't think its a bit deal.

Still open to simply warn (rather than raise) though (or can just break it).

[immerrr]

It makes sense to make set operations secondary to arithmetics, so +1 from me as well.

As for warn/raise, I'd say a graceful deprecation (a pre-change warning for one release and then a post-change for another one on a second thought, disregard that last part) would prevent some user rants. I recall using set difference somewhere in my code in the past so my own code would probably break after the change and I'd love a heads-up before that.

[jorisvandenbossche]

I think this should be deprecated first (warning), as this really breaks your code and is used (I used it myself also), how strange it could be at first sight.

But I see a point in making this less confusing.

Some questions:

• the idea is to disallow - and + (raise an error) in the future? Or do you want to allow it as arithmethic operation? (as you want to do for the datetime and timedelta index?)
• to wrap up: compared to python's built-in set, the only difference after this change would be that - does not work as it does with sets? (as + does not work as union for sets as it did for index)
• to make it even more consistent, we could also deprecate & and alike, as these also do something different when applied on a series (and then only leave the method versions)
• maybe something not that related: is there some support for renaming diff to difference? (or at least start with having that alias and using that in the docs). That Series.diff and Index.diff do something completely different, that's something I have found very confusing in the past.

[TomAugspurger]

Agree with the spirit of the PR and that we should warn for a release or two.

@jorisvandenbossche I think + and - will always do arithmetic ops. Then idx.union and idx.diff are for setops.

What does & do on series? And if we deprecate & do we get rid of ^ as well? I think that one is unambiguous.

[jreback]

• now + and - for an Index and a scalar are add and subtract. This will now be consistent for indexes for which this makes sense (eg. DatetimeIndex + TimedeltaIndex and DatetimeIndex - DatetimeIndex but not DatetimeIndex + DatetimeIndex). Numeric like indexes can easily support this (it is disabled ATM, but just need tests and trivial to implement), for example Int64Index + Float64Index. These make everything more Series like and natural
• will change to a warning - easy enough
• difference from python set: well sets support both union (+) and difference (-) so Indexes will only by set-like for the boolean operators (&,|,^). I don't think this should change (you are right can reavaluate in the future)
• I am ok with diff -> difference. Will make that change as well (and warn on the original).