djblets.conditions¶

Condition rule support for applications.

This module contains convenience imports for:

class Condition(choice, operator, value=None, raw_value=None)¶

Bases: object

A condition used to match state to a choice, operator, and value.

Conditions store a choice, operator, and value (depending on the operator). Callers can query whether a value fulfills a given condition, making it easy for users to compose sets of rules safely for controlling behavior in an application without having to write any code.

Generally, queries will be made against a ConditionSet, instead of an individual Condition.

choice¶

The choice stored for this condition.

Type:: djblets.conditions.choices.BaseConditionChoice

operator¶

The operator stored for this condition.

Type:: djblets.conditions.operators.BaseConditionOperator

value¶

The value stored for this condition.

Type:: object

raw_value¶

The raw (serialized) value for this condition. This is used internally, and won’t usually be needed by a caller.

Type:: object

classmethod deserialize(choices, data, condition_index=None, choice_kwargs={})¶

Deserialize a condition from serialized data.

This expects data serialized by serialize().

Parameters:

choices (djblets.conditions.choices.ConditionChoices) – Possible choices for the condition.
data (dict) – Serialized data representing this condition.
condition_index (int, optional) – The index of the condition within the set of conditions. This is used for exceptions to help identify which condition failed during deserialization.

Returns:

The deserialized condition.

Return type:

djblets.conditions.conditions.Condition

Raises:

djblets.conditions.errors.ConditionChoiceNotFoundError – The choice ID referenced in the data was missing or did not match a valid choice.
djblets.conditions.errors.ConditionOperatorNotFoundError – The operator ID referenced in the data was missing or did not match a valid operator for the choice.
djblets.conditions.errors.InvalidConditionValueError – The value was missing from the payload data or was not valid for the choice and operator.

__init__(choice, operator, value=None, raw_value=None)¶

Initialize the condition.

Parameters:

choice (djblets.conditions.choices.BaseConditionChoice) – The choice for this condition.
operator (djblets.conditions.operators.BaseConditionOperator) – The operator for this condition.
value (object, optional) – The value for this condition.
raw_value (object, optional) – The raw (serialized) value for this condition.

matches(value, value_state_cache=None)¶

Return whether a value matches the condition.

Parameters:

value (object) – The value to match against.
value_state_cache (dict) – An optional dictionary used to cache common computable data that might be shared across instances of one or more conditions.

Returns:

True if the value fulfills the condition. False if it does not.

Return type:

bool

serialize()¶

Serialize the condition to a JSON-serializable dictionary.

Returns:: A dictionary representing the condition. It can be safely serialized to JSON.
Return type:: dict

to_json()¶

Serialize the condition to a JSON-serializable dictionary.

Returns:: A dictionary representing the condition. It can be safely serialized to JSON.
Return type:: dict

class ConditionSet(mode='all', conditions=[])¶

Bases: object

A set of conditions used to match state and define rules.

Condition sets own multiple conditions, and are given a mode indicating how to query state against those conditions. They’re also responsible for serializing and deserializing all data around a set of conditions to a JSON-serializable format.

If using MODE_ALL, then all conditions must be satisfied for a condition set to pass. If using MODE_ANY, then only one condition must be satisfied.

mode¶

The matching mode for the condition set. This is one of MODE_ALL or MODE_ANY.

Type:: unicode

conditions¶

The list of conditions that comprise this set.

Type:: list of Condition

MODE_ALWAYS = 'always'¶: Always match without conditions.

MODE_ALL = 'all'¶: All conditions must match a value to satisfy the condition set.

MODE_ANY = 'any'¶: Any condition may match a value to satisfy the condition set.

CONDITIONS = ('always', 'all', 'any')¶: A set of all the valid modes.

DEFAULT_MODE = 'all'¶: The default mode.

classmethod deserialize(choices, data, choice_kwargs={})¶

Deserialize a set of conditions from serialized data.

This expects data serialized by deserialize().

Parameters:

choices (djblets.conditions.choices.ConditionChoices) – Possible choices for the condition set.
data (dict) – Serialized data representing this condition set.

Returns:

The deserialized condition set.

Return type:

djblets.conditions.conditions.ConditionSet

Raises:

djblets.conditions.errors.ConditionChoiceNotFoundError – The choice ID referenced in the data was missing or did not match a valid choice in a condition.
djblets.conditions.errors.ConditionOperatorNotFoundError – The operator ID referenced in the data was missing or did not match a valid operator for the choice in a condition.
djblets.conditions.errors.InvalidConditionValueError – The value was missing from the payload data or was not valid for the choice and operator in a condition.
djblets.conditions.errors.InvalidConditionModeError – The stored match mode was missing or was not a valid mode.

__init__(mode='all', conditions=[])¶

Initialize the condition set.

Parameters:

mode (unicode, optional) – The match mode. This defaults to MODE_ALL.
conditions (list, optional) – The conditions that make up this set. This defaults to an empty list.

Raises:

djblets.conditions.errors.InvalidConditionModeError – The match mode is not a valid mode.

matches(**values)¶

Check if a value matches the condition set.

Depending on the mode of the condition set, this will either require all conditions to match, or only one.

Parameters:: **values (dict) – Values to match against. By default, condition choices will match against a single value keyword argument, but more specialized uses might take into account one or more other keyword arguments.
Returns:: True if the value fulfills the condition set. False if it does not.
Return type:: bool

serialize()¶

Serialize the condition set to a JSON-serializable dictionary.

Returns:: A dictionary representing the condition set. It can be safely serialized to JSON.
Return type:: dict

to_json()¶

Serialize the condition set to a JSON-serializable dictionary.

Returns:: A dictionary representing the condition set. It can be safely serialized to JSON.
Return type:: dict