Unsure if an IntEnum is better than supporting plain strings “left” etc.

Pro:

• Supports completion

Con:

• quite verbose because of the qualified name
• everywhere else we currently use strings for enums (API consistency)

While we do use strings everywhere, I find them typo-prone: you get an error if you write event.button is MouseButton.lef, but nothing if you write event.button == "lef". (I don't personally care much about completion, but I guess it's important for some.)
It would also be a pretty gratuitous API break to switch to strings...

With „get“ you mean your IDE or a linter? Both should fail at runtime.

Of course, the plain ints have to stay. Similar to the loc parameter.

With „get“ you mean your IDE or a linter? Both should fail at runtime.

I mean at runtime. is MouseEvent.lef will get you an AttributeError, == "lef" will silently return false.

Of course, the plain ints have to stay. Similar to the loc parameter.

Then it's not clear what the proposed alternative change is.

On Linux scrolling is button 4/5, though I don't know how much that translates to the toolkits.

Qt and GTK handle button presses completely separately from scrolls (different C-level structures / event handlers):
http://doc.qt.io/qt-5/qmouseevent.html
http://doc.qt.io/qt-5/qwheelevent.html
https://developer.gnome.org/gdk3/stable/gdk3-Event-Structures.html#GdkEventButton
https://developer.gnome.org/gdk3/stable/gdk3-Event-Structures.html#GdkEventScroll

wx handles both as MouseEvents:
https://wxpython.org/Phoenix/docs/html/wx.MouseEvent.html#wx-mouseevent

I think(?) Tk handles everything as strings anyways...
https://www.tcl.tk/man/tcl/TkCmd/bind.htm#M7

is MouseEvent.lef will get you an AttributeError, == "lef" will silently return false.

Yes that's true and I agree that's a benefit. However, in this particular case I propose that it's not worth the additional verbosity and API inconsistency (in particular since we already have "up" and "down" strings).

Then it's not clear what the proposed alternative change is.

Current solution:

button : {None, 1, 2, 3, 'up', 'down'}

Alternative proposed in this PR:

button : {None, MouseButton.LEFT, MouseButton.MIDDLE, MouseButton.RIGHT, \
'up', 'down'}

My preferred alternative:

button : {None, 1, 2, 3, 'left', 'middle', 'right', 'up', 'down'}

I think I see the source of the confusion. You are (I believe?) thinking about the signature of the Event constructor, but that doesn't really matter -- in practice it must be exceptionally rare for end users to construct Events themselves (except for some mocking purposes, which I've done, but again that's not the main point). The main place where end users see events is the instance that's passed to them in eventhandlers (canvas.mpl_connect("button_press_event", lambda event: <do-something-with-event>)).
Now that event has a button attribute, and we need to decide whether it's 1 (current status) or MouseButton.LEFT (this PR) or "left" (as you propose). Changing it from 1 to MouseButton.LEFT doesn't break any API, because MouseButton is an IntEnum, so behaves like an int in any reasonable way (except explicit type equality checks); changing it to "left" would break any event handler that starts with if event.button == 1: ....

I see. In that context it's ok to use an enum. Still, it's unfortunate that we currently already have an inconsistent API.

I’m pretty sure another point in favor of using ints/IntEnum is that equality is faster for ints/enums than strings.

Personally, I’m not a huge fan of using a set of strings for input parameters.

Actually I'm warming up to the idea of making MouseButton an Enum and override __eq__ to work for with 1/2/3 and "up"/"down". That means that really funky use cases such as event.button + 1 or event.button.upper() won't work anymore but heh... Thoughts?

I’m pretty sure another point in favor of using ints/IntEnum is that equality is faster for ints/enums than strings.

The difference in string vs int equality comparison should be absolutely negligible in this context.

Just to prove:

In [1]: def foo(a):
   ...:     return a == 1
   ...: 

In [2]: %timeit foo(2)
62.8 ns ± 0.136 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)

In [3]: def bar(a):
   ...:     return a == "left"
   ...: 
   ...: 

In [4]: %timeit bar('left')
65.5 ns ± 0.162 ns per loop (mean ± std. dev. of 7 runs, 10000000 loops each)

I'm fine with an IntEnum. It's not making it worse compared to now.

Not sure if an Enum with an overloaded __eq__ is too clever. OTOH it would unify the API while maintaining basic compatibility. The funky usecases are rather an abuse and already now each would only work for a subset of current MouseButton values. I wouldn't worry about them.

The funky usecases are rather an abuse and already now each would only work for a subset of current MouseButton values.

Well, you don't seem them in the same event handlers: buttons go to the button_press_event and scrolls to the scroll_event.

You could of course overload __str__ and __add__ as well 😄 . But no, let's keep it simple and just introduce the IntEnum unless somebody else advocates the more sophisticated solution.

• everywhere else we currently use strings for enums (API consistency)

This is something I am in favor of addressing over time (and moving to more enums).

Thoughts about just moving to Enum and override __eq__? I guess then we could make up/down be 4/5 to match the X model (while still being "equal" to "up"/"down", and they get a nice repr so no one gets confused...).

Thoughts about just moving to Enum and override eq?

I think we have to use something like this. Also, when we think about moving to enums in other places that accept strings so far, this would be the way to keep backward compatibility.

@tacaswell "moving to more enums". Is that intended

• mainly for internal use?
• an addition to the API and enum values are equally supported as strings.
• a replacement for string parameters, which would be deprecated and removed in the long term?

@tacaswell or @dopplershift either of you want to do the second review?

Ready to merge it? :)