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