djblets.conditions.choices¶

Base support and standard choices for conditions.

class BaseConditionChoice(**kwargs)[source]¶

Base class for a choice for a condition.

A choice is the primary option in a condition. It generally corresponds to an object or attribute that would be matched, and contains a human-readable name for the choice, a list of operators that pertain to the choice, and the default type of field that a user will be using to select a value.

extra_state¶

Extra state provided to the choice during construction as keyword arguments. This can be useful for condition choices that need more advanced logic around value field construction or matching.

Type

dict

choice_id = None[source]¶

The ID of the choice.

This must be unique within a ConditionSet.

name = None[source]¶

The displayed name for the choice.

operators = None[source]¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

default_value_field = None[source]¶

The default field type used to prompt and render fields.

This value will be the default for all operators, unless otherwise overridden.

This must be set to an instance of a BaseConditionValueField subclass or a function returning an instance.

If it’s a function, it must accept a **kwargs, for future expansion.

value_kwarg = 'value'[source]¶

The keyword argument required for condition matching.

This is the name of the keyword argument that must be provided in order for this choice to be considered for matching. By default, this expects a value= keyword argument to be passed to Condition.match, but choices can specify another name instead.

This allows multiple choices with different expected values to be used in the same ConditionSet.

get_operator(operator_id)[source]¶

Return an operator instance from this choice with the given ID.

Instances are not cached. Repeated calls will construct new instances.

Parameters

operator_id (unicode) – The ID of the operator to retrieve.

Returns

The operator instance matching the ID.

Return type

djblets.conditions.operators.BaseConditionOperator

Raises

djblets.conditions.errors.ConditionOperatorNotFoundError – No operator was found that matched the given ID.

get_operators()[source]¶

Return a generator for all operator instances for this choice.

This is a convenience around iterating through all operator classes and constructing an instance for each.

Instances are not cached. Repeated calls will construct new instances.

Yields

djblets.conditions.operators.BaseConditionOperator – The operator instance.

get_match_value(value, value_state_cache=None, **kwargs)[source]¶

Return a normalized value used for matching.

This will take the value provided to the parent Condition and return either that value or some related value.

It’s common for value to actually be an object, such as a database model. In this case, this function may want to return an attribute (such as a text attribute) from the object, or an object related to this object.

By default, the value is returned directly.

Parameters

• value (object) – The value provided to match against.

• value_state_cache (dict) –

  An dictionary used to cache common computable data that might be shared across instances of one or more conditions.

  This can be assumed to be a valid dictionary when called in normal usage through condition matching.

• **kwargs (dict) – Extra keyword arguments passed, for future expansion.

Returns

The value that this choice’s operators will match against.

Return type

object

matches(operator, match_value, condition_value, value_state_cache, **kwargs)[source]¶

Return whether a value matches this choice and operator.

This is called internally be Condition(). It should not be called manually.

Parameters

• operator (djblets.conditions.operators.BaseConditionOperator) – The operator that will perform the match, given this choice’s match value and the provided condition value.

• match_value (object) – The value to match against the operator and condition value. This will be normalized before being passed to the operator for matching.

• condition_value (object) – The optional value stored in the condition, which the operator will use for the match.

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

• **kwargs (dict) – Unused keyword arguments.

Returns

True if the value fulfills this choice and operator. False if it does not.

Return type

bool

class ConditionChoiceMatchListItemsMixin[source]¶

Mixin to match against each item in a list instead of the list itself.

This allows a condition choice to perform an operator match against each item a value, instead of performing the match against the value itself. It’s useful for choices that want to offer, for instance, a string-based operator against a list of filenames.

By default, the match will be considered successful if any item in the list matches, and will be considered unsuccessful if no items match. Consumers of the mixin can set require_match_all_items to True to require all items in the list to match.

require_match_all_items = False[source]¶

Whether all items must match for the choice’s match to be successful.

By default, the match is successful if any item in the list matches. If True, all items must match.

matches(operator, match_value, condition_value, value_state_cache, **kwargs)[source]¶

Return whether a value matches this choice and operator.

This is called internally be Condition(). It should not be called manually.

Parameters

• operator (djblets.conditions.operators.BaseConditionOperator) – The operator that will perform the match, given this choice’s match value and the provided condition value.

• match_value (object) – The value to match against the operator and condition value. This will be normalized before being passed to the operator for matching.

• condition_value (object) – The optional value stored in the condition, which the operator will use for the match.

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

• **kwargs (dict) – Unused keyword arguments.

Returns

True if the value fulfills this choice and operator. False if it does not.

Return type

bool

class BaseConditionBooleanChoice(**kwargs)[source]¶

Base class for a standard boolean-based condition choice.

This is a convenience for choices that cover boolean values.

class BaseConditionIntegerChoice(**kwargs)[source]¶

Base class for a standard integer-based condition choice.

This is a convenience for choices that are based on integers. It provides some standard operators that work well with integers for checking.

class BaseConditionStringChoice(**kwargs)[source]¶

Base class for a standard string-based condition choice.

This is a convenience for choices that are based on strings. It provides some standard operators that work well with strings for checking.

class ModelQueryChoiceMixin[source]¶

A mixin for choices that want to allow for custom querysets.

This allows subclasses to either define a queryset or define a more complex queryset by overriding get_queryset().

queryset = None[source]¶

The queryset used for the choice.

get_queryset()[source]¶

Return the queryset used for the choice.

By default, this returns queryset. It can be overridden to return a more dynamic queryset.

Returns

The queryset for the choice.

Return type

django.db.query.QuerySet

class BaseConditionModelChoice(**kwargs)[source]¶

Base class for a standard model-based condition choice.

This is a convenience for choices that are based on a single model. It provides some standard operators that work well with comparing models.

Subclasses should provide a queryset attribute, or override get_queryset() to provide a more dynamic queryset.

default_value_field(**kwargs)[source]¶

Return the default value field for this choice.

This will call out to get_queryset() before returning the field, allowing subclasses to simply set queryset or to perform more dynamic queries before constructing the form field.

Parameters

**kwargs (dict) – Extra keyword arguments for this function, for future expansion.

Returns

The form field for the value.

Return type

djblets.conditions.values.ConditionValueMultipleModelField

class BaseConditionRequiredModelChoice(**kwargs)[source]¶

Base class for a model-based condition that requires a value.

This is simply a variation on BaseConditionModelChoice that doesn’t include a UnsetOperator.

class BaseConditionModelMultipleChoice(**kwargs)[source]¶

Base class for a standard multi-model-based condition choice.

This is a convenience for choices that are based on comparing against multiple instances of models. It provides some standard operators that work well with comparing sets of models.

Subclasses should provide a queryset attribute, or override get_queryset() to provide a more dynamic queryset.

default_value_field(**kwargs)[source]¶

Return the default value field for this choice.

This will call out to get_queryset() before returning the field, allowing subclasses to simply set queryset or to perform more dynamic queries before constructing the form field.

Parameters

**kwargs (dict) – Extra keyword arguments for this function, for future expansion.

Returns

The form field for the value.

Return type

djblets.conditions.values.ConditionValueMultipleModelField

class ConditionChoices(choices=[])[source]¶

Represents a list of choices for conditions.

This stores a list of choices that can be used for conditions. It can be used in one of two ways:

1. Created dynamically, taking a list of BaseConditionChoice subclasses as arguments.

2. Subclassed, with choice_classes set to a list of BaseConditionChoice subclasses.

This works as a registry, allowing additional choices to be added dynamically by extensions or other code.

choice_classes = [][source]¶

A list of default choices.

This is only used if a list of choices is not passed to the constructor.

lookup_error_class[source]¶

alias of djblets.conditions.errors.ConditionChoiceNotFoundError

already_registered_error_class[source]¶

alias of djblets.conditions.errors.ConditionChoiceConflictError

get_choice(choice_id, choice_kwargs={})[source]¶

Return a choice instance with the given ID.

Instances are not cached. Repeated calls will construct new instances.

Parameters

• choice_id (unicode) – The ID of the choice to retrieve.

• choice_kwargs (dict) – Keyword arguments to pass to the choice’s constructor.

Returns

The choice instance matching the ID.

Return type

BaseConditionChoice

Raises

djblets.conditions.errors.ConditionChoiceNotFoundError – No choice was found that matched the given ID.

get_choices(choice_kwargs={})[source]¶

Return a generator for all choice instances.

This is a convenience around iterating through all choice classes and constructing an instance for each.

Instances are not cached. Repeated calls will construct new instances.

Parameters

choice_kwargs (dict) – Keyword arguments to pass to each choice’s constructor.

Yields

BaseConditionChoice – The choice instance.

get_defaults()[source]¶

Return the default choices for the list.

This is used internally by the parent registry class, and is based on the list of choices provided to the constructor or the value for choice_classes.

Returns

The default list of choices.

Return type

list of type