charms.reactive.flags¶

Summary

`all_flags_set`	Assert that all desired_flags are set
`any_flags_set`	Assert that any of the desired_flags are set
`clear_flag`	Clear / deactivate a flag.
`get_flags`	Return a list of all flags which are set.
`get_unset_flags`	Check if any of the provided flags missing and return them if so.
`is_flag_set`	Assert that a flag is set
`register_trigger`	Register a trigger to set or clear a flag when a given flag is set.
`set_flag`	Set the given flag as active.
`toggle_flag`	Helper that calls either `set_flag()` or `clear_flag()`, depending on the value of should_set.

Reference

charms.reactive.flags.set_flag(flag)¶

Set the given flag as active.

Parameters:	flag (str) – Name of flag to set.

Note

Changes to flags are reset when a handler crashes. Changes to flags happen immediately, but they are only persisted at the end of a complete and successful run of the reactive framework. All unpersisted changes are discarded when a hook crashes.

charms.reactive.flags.clear_flag(flag)¶

Clear / deactivate a flag.

Parameters:	flag (str) – Name of flag to set.

Note

Changes to flags are reset when a handler crashes. Changes to flags happen immediately, but they are only persisted at the end of a complete and successful run of the reactive framework. All unpersisted changes are discarded when a hook crashes.

charms.reactive.flags.toggle_flag(flag, should_set)¶

Helper that calls either set_flag() or clear_flag(), depending on the value of should_set.

Equivalent to:

if should_set:
    set_flag(flag)
else:
    clear_flag(flag)

Parameters:	flag (str) – Name of flag to toggle. should_set (bool) – Whether to set the flag, or clear it.

Note

Changes to flags are reset when a handler crashes. Changes to flags happen immediately, but they are only persisted at the end of a complete and successful run of the reactive framework. All unpersisted changes are discarded when a hook crashes.

charms.reactive.flags.register_trigger(when=None, when_not=None, set_flag=None, clear_flag=None, callback=None)¶

Register a trigger to set or clear a flag when a given flag is set.

Note: Flag triggers are handled at the same time that the given flag is set.

Parameters:

when (Optional[str]) – Flag to trigger on when it is set.
when_not (Optional[str]) – Flag to trigger on when it is cleared.
set_flag (Optional[str]) – If given, this flag will be set when the relevant flag is changed.
clear_flag (Optional[str]) – If given, this flag will be cleared when the relevant flag is changed.
Any]] callback (Optional[Callable[[],) – If given, this callback will be invoked when the relevant flag is changed.

Note: Exactly one of either when or when_not, and at least one of set_flag, clear_flag, or callback must be provided.

charms.reactive.flags.is_flag_set(flag)¶: Assert that a flag is set

charms.reactive.flags.all_flags_set(*desired_flags)¶: Assert that all desired_flags are set

charms.reactive.flags.any_flags_set(*desired_flags)¶: Assert that any of the desired_flags are set

charms.reactive.flags.get_flags()¶: Return a list of all flags which are set.

charms.reactive.flags.get_unset_flags(*desired_flags)¶

Check if any of the provided flags missing and return them if so.

Parameters:	desired_flags (non-keyword args, str) – list of reactive flags
Returns:	list of unset flags filtered from the parameters shared
Return type:	List[str]

charms.reactive.flags.set_state(state, value=None)¶: Deprecated since version 0.5.0: Alias of set_flag().

charms.reactive.flags.remove_state(state)¶: Deprecated since version 0.5.0: Alias of clear_flag()

charms.reactive.flags.toggle_state(state, should_set)¶: Deprecated since version 0.5.0: Alias of toggle_flag()

charms.reactive.flags.is_state(state)¶: Deprecated since version 0.5.0: Alias for is_flag_set()

charms.reactive.flags.all_states(*desired_states)¶: Deprecated since version 0.5.0: Alias for all_flags_set()

charms.reactive.flags.get_states()¶: Deprecated since version 0.5.0: Use get_flags() instead.

Return a mapping of all active states to their values.

charms.reactive.flags.any_states(*desired_states)¶: Deprecated since version 0.5.0: Alias for any_flags_set()