Events#

class hyperspy.events.Event(doc='', arguments=None)#

Bases: object

Events class

Parameters:
docstr

Optional docstring for the new Event.

argumentsiterable

Pass to define the arguments of the trigger() function. Each element must either be an argument name, or a tuple containing the argument name and the argument’s default value.

Examples

>>> from hyperspy.events import Event
>>> Event()
<hyperspy.events.Event: set()>
>>> Event(doc="This event has a docstring!").__doc__
'This event has a docstring!'
>>> e1 = Event()
>>> e2 = Event(arguments=('arg1', ('arg2', None)))
>>> e1.trigger(arg1=12, arg2=43, arg3='str', arg4=4.3)  # Can trigger with whatever
>>> e2.trigger(arg1=11, arg2=22, arg3=3.4) 
Traceback (most recent call last):
    ...
TypeError: trigger() got an unexpected keyword argument 'arg3'
connect(function, kwargs='all')#

Connects a function to the event.

Parameters:
functioncallable()

The function to call when the event triggers.

kwargstuple or list, dict, str {'all' | ``'auto'}, default "all"

If "all", all the trigger keyword arguments are passed to the function. If a list or tuple of strings, only those keyword arguments that are in the tuple or list are passed. If empty, no keyword argument is passed. If dictionary, the keyword arguments of trigger are mapped as indicated in the dictionary. For example, {“a” : “b”} maps the trigger argument “a” to the function argument “b”.

See also

disconnect
property connected#

Connected functions.

disconnect(function)#

Disconnects a function from the event. The passed function will be disconnected irregardless of which ‘nargs’ argument was passed to connect().

If you only need to temporarily prevent a function from being called, single callback suppression is supported by the suppress_callback context manager.

Parameters:
function: function
return_connection_kwargs: bool, default False

If True, returns the kwargs that would reconnect the function as it was.

See also

connect
suppress_callback
suppress()#

Use this function with a ‘with’ statement to temporarily suppress all events in the container. When the ‘with’ lock completes, the old suppression values will be restored.

See also

suppress_callback
Events.suppress

Examples

>>> with obj.events.myevent.suppress(): 
...     # These would normally both trigger myevent:
...     obj.val_a = a
...     obj.val_b = b

Trigger manually once: >>> obj.events.myevent.trigger() # doctest: +SKIP

suppress_callback(function)#

Use this function with a ‘with’ statement to temporarily suppress a single callback from being called. All other connected callbacks will trigger. When the ‘with’ lock completes, the old suppression value will be restored.

See also

suppress
Events.suppress

Examples

>>> with obj.events.myevent.suppress_callback(f): 
...     # Events will trigger as normal, but `f` will not be called
...     obj.val_a = a
...     obj.val_b = b
>>> # Here, `f` will be called as before:
>>> obj.events.myevent.trigger()
trigger(**kwargs)#

Triggers the event. If the event is suppressed, this does nothing. Otherwise it calls all the connected functions with the arguments as specified when connected.

See also

suppress
suppress_callback
Events.suppress
class hyperspy.events.EventSuppressor(*to_suppress)#

Bases: object

Object to enforce a variety of suppression types simultaneously

Targets to be suppressed can be added by the function add(), or given in the constructor. Valid targets are:

  • Event: The entire Event will be suppressed

  • Events: All events in th container will be suppressed

  • (Event, callback): The callback will be suppressed in Event

  • (Events, callback): The callback will be suppressed in each event in Events where it is connected.

  • Any iterable collection of the above target types

Examples

>>> es = EventSuppressor((event1, callback1), (event1, callback2)) 
>>> es.add(event2, callback2) 
>>> es.add(event3) 
>>> es.add(events_container1) 
>>> es.add(events_container2, callback1) 
>>> es.add(event4, (events_container3, callback2)) 

>>> with es.suppress(): 
...     do_something()
add(*to_suppress)#

Add one or more targets to be suppressed

Valid targets are:

  • Event: The entire Event will be suppressed

  • Events: All events in the container will be suppressed

  • (Event, callback): The callback will be suppressed in Event

  • (Events, callback): The callback will be suppressed in each event in Events where it is connected.

  • Any iterable collection of the above target types

suppress()#

Use this function with a ‘with’ statement to temporarily suppress all events added. When the ‘with’ lock completes, the old suppression values will be restored.

See also

Events.suppress
Event.suppress
Event.suppress_callback
class hyperspy.events.Events#

Bases: object

Events container.

All available events are attributes of this class.

suppress()#

Use this function with a ‘with’ statement to temporarily suppress all callbacks of all events in the container. When the ‘with’ lock completes, the old suppression values will be restored.

See also

Event.suppress
Event.suppress_callback

Examples

>>> with obj.events.suppress(): 
...     # Any events triggered by assignments are prevented:
...     obj.val_a = a
...     obj.val_b = b
>>> # Trigger one event instead:
>>> obj.events.values_changed.trigger()