djblets.conditions.operators¶

Base support and standard operators for condition choices.

class BaseConditionOperator(choice)[source]¶

Bases: object

Base class for an operator for a condition choice.

An operator forms an expression along with a parent BaseConditionChoice and an optional value. This expression can be used by the condition to determine if a caller-provided value satisfies the condition.

Choices will usually have more than one operator registered. Depending on the operator, there may or may not be a field for a value.

choice¶

The choice owning the instance of this operation.

Type:: djblets.conditions.choices.BaseConditionChoice

operator_id = None[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = None[source]¶: The displayed name for the operator.

classmethod with_overrides(**attrs)[source]¶

Dynamically create a subclass with overridden attributes.

This makes it easy for a choice to make use of existing operators while using a custom name for display, or a custom value field, without having to create their own subclasses. It’s meant only for simple changes.

Parameters:: **attrs (dict) – Attributes to override on the operator.
Returns:: A new subclass with the overridden attributes.
Return type:: type

__init__(choice)[source]¶

Initialize the operator.

Parameters:: choice (djblets.conditions.choices.BaseConditionChoice) – The choice owning the instance of this operator.

property value_field[source]¶

The field type used to prompt and render fields.

By default, this will use the default one for the choice. The field can be disabled by setting this to None, or a different field can be used by setting it 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.

property has_custom_value_field[source]¶: Whether the operator has a custom value field.

matches(match_value, stored_value, **kwargs)[source]¶

Return whether a value matches the operator and condition’s value.

This must be implemented by subclasses.

Parameters:

match_value (object) – The caller’s value to check against the state for this operator.
condition_value (object) – The value stored as part of the condition to check against. This will only be used if the operator has a value field associated.
**kwargs (dict) – Extra keyword arguments, for future expansion.

Returns:

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

Return type:

bool

Raises:

TypeError – Either the lookup or condition value or types was not compatible with the expression.

class IsOneOfOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that matches against a set of possible values.

This operator checks if the lookup value matches one of a set of possible values listed in the condition.

This is equivalent to:

if match_value in condition_value:
    ...

operator_id = 'one-of'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Is one of'[source]¶: The displayed name for the operator.

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

Return whether the lookup value is one of a set of values.

Parameters:

match_value (object) – The caller’s value to check against the state for this operator.
condition_value (list) – A list of possible values that the lookup value must match.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value is present in the list of possible values.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not compatible with the expression.

__annotations__ = {}¶

class IsNotOneOfOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that matches if not one of a set of possible values.

This operator checks if the lookup value is not one of a set of possible values listed in the condition.

This is equivalent to:

if match_value not in condition_value:
    ...

operator_id = 'not-one-of'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Is not one of'[source]¶: The displayed name for the operator.

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

Return whether the lookup value is not one of a set of values.

Parameters:

match_value (object) – The caller’s value to check against the state for this operator.
condition_value (list) – A list of possible values that the lookup value must not match.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value is not present in the list of possible values.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not compatible with the expression.

__annotations__ = {}¶

class AnyOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that matches for any non-empty/zero value.

This operator checks if the lookup value provided is a non-empty value (a boolean, integer, string/list/dictionary containing a value, etc.). To determine if the value is empty, the operator checks len(value). If not 0, or if the value doesn’t support a length check, it’s assumed to have a value.

This is equivalent to:

if match_value in (0, False) or bool(match_value):
    ...

The operator does not accept a user-provided condition value.

This is the opposite of UnsetOperator.

operator_id = 'any'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Has a value'[source]¶: The displayed name for the operator.

value_field = None[source]¶

matches(match_value, **kwargs)[source]¶

Return whether the lookup value is non-empty.

Parameters:

match_value (object) – The caller’s value to check against the state for this operator.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the value is evaluated as not empty. False if it evalutes as empty.

Return type:

bool

__annotations__ = {}¶

class UnsetOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that matches for an unset/empty value.

This operator checks if the lookup value provided is an empty value (such as empty string/list/dictionary or None). This performs a simple not check against the value, but filters out values that evalute to False but are not considered unset.

This is equivalent to:

if match_value not in (0, False) and not match_value:
    ...

The operator does not accept a user-provided condition value.

This is the opposite of AnyOperator.

operator_id = 'none'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Is unset'[source]¶: The displayed name for the operator.

value_field = None[source]¶

matches(match_value, **kwargs)[source]¶

Return whether the lookup value is empty.

Parameters:

match_value (object) – The caller’s value to check against the state for this operator.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the value is evaluated as empty. False if it evalutes as not empty.

Return type:

bool

__annotations__ = {}¶

class IsOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if one value is the same as another.

This operator checks for equality, comparing the lookup value to the stored condition value.

It’s equivalent to:

if match_value == condition_value:
    ...

This is the opposite of IsNotOperator.

operator_id = 'is'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Is'[source]¶: The displayed name for the operator.

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

Return whether the lookup value equals a condition value.

Parameters:

match_value (object) – The caller’s value to check against the state for this operator.
condition_value (object) – The value to compare against.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value equals the condition value.

Return type:

bool

__annotations__ = {}¶

class IsNotOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if one value is not the same as another.

This operator checks for inequality, comparing the lookup value to the stored condition value.

It’s equivalent to:

if match_value != condition_value:
    ...

This is the opposite of IsOperator.

operator_id = 'is-not'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Is not'[source]¶: The displayed name for the operator.

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

Return whether the lookup value is not equal to a condition value.

Parameters:

match_value (object) – The caller’s value to check against the state for this operator.
condition_value (object) – The value to compare against.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value is not equal to the condition value.

Return type:

bool

__annotations__ = {}¶

class ContainsOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a lookup value contains a condition value.

This operator checks if the provided lookup value contains the condition value within the value. It’s useful for checking if a string or list contains some value.

It’s equivalent to:

if condition_value in match_value:
    ...

This is the opposite of DoesNotContainOperator.

operator_id = 'contains'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Contains'[source]¶: The displayed name for the operator.

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

Return whether the lookup value contains a condition value.

Parameters:

match_value (object) – The caller’s value to check for a condition value within.
condition_value (object) – The value to check within the lookup value.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value contains the condition value.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not compatible with the expression.

__annotations__ = {}¶

class DoesNotContainOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a lookup value does not contain a value.

This operator checks if the provided lookup value does not contain the condition value within the value. It’s useful for checking if a string or list does not contain some value.

It’s equivalent to:

if condition_value not in match_value:
    ...

This is the opposite of ContainsOperator.

operator_id = 'does-not-contain'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Does not contain'[source]¶: The displayed name for the operator.

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

Return whether the lookup value does not contain a condition value.

Parameters:

match_value (object) – The caller’s value to check for a condition value within.
condition_value (object) – The value to check within the lookup value.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value does not contain the condition value.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not compatible with the expression.

__annotations__ = {}¶

class ContainsAnyOperator(choice)[source]¶

Bases: BaseConditionOperator

Checks if a lookup value contains any specified condition values.

This operator checks if the provided lookup value contains any items in a list of condition value. It’s useful for checking if a list contains anything from another list.

It’s equivalent to:

if set(condition_value) & set(match_value):
    ...

This is the opposite of DoesNotContainAnyOperator.

operator_id = 'contains-any'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Any of'[source]¶: The displayed name for the operator.

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

Return whether the lookup value contains any condition values.

Parameters:

match_value (object) – The caller’s value to check for condition values within.
condition_value (object) – The values to check within the lookup value.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value contains any of the given condition values.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not compatible with the expression.

__annotations__ = {}¶

class DoesNotContainAnyOperator(choice)[source]¶

Bases: BaseConditionOperator

Checks if a lookup value doesn’t contain any of the specified values.

This operator checks if the provided lookup value does not contain any of the provided condition values. It’s useful for checking if a list does not contain any items from another list.

It’s equivalent to:

if not (set(condition_value) & set(match_value)):
    ...

This is the opposite of ContainsAnyOperator.

operator_id = 'does-not-contain-any'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Not any of'[source]¶: The displayed name for the operator.

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

Return if the lookup value doesn’t contain any condition values.

Parameters:

match_value (object) – The caller’s value to check for a condition value within.
condition_value (object) – The values to check within the lookup value.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value does not contain any of the condition value.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not compatible with the expression.

__annotations__ = {}¶

class StartsWithOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a string starts with another string.

This operator checks if the lookup value (assumed to be a string) starts with the condition value (also a string).

It’s equivalent to:

if match_value.startswith(condition_value):
    ...

operator_id = 'starts-with'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Starts with'[source]¶: The displayed name for the operator.

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

Return whether the lookup value starts with the condition value.

Parameters:

match_value (unicode) – The caller’s value to check.
condition_value (unicode) – The value to check at the start of the lookup value string.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value starts with the condition value.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not a string (or string-like object).

__annotations__ = {}¶

class EndsWithOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a string ends with another string.

This operator checks if the lookup value (assumed to be a string) ends with the condition value (also a string).

It’s equivalent to:

if match_value.endswith(condition_value):
    ...

operator_id = 'ends-with'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Ends with'[source]¶: The displayed name for the operator.

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

Return whether the lookup value ends with the condition value.

Parameters:

match_value (unicode) – The caller’s value to check.
condition_value (unicode) – The value to check at the end of the lookup value string.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value ends with the condition value.

Return type:

bool

Raises:

TypeError – Either the lookup or condition value was not a string (or string-like object).

__annotations__ = {}¶

class GreaterThanOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a number is greater than a value.

This operator checks if the lookup value (assumed to be an integer or similar) is greater than the condition value.

It’s equivalent to:

if match_value > condition_value:
    ...

operator_id = 'greater-than'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Greater than'[source]¶: The displayed name for the operator.

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

Return whether the lookup value is greater than the condition value.

Parameters:

match_value (object) – The caller’s value to check.
condition_value (object) – The value that the lookup value must be greater than.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value is greater than the condition value.

Return type:

bool

__annotations__ = {}¶

class LessThanOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a number is less than a value.

This operator checks if the lookup value (assumed to be an integer or similar) is less than the condition value.

It’s equivalent to:

if match_value < condition_value:
    ...

operator_id = 'less-than'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Less than'[source]¶: The displayed name for the operator.

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

Return whether the lookup value is less than the condition value.

Parameters:

match_value (object) – The caller’s value to check.
condition_value (object) – The value that the lookup value must be less than.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value is less than the condition value.

Return type:

bool

__annotations__ = {}¶

class MatchesRegexOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a value matches against a regex.

It’s equivalent to:

if condition_value.match(match_value):
    ...

operator_id = 'matches-regex'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Matches regex'[source]¶: The displayed name for the operator.

value_field = <djblets.conditions.values.ConditionValueRegexField object>[source]¶

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

Return whether the lookup value matches the condition’s regex.

Parameters:

match_value (unicode) – The caller’s value to check.
condition_value (re.RegexObject) – The regex value that the lookup value must match.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value matches the regex in the condition.

Return type:

bool

__annotations__ = {}¶

class DoesNotMatchRegexOperator(choice)[source]¶

Bases: BaseConditionOperator

An operator that checks if a value does not match against a regex.

It’s equivalent to:

if not condition_value.match(match_value):
    ...

operator_id = 'does-not-match-regex'[source]¶

The ID of the operator.

This must be unique within a BaseConditionChoice.

name = 'Does not match regex'[source]¶: The displayed name for the operator.

value_field = <djblets.conditions.values.ConditionValueRegexField object>[source]¶

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

Return whether the lookup value doesn’t match the condition’s regex.

Parameters:

match_value (unicode) – The caller’s value to check.
condition_value (re.RegexObject) – The regex value that the lookup value must not match.
**kwargs (dict) – Unused extra keyword arguments.

Returns:

True if the lookup value doesn’t match the regex in the condition.

Return type:

bool

__annotations__ = {}¶

class ConditionOperators(operators=[], *args, **kwargs)[source]¶

Bases: OrderedRegistry

Represents a list of operators for a condition choice.

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

Created dynamically, taking a list of BaseConditionOperator subclasses as arguments.
Subclassed, with operator_classes set to a list of BaseConditionOperator subclasses.

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

operator_classes = [][source]¶

A list of default operators.

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

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

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

Type:: list of str

lookup_error_class[source]¶: alias of ConditionOperatorNotFoundError

already_registered_error_class[source]¶: alias of ConditionOperatorConflictError

default_errors: RegistryErrorsDict = {'already_registered': 'Could not register condition operator %(item)s: This operator is already registered or its ID conflicts with another operator.', 'attribute_registered': 'Could not register condition operator %(item)s: Another operator %(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 operator was found matching "%(attr_value)s".', 'unregister': 'Could not unregister condition operator %(item)s: This condition was not yet registered.'}[source]¶

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__(operators=[], *args, **kwargs)[source]¶

Initialize the list of operators.

Parameters:: operators (list of type, optional) – A list of BaseConditionOperator subclasses. If this is provided, any value set for operator_classes will be ignored.

get_operator(operator_id, choice)[source]¶

Return an operator instance with the given ID.

Parameters:

operator_id (unicode) – The ID of the operator to retrieve.
choice (djblets.conditions.choices.BaseConditionChoice) – The choice that will own this operator instance.

Returns:

The operator instance matching the ID.

Return type:

BaseConditionOperator

Raises:

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

get_defaults()[source]¶

Return the default operators for the list.

This is used internally by the parent registry classa, and is based on the list of operators provided to the constructor or the value for operator_classes.

Returns:: The default list of operators.
Return type:: list of type

__annotations__ = {'_by_id': 'Dict[int, RegistryItemType]', '_items': 'Set[RegistryItemType]', '_key_order': 'List[int]', '_populated': 'bool', '_registry': 'Dict[str, Dict[object, RegistryItemType]]', 'already_registered_error_class': 'Type[AlreadyRegisteredError]', 'default_errors': 'RegistryErrorsDict', 'errors': 'RegistryErrorsDict', 'item_name': 'Optional[str]', 'lookup_attrs': 'Sequence[str]', 'lookup_error_class': 'Type[ItemLookupError]'}¶

__parameters__ = ()¶