issue #710 : add event list and or operator

[sdesrozis]

Fixes #710

Description:

Add an event list class to pack events which could be added with operator | on Events and CallableEventWithFilter

User code is

    def fn(e, b):
        pass

    trainer = Engine(fn)

    @trainer.on(Events.ITERATION_STARTED(once=1) | Events.ITERATION_STARTED(every=3) | Events.COMPLETED)
    def execute_some_handler(engine):
        print(engine.state.iteration)

    trainer.run(range(3), max_epochs=5)

TODO : improve doc

Check list:

• New tests are added (if a new feature is added)
• New doc strings: description and/or example code are in RST format
• Documentation is updated (if required)

[vfdev-5]

@sdesrozis I'm not a fan of introducing another public method for that.
Idea of returning RemovableEventHandler is that it can be used as a context manager to remove attached handlers on exit of the context manager. I think we need to keep single method add_event_handler and return something such that we ensure that it could be used as RemovableEventHandler... What do you think ?

[sdesrozis]

Now add_event_handler returns RemovableEventHandler compatible with EventsList.

@vfdev-5 Is it better ?

TODO doc

[vfdev-5]

Sorry, my bad, the name should remain as previously as RemovableEventHandle and not RemovableEventHandLER.
Yes, now, it looks good for me. Please, add a test with RemovableEventHandle for event list.

TODO doc

• dosctring of Engine.add_event_handler
• README.md in "Power of Events & Handlers"

[sdesrozis]

Last missing point is

• README.md in "Power of Events & Handlers"

[sdesrozis]

@vfdev-5 you can comment :)

[vfdev-5]

@sdesrozis looks good to me. For perfect fit, I would put added section just after "Built-in events filtering"...

[vfdev-5]

@sdesrozis Thanks a lot for the PR !

PS: I changed the order of sections by myself as it can be done very quickly :)

[vfdev-5]

Let me fix coverage relative decrease: https://codecov.io/gh/pytorch/ignite/pull/868/diff#diff-aWduaXRlL2VuZ2luZS9ldmVudHMucHk=

• https://codecov.io/gh/pytorch/ignite/pull/868/diff#D6-218
• https://codecov.io/gh/pytorch/ignite/pull/868/diff#D6-336