hyperspy.events module¶

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

Bases: object

Create an Event object.

Parameters

doc (str) – Optional docstring for the new Event.
arguments (iterable) – 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.

Example

>>> 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'

_re_arg_name = re.compile('[a-zA-Z_][a-zA-Z0-9_]*')¶

_trigger_maker(arguments)¶

Dynamically creates a function with a signature equal to arguments.

Ensures that trigger can only be called with the correct arguments

property arguments¶

connect(function, kwargs='all')¶

Connects a function to the event.

Parameters

function (callable) – The function to call when the event triggers.
kwargs ({tuple or list, dictionary, '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.

Example

>>> 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()

See also

suppress_callback, Events.suppress

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.

Example

>>> 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()

See also

suppress, Events.suppress

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

Example

>>> 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_single(target)¶

_is_target(candidate)¶

_is_tuple_target(candidate)¶

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.

_update_doc()¶: Updates the doc to reflect the events that are contained

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.

Example

>>> 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()