djblets.conditions.choices¶

Base support and standard choices for conditions.

class BaseConditionChoice(**kwargs)¶

Bases: object

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¶

The ID of the choice.

This must be unique within a ConditionSet.

name = None¶

The displayed name for the choice.

operators = None¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

default_value_field = None¶

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'¶

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.

__init__(**kwargs)¶

Initialize the condition choice.

Parameters:

**kwargs (dict) – Additional data used for the condition choice. These will be available as extra_state.

get_operator(operator_id)¶

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

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

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

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¶

Bases: object

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¶

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

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

Bases: BaseConditionChoice

Base class for a standard boolean-based condition choice.

This is a convenience for choices that cover boolean values.

operators = <djblets.conditions.operators.ConditionOperators object>¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

default_value_field = <djblets.conditions.values.ConditionValueBooleanField object>¶

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.

class BaseConditionIntegerChoice(**kwargs)¶

Bases: BaseConditionChoice

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.

operators = <djblets.conditions.operators.ConditionOperators object>¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

default_value_field = <djblets.conditions.values.ConditionValueIntegerField object>¶

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.

class BaseConditionStringChoice(**kwargs)¶

Bases: BaseConditionChoice

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.

operators = <djblets.conditions.operators.ConditionOperators object>¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

default_value_field = <djblets.conditions.values.ConditionValueCharField object>¶

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.

class ModelQueryChoiceMixin¶

Bases: object

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¶

The queryset used for the choice.

get_queryset()¶

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

Bases: ModelQueryChoiceMixin, BaseConditionChoice

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.

operators = <djblets.conditions.operators.ConditionOperators object>¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

default_value_field(**kwargs)¶

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

Bases: BaseConditionModelChoice

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

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

operators = <djblets.conditions.operators.ConditionOperators object>¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

class BaseConditionModelMultipleChoice(**kwargs)¶

Bases: ModelQueryChoiceMixin, BaseConditionChoice

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.

operators = <djblets.conditions.operators.ConditionOperators object>¶

The operators for this choice.

This must be set to an instance of ConditionOperators.

default_value_field(**kwargs)¶

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=[])¶

Bases: OrderedRegistry

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 = []¶

A list of default choices.

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

lookup_attrs: Sequence[str] = ('choice_id',)¶

A list of attributes that items can be looked up by.

Type:

list of str

lookup_error_class¶

alias of ConditionChoiceNotFoundError

already_registered_error_class¶

alias of ConditionChoiceConflictError

default_errors: Dict[str, Union[str, StrPromise]] = {'already_registered': 'Could not register condition choice %(item)s: This choice is already registered or its ID conflicts with another choice.', 'attribute_registered': 'Could not register condition choice %(item)s: Another choice (%(duplicate)s) is already registered with the same ID.', 'invalid_attribute': '"%(attr_name)s" is not a registered lookup attribute.', 'load_entry_point': 'Could not load entry point %(entry_point)s: %(error)s.', 'missing_attribute': 'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', 'not_registered': 'No condition choice was found matching "%(attr_value)s".', 'unregister': 'Could not unregister condition choice %(item)s: This condition was not yet registered.'}¶

The default error formatting strings.

If subclasses need to provide additional errors that can be overridden, they should copy DEFAULT_ERRORS and set their copy on the subclass as this attribute.

Type:

dict

__init__(choices=[])¶

Initialize the list of choices.

Parameters:

choices (list of type, optional) – A list of BaseConditionChoice subclasses. If this is provided, any value set for choice_classes will be ignored.

get_choice(choice_id, choice_kwargs={})¶

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={})¶

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

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

__parameters__ = ()¶