Rename `EndpointAPI.subscribe` to be `EndpointAPI.add_event_handler`

[pipermerriam]

What is wrong

We have two concepts that both use the term subscription.

• The set of endpoint types that a given endpoint cares about
• The EndpointAPI.subscribe concept

How can it be fixed

I think that we might benefit from changing EndpointAPI.subscribe to be EndpointAPI.add_event_handler

This makes it alight with the internal nomenclature we use and separates it from the other subscriptions concept.

[cburgdorf]

The minor downside with that name is that add_event_handler kinda suggests there would also be a remove_event_handler which isn't the case as instead the API returns you a handle to unsubscribe. That is for a good reason (e.g to allow to unsubscribe even when a lambda was used or we can't - for whatever reasons - hold on to the original handler being used).

Alternatives:

• on_event
• on
• with_handler
• ???

[pipermerriam]

??? not sure I like this but it might make sense.

handle = endpoint.add_event_handler(MyEvent, do_thing_with_event)

# this is the primary API
endpoint.remove_event_handler(handle)
# this is convenience that delegates to the above statement
handle.remove()

I could get onboard with on_event

[cburgdorf]

Not a fan of this tbh. It introduces some inconsistency. Now you have:

def add_event_handler(self, event_type: Type[BaseEvent], handler: Callable[[BaseEvent], None])
   ...

vs

def remove_event_handler(self, event_type: Type[BaseEvent], handle: UnsubscribeHandle)
   ...

The naming suggest that the following would work:

def handler(event: BaseEvent):
    pass

event_bus.add_event_handler(handler)
event_bus.remove_event_handler(handler)

I mean, we could make the above possible since in this case you can hold on to the handler but then in the lambda case you would be back to this:

handle = event_bus.add_event_handler(lambda _: None)
event_bus.remove_event_handler(handle)

So, this would leave us with an implementation that looks like this:

def remove_event_handler(self, event_type: Type[BaseEvent], handle: Union[UnsubscribeHandle, Callable[[BaseEvent], None]])
   ...

I think I'd rather like to find a name that simple doesn't convey the add/ remove symmetry.

Could be on_event but maybe we find something more suitable. How about:

• receive
• receive_event
• observe
• observe_event
• listen
• listen_for