charms.reactive.decorators

Summary

hook Register the decorated function to run when the current hook matches any of the hook_patterns.
not_unless Assert that the decorated function can only be called if the desired_states are active.
only_once Register the decorated function to be run once, and only once.
when Alias for when_all.
when_all Register the decorated function to run when all of desired_states are active.
when_any Register the decorated function to run when any of desired_states are active.
when_file_changed Register the decorated function to run when one or more files have changed.
when_none Register the decorated function to run when none of desired_states are active.
when_not Alias for when_none.
when_not_all Register the decorated function to run when one or more of the desired_states are not active.

Reference

charms.reactive.decorators.hook(*hook_patterns)

Register the decorated function to run when the current hook matches any of the hook_patterns.

The hook patterns can use the {interface:...} and {A,B,...} syntax supported by any_hook().

If the hook is a relation hook, an instance of that relation class will be passed in to the decorated function.

For example, to match any joined or changed hook for the relation providing the mysql interface:

class MySQLRelation(RelationBase):
    @hook('{provides:mysql}-relation-{joined,changed}')
    def joined_or_changed(self):
        pass

Note that hook decorators cannot be combined with when() or when_not() decorators.

charms.reactive.decorators.not_unless(*desired_states)

Assert that the decorated function can only be called if the desired_states are active.

Note that, unlike when(), this does not trigger the decorated function if the states match. It only raises an exception if the function is called when the states do not match.

This is primarily for informational purposes and as a guard clause.

charms.reactive.decorators.only_once(action=None)

Register the decorated function to be run once, and only once.

This decorator will never cause arguments to be passed to the handler.

charms.reactive.decorators.when(*desired_states)

Alias for when_all.

charms.reactive.decorators.when_all(*desired_states)

Register the decorated function to run when all of desired_states are active.

This decorator will pass zero or more relation instances to the handler, if any of the states are associated with relations. If so, they will be passed in in the same order that the states are given to the decorator.

Note that handlers whose conditions match are triggered at least once per hook invocation.

charms.reactive.decorators.when_any(*desired_states)

Register the decorated function to run when any of desired_states are active.

This decorator will never cause arguments to be passed into to the handler, even for states which are set by relations, since that would make the parameter bindings ambiguous. Therefore, it is not generally recommended to use this with relation states; however, if you do need to, you can get the relation instance associated with a state using from_state().

Note that handlers whose conditions match are triggered at least once per hook invocation.

charms.reactive.decorators.when_file_changed(*filenames, **kwargs)

Register the decorated function to run when one or more files have changed.

Parameters:
  • filenames (list) – The names of one or more files to check for changes (a callable returning the name is also accepted).
  • hash_type (str) – The type of hash to use for determining if a file has changed. Defaults to ‘md5’. Must be given as a kwarg.
charms.reactive.decorators.when_none(*desired_states)

Register the decorated function to run when none of desired_states are active.

This decorator will never cause arguments to be passed to the handler.

Note that handlers whose conditions match are triggered at least once per hook invocation.

charms.reactive.decorators.when_not(*desired_states)

Alias for when_none.

charms.reactive.decorators.when_not_all(*desired_states)

Register the decorated function to run when one or more of the desired_states are not active.

This decorator will never cause arguments to be passed to the handler.

Note that handlers whose conditions match are triggered at least once per hook invocation.