API

Module queryable_properties.properties

class queryable_properties.properties.QueryableProperty[source]

Base class for all queryable properties, which are basically simple descriptors with some added methods for queryset interaction.

cached = False

Determines if the result of the getter is cached, like Django’s cached_property.

filter_requires_annotation = False

Determines if using the property to filter requires annotating first.

setter_cache_behavior(obj, value, return_value)

Determines what happens if the setter of a cached property is used.

get_value(obj)[source]

Getter method for the queryable property, which will be called when the property is read-accessed.

Parameters:obj (django.db.models.Model) – The object on which the property was accessed.
Returns:The getter value.
get_filter(cls, lookup, value)[source]

Generate a django.db.models.Q object that emulates filtering a queryset using this property.

Parameters:
  • cls (type) – The model class of which a queryset should be filtered.
  • lookup (str) – The lookup to use for the filter (e.g. ‘exact’, ‘lt’, etc.)
  • value – The value passed to the filter condition.
Returns:

A Q object to filter using this property.

Return type:

django.db.models.Q

class queryable_properties.properties.queryable_property(getter=None, cached=None)[source]

A queryable property that is intended to be used as a decorator.

getter(method, cached=None)[source]

Decorator for a function or method that is used as the getter of this queryable property. May be used as a parameter-less decorator (@getter) or as a decorator with keyword arguments (@getter(cached=True)).

Parameters:
  • method (function) – The method to decorate.
  • cached (bool | None) – If True, values returned by the decorated getter method will be cached. A value of None means no change.
Returns:

A cloned queryable property.

Return type:

queryable_property

setter(method, cache_behavior=None)[source]

Decorator for a function or method that is used as the setter of this queryable property. May be used as a parameter-less decorator (@setter) or as a decorator with keyword arguments (@setter(cache_behavior=DO_NOTHING)).

Parameters:
  • method (function) – The method to decorate.
  • cache_behavior (function | None) – A function that defines how the setter interacts with cached values. A value of None means no change.
Returns:

A cloned queryable property.

Return type:

queryable_property

filter(method, requires_annotation=None, lookups=None, boolean=False)[source]

Decorator for a function or method that is used to generate a filter for querysets to emulate filtering by this queryable property. May be used as a parameter-less decorator (@filter) or as a decorator with keyword arguments (@filter(requires_annotation=False)). May be used to define a one-for-all filter function or a filter function that will be called for certain lookups only using the lookups argument.

Parameters:
  • method (function | classmethod | staticmethod) – The method to decorate.
  • requires_annotation (bool | None) – True if filtering using this queryable property requires its annotation to be applied first; otherwise False. None if this information should not be changed.
  • lookups (collections.Iterable[str] | None) – If given, the decorated function or method will be used for the specified lookup(s) only. Automatically adds the LookupFilterMixin to this property if this is used.
  • boolean (bool) – If True, the decorated function or method is expected to be a simple boolean filter, which doesn’t take the lookup and value parameters and should always return a Q object representing the positive (i.e. True) filter case. The decorator will automatically negate the condition if the filter was called with a False value.
Returns:

A cloned queryable property.

Return type:

queryable_property

annotater(method)[source]

Decorator for a function or method that is used to generate an annotation to represent this queryable property in querysets. The AnnotationMixin will automatically applied to this property when this decorator is used.

Parameters:method (function | classmethod | staticmethod) – The method to decorate.
Returns:A cloned queryable property.
Return type:queryable_property
updater(method)[source]

Decorator for a function or method that is used to resolve an update keyword argument for this queryable property into the actual update keyword arguments.

Parameters:method (function | classmethod | staticmethod) – The method to decorate.
Returns:A cloned queryable property.
Return type:queryable_property
queryable_properties.properties.CACHE_RETURN_VALUE(prop, obj, value, return_value)[source]

Setter cache behavior function that will update the cache for the cached queryable property on the object in question with the return value of the setter function/method.

Parameters:
  • prop (QueryableProperty) – The property whose setter was used.
  • obj (django.db.models.Model) – The object the setter was used on.
  • value – The value that was passed to the setter.
  • return_value – The return value of the setter function/method.
queryable_properties.properties.CACHE_VALUE(prop, obj, value, return_value)[source]

Setter cache behavior function that will update the cache for the cached queryable property on the object in question with the (raw) value that was passed to the setter.

Parameters:
  • prop (QueryableProperty) – The property whose setter was used.
  • obj (django.db.models.Model) – The object the setter was used on.
  • value – The value that was passed to the setter.
  • return_value – The return value of the setter function/method.
queryable_properties.properties.CLEAR_CACHE(prop, obj, value, return_value)[source]

Setter cache behavior function that will clear the cached value for a cached queryable property on objects after the setter was used.

Parameters:
  • prop (QueryableProperty) – The property whose setter was used.
  • obj (django.db.models.Model) – The object the setter was used on.
  • value – The value that was passed to the setter.
  • return_value – The return value of the setter function/method.
queryable_properties.properties.DO_NOTHING(prop, obj, value, return_value)[source]

Setter cache behavior function that will do nothing after the setter of a cached queryable property was used, retaining previously cached values.

Parameters:
  • prop (QueryableProperty) – The property whose setter was used.
  • obj (django.db.models.Model) – The object the setter was used on.
  • value – The value that was passed to the setter.
  • return_value – The return value of the setter function/method.
class queryable_properties.properties.AggregateProperty(aggregate, cached=False)[source]
__init__(aggregate, cached=False)[source]

Initialize a new property that gets its value by retrieving an aggregated value from the database.

Parameters:
  • aggregate (django.db.models.Aggregate) – The aggregate to use to determine the value of this property.
  • cached (bool) – Whether or not this property should use a cached getter. If the property is not cached, the getter will perform the corresponding aggregate query on every access.
get_annotation(cls)[source]

Construct an annotation representing this property that can be added to querysets of the model associated with this property.

Parameters:cls (type) – The model class of which a queryset should be annotated.
Returns:An annotation object.
class queryable_properties.properties.RangeCheckProperty(min_attribute_path, max_attribute_path, value, include_boundaries=True, in_range=True, include_missing=False)[source]

A property that checks if a static or dynamic value is contained in a range expressed by two field values and returns a corresponding boolean value.

Supports queryset filtering and CASE/WHEN-based annotating.

__init__(min_attribute_path, max_attribute_path, value, include_boundaries=True, in_range=True, include_missing=False)[source]

Initialize a new property that checks if a value is contained in a range expressed by two field values.

Parameters:
  • min_attribute_path (str) – The name of the attribute to get the lower boundary from. May also be a more complex path to a related attribute using dot-notation (like with operator.attrgetter()). If an intermediate value on the path is None, it will be treated as a missing value instead of raising an exception. The behavior is the same if an intermediate value raises an ObjectDoesNotExist error.
  • max_attribute_path (str) – The name of the attribute to get the upper boundary from. The same behavior as for the lower boundary applies.
  • value – The value which is tested against the boundary. May be a callable which can be called without any arguments, whose return value will then be used as the test value.
  • include_boundaries (bool) – Whether or not the value is considered a part of the range if it is exactly equal to one of the boundaries.
  • in_range (bool) – Configures whether the property should return True if the value is in range (in_range=True) or if it is out of the range (in_range=False). This also affects the impact of the include_boundaries and include_missing parameters.
  • include_missing (bool) – Whether or not a missing value is considered a part of the range (see the description of min_attribute_path). Useful e.g. for nullable fields.
class queryable_properties.properties.ValueCheckProperty(attribute_path, *values)[source]

A property that checks if an attribute of a model instance or a related object contains a certain value or one of multiple specified values and returns a corresponding boolean value.

Supports queryset filtering and CASE/WHEN-based annotating.

__init__(attribute_path, *values)[source]

Initialize a new property that checks for certain field values.

Parameters:
  • attribute_path (str) – The name of the attribute to compare against. May also be a more complex path to a related attribute using dot-notation (like with operator.attrgetter()). If an intermediate value on the path is None, it will be treated as “no match” instead of raising an exception. The behavior is the same if an intermediate value raises an ObjectDoesNotExist error.
  • values – The value(s) to check for.
class queryable_properties.properties.AnnotationMixin(*args, **kwargs)[source]

A mixin for queryable properties that allows to add an annotation to represent them to querysets.

get_annotation(cls)[source]

Construct an annotation representing this property that can be added to querysets of the model associated with this property.

Parameters:cls (type) – The model class of which a queryset should be annotated.
Returns:An annotation object.
class queryable_properties.properties.LookupFilterMixin(*args, **kwargs)[source]

A mixin for queryable properties that allows to implement queryset filtering via individual methods for different lookups.

classmethod lookup_filter(*lookups)[source]

Decorator for individual filter methods of classes that use the LookupFilterMixin to register the decorated methods for the given lookups.

Parameters:lookups (str) – The lookups to register the decorated method for.
Returns:The actual internal decorator.
Return type:function
classmethod boolean_filter(method)[source]

Decorator for individual filter methods of classes that use the LookupFilterMixin to register the methods that are simple boolean filters (i.e. the filter can only be called with a True or False value). This automatically restricts the usable lookups to exact. Decorated methods should not expect the lookup and value parameters and should always return a Q object representing the positive (i.e. True) filter case. The decorator will automatically negate the condition if the filter was called with a False value.

Parameters:method (function) – The method to decorate.
Returns:The decorated method.
Return type:function
class queryable_properties.properties.SetterMixin[source]

A mixin for queryable properties that also define a setter.

set_value(obj, value)[source]

Setter method for the queryable property, which will be called when the property is write-accessed.

Parameters:
  • obj (django.db.models.Model) – The object on which the property was accessed.
  • value – The value to set.
class queryable_properties.properties.UpdateMixin[source]

A mixin for queryable properties that allows to use themselves in update queries.

get_update_kwargs(cls, value)[source]

Resolve an update keyword argument for this property into the actual keyword arguments to emulate an update using this property.

Parameters:
  • cls (type) – The model class of which an update query should be performed.
  • value – The value passed to the update call for this property.
Returns:

The actual keyword arguments to set in the update call instead of the given one.

Return type:

dict

Module queryable_properties.managers

class queryable_properties.managers.QueryablePropertiesQuerySet(*args, **kwargs)[source]

A special queryset class that allows to use queryable properties in its filter conditions, annotations and update queries.

class queryable_properties.managers.QueryablePropertiesQuerySetMixin(*args, **kwargs)[source]

A mixin for Django’s django.db.models.QuerySet objects that allows to use queryable properties in filters, annotations and update queries.

select_properties(*names)[source]

Add the annotations of the queryable properties with the specified names to this query. The annotation values will be cached in the properties of resulting model instances, regardless of the regular caching behavior of the queried properties.

Parameters:names – Names of queryable properties.
Returns:A copy of this queryset with the added annotations.
Return type:QuerySet
managers.QueryablePropertiesManager = <class 'django.db.models.manager.ManagerFromQueryablePropertiesQuerySet'>

Module queryable_properties.utils

queryable_properties.utils.MISSING_OBJECT = <object object>

Arbitrary object to represent that an object in an attribute chain is missing.

queryable_properties.utils.get_queryable_property(model, name)[source]

Retrieve the queryable_properties.properties.QueryableProperty object with the given attribute name from the given model class or raise an error if no queryable property with that name exists on the model class.

Parameters:
  • model (type) – The model class to retrieve the property object from.
  • name (str) – The name of the property to retrieve.
Returns:

The queryable property.

Return type:

queryable_properties.properties.QueryableProperty

queryable_properties.utils.reset_queryable_property(obj, name)[source]

Reset the cached value of the queryable property with the given name on the given model instance. Read-accessing the property on this model instance at a later point will therefore execute the property’s getter again.

Parameters:
  • obj (django.db.models.Model) – The model instance to reset the cached value on.
  • name (str) – The name of the queryable property.

Module queryable_properties.exceptions

exception queryable_properties.exceptions.QueryablePropertyDoesNotExist[source]

The requested queryable property does not exist.

exception queryable_properties.exceptions.QueryablePropertyError[source]

Some kind of problem with a queryable property.