djblets.conditions.choices¶
Base support and standard choices for conditions.
-
class
BaseConditionChoice
(**kwargs)[source]¶ 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[source]¶ The ID of the choice.
This must be unique within a
ConditionSet
.
-
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
= u'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 toCondition.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)[source]¶ 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)[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:
-
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:
-
-
class
ConditionChoiceMatchListItemsMixin
[source]¶ 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
toTrue
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:
-
-
class
BaseConditionBooleanChoice
(**kwargs)[source]¶ Bases:
djblets.conditions.choices.BaseConditionChoice
Base class for a standard boolean-based condition choice.
This is a convenience for choices that cover boolean values.
-
class
BaseConditionIntegerChoice
(**kwargs)[source]¶ Bases:
djblets.conditions.choices.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.
-
class
BaseConditionStringChoice
(**kwargs)[source]¶ Bases:
djblets.conditions.choices.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.
-
class
ModelQueryChoiceMixin
[source]¶ 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 overridingget_queryset()
.
-
class
BaseConditionModelChoice
(**kwargs)[source]¶ Bases:
djblets.conditions.choices.ModelQueryChoiceMixin
,djblets.conditions.choices.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 overrideget_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 setqueryset
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]¶ Bases:
djblets.conditions.choices.BaseConditionModelChoice
Base class for a model-based condition that requires a value.
This is simply a variation on
BaseConditionModelChoice
that doesn’t include aUnsetOperator
.
-
class
BaseConditionModelMultipleChoice
(**kwargs)[source]¶ Bases:
djblets.conditions.choices.ModelQueryChoiceMixin
,djblets.conditions.choices.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 overrideget_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 setqueryset
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]¶ Bases:
djblets.registries.registry.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:
- Created dynamically, taking a list of
BaseConditionChoice
subclasses as arguments. - Subclassed, with
choice_classes
set to a list ofBaseConditionChoice
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
-
default_errors
= {u'already_registered': u'Could not register condition choice %(item)s: This choice is already registered or its ID conflicts with another choice.', u'attribute_registered': u'Could not register condition choice %(item)s: Another choice (%(duplicate)s) is already registered with the same ID.', u'invalid_attribute': u'"%(attr_name)s" is not a registered lookup attribute.', u'load_entry_point': u'Could not load entry point %(entry_point)s: %(error)s.', u'missing_attribute': u'Could not register %(item)s: it does not have a "%(attr_name)s" attribute.', u'not_registered': u'No condition choice was found matching "%(attr_value)s".', u'unregister': u'Could not unregister condition choice %(item)s: This condition was not yet registered.'}[source]¶
-
__init__
(choices=[])[source]¶ Initialize the list of choices.
Parameters: choices (list of type, optional) – A list of BaseConditionChoice
subclasses. If this is provided, any value set forchoice_classes
will be ignored.
-
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: 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
- Created dynamically, taking a list of