charms.reactive.decorators

Summary

These decorators turn a regular function into a reactive handler so that it will be invoked if the conditions in the decorators are met. These decorators are also called the preconditions of the handlers. If a handler has multiple decorators, they will be ANDed together: the handler will only be invoked if all of the individual decorators match.

Handlers are currently re-invoked for every hook execution, even if their predicate flags have not changed. However, this may well change in the future, and it is highly recommended that you not rely on this behavior. If you need to ensure that a particular handler runs again, you should set or remove one of its predicate flags.

Regular handlers should not accept any arguments. When a handler needs to use a (relationship) Endpoint, it can access the endpoint object via endpoint_from_flag(). The only exceptions to this are endpoint handlers, handlers that are instance methods of Endpoint: they get the endpoint object as the self argment.

For backwards compatibility, some decorators will pass endpoint instances if the handler function specifies them as arguments. However, explicit instance access using endpoint_from_flag is recommended, because ensuring proper argument order can be confusing: they are passed in bottom-up, left-to-right, and no negative or ambiguous decorators, such as when_not() or when_any() will ever pass arguments. Note that a handler function that doesn’t take arguments will never receive these instances.

collect_metrics	Register the decorated function to run for the collect_metrics hook.
hook	Register the decorated function to run when the current hook matches any of the hook_patterns.
meter_status_changed	Register the decorated function to run when a meter status change has been detected.
not_unless	Assert that the decorated function can only be called if the desired_flags are active.
when	Alias for when_all().
when_all	Register the decorated function to run when all of desired_flags are active.
when_any	Register the decorated function to run when any of desired_flags 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_flags are active.
when_not	Alias for when_none().
when_not_all	Register the decorated function to run when one or more of the desired_flags are not active.

Reference

charms.reactive.decorators.when(*desired_flags)

Alias for when_all().

charms.reactive.decorators.when_all(*desired_flags)

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

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

For backwards compatibility, this decorator can pass arguments, but it is recommended to use argument-less handlers. See the summary for more information.

charms.reactive.decorators.when_any(*desired_flags)

Register the decorated function to run when any of desired_flags 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_flags)

Alias for when_none().

charms.reactive.decorators.when_none(*desired_flags)

Register the decorated function to run when none of desired_flags 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_all(*desired_flags)

Register the decorated function to run when one or more of the desired_flags 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.

charms.reactive.decorators.not_unless(*desired_flags)

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

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

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

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

Register the decorated function to run for the collect_metrics hook.

charms.reactive.decorators.meter_status_changed()

Register the decorated function to run when a meter status change has been detected.

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

Deprecated since version 0.5.0: Use when_not() in combination with set_state() instead. This handler is deprecated because it might actually be called multiple times.

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.hook(*hook_patterns)

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

This decorator is generally deprecated and should only be used when absolutely necessary.

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

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