API

Module queryable_properties.properties

class queryable_properties.properties.AggregateProperty(aggregate, **kwargs)

A property that is based on an aggregate that is used to provide both queryset annotations as well as getter values.

get_value(obj)

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.

class queryable_properties.properties.AnnotationProperty(annotation, **kwargs)

A property that is based on a static annotation that is even used to provide getter values.

get_annotation(cls)

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.RelatedExistenceCheckProperty(relation_path, negated=False, **kwargs)

A property that checks whether related objects to the one that uses the property exist in the database and returns a corresponding boolean value.

Supports queryset filtering and CASE/WHEN-based annotating.

get_value(obj)

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.

class queryable_properties.properties.QueryableProperty(verbose_name=None)

Base class for all queryable property definitions, which provide methods for single object as well as queryset interaction.

cached = False

Determines if the result of the getter is cached, like Python’s/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.

property short_description

Return the verbose name of this property as its short description, which is required for the admin integration.

Returns:

The verbose name of this property.

Return type:

str

get_value(obj)

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)

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, annotation_based=False, **kwargs)

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

get_value = None

get_filter = None

getter(method, cached=None)

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)

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, remaining_lookups_via_parent=None)

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.

• remaining_lookups_via_parent (bool) – True if lookup-based filters should fall back to the base class implementation for lookups without a registered filter function; otherwise False. None if this information should not be changed.

Returns:

A cloned queryable property.

Return type:

queryable_property

annotater(method)

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)

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(descriptor, obj, value, return_value)

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:

• descriptor (queryable_properties.properties.base.QueryablePropertyDescriptor) – The descriptor of 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(descriptor, obj, value, return_value)

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:

• descriptor (queryable_properties.properties.base.QueryablePropertyDescriptor) – The descriptor of 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(descriptor, obj, value, return_value)

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

Parameters:

• descriptor (queryable_properties.properties.base.QueryablePropertyDescriptor) – The descriptor of 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(descriptor, obj, value, return_value)

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

Parameters:

• descriptor (queryable_properties.properties.base.QueryablePropertyDescriptor) – The descriptor of 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.AnnotationGetterMixin(cached=None, *args, **kwargs)

A mixin for queryable properties that support annotation and use their annotation even to provide the value for their getter (i.e. perform a query to retrieve the getter value).

get_queryset(model)

Construct a base queryset for the given model class that can be used to build queries in property code.

Parameters:

model – The model class to build the queryset for.

get_queryset_for_object(obj)

Construct a base queryset that can be used to retrieve the getter value for the given object.

Parameters:

obj (django.db.models.Model) – The object to build the queryset for.

Returns:

A base queryset for the correct model that is already filtered for the given object.

Return type:

django.db.models.QuerySet

class queryable_properties.properties.AnnotationMixin(*args, **kwargs)

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

property admin_order_field

Return the field name for the ordering in the admin, which is simply the property’s name since it’s annotatable.

Returns:

The field name for ordering in the admin.

Return type:

str

get_annotation(cls)

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.

queryable_properties.properties.boolean_filter(method)

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.LookupFilterMixin(*args, **kwargs)

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

classmethod lookup_filter(*lookups)

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)

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

queryable_properties.properties.lookup_filter(*lookups)

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

class queryable_properties.properties.SetterMixin

A mixin for queryable properties that also define a setter.

set_value(obj, value)

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

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

get_update_kwargs(cls, value)

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

class queryable_properties.properties.MappingProperty(attribute_path, output_field, mappings, default=None, **kwargs)

A property that translates values of an attribute into other values using defined mappings.

get_value(obj)

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_annotation(cls)

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, **kwargs)

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.

get_value(obj)

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.

class queryable_properties.properties.ValueCheckProperty(attribute_path, *values, **kwargs)

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.

get_value(obj)

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.

class queryable_properties.properties.SubqueryExistenceCheckProperty(queryset, negated=False, **kwargs)

A property that checks whether or not certain objects exist in the database using a custom subquery.

class queryable_properties.properties.SubqueryFieldProperty(queryset, field_name, output_field=None, **kwargs)

A property that returns a field value contained in a subquery, extracting it from the first row of the subquery’s result set.

Module queryable_properties.admin

class queryable_properties.admin.QueryablePropertiesAdmin(*args, **kwargs)

Base class for admin classes which allows to use queryable properties in various admin features.

Intended to be used in place of Django’s regular ModelAdmin class.

class queryable_properties.admin.QueryablePropertiesAdminMixin(*args, **kwargs)

A mixin for admin classes including inlines that allows to use queryable properties in various admin features.

list_select_properties = ()

A sequence of queryable property names that should be selected.

get_list_select_properties(request)

Wrapper around the list_select_properties attribute that allows to dynamically create the list of queryable property names to select based on the given request.

Parameters:

request (django.http.HttpRequest) – The request to the admin.

Returns:

A sequence of queryable property names to select.

Return type:

collections.Sequence[str]

process_queryable_property_filters(list_filter)

Process a sequence of list filters to create a new sequence in which queryable property references are replaced with custom callables that make them compatible with Django’s filter workflow.

Parameters:

list_filter (collections.Sequence) – The list filter sequence.

Returns:

The processed list filter sequence.

Return type:

list

class queryable_properties.admin.QueryablePropertiesStackedInline(*args, **kwargs)

Base class for stacked inline classes which allows to use queryable properties in various admin features.

Intended to be used in place of Django’s regular StackedInline class.

class queryable_properties.admin.QueryablePropertiesTabularInline(*args, **kwargs)

Base class for tabular inline classes which allows to use queryable properties in various admin features.

Intended to be used in place of Django’s regular TabularInline class.

Module queryable_properties.managers

class queryable_properties.managers.QueryablePropertiesManager(*args, **kwargs)

A special manager class that allows to use queryable properties methods and returns QueryablePropertiesQuerySet instances.

classmethod get_for_model(model, using=None, hints=None)

Get a new manager with queryable properties functionality for the given model.

Parameters:

• model – The model class for which the manager should be built.

• using (str | None) – An optional name of the database connection to use.

• hints (dict | None) – Optional hints for the db connection.

Returns:

A new manager with queryable properties functionality.

Return type:

QueryablePropertiesManager

class queryable_properties.managers.QueryablePropertiesManagerMixin(*args, **kwargs)

A mixin for Django’s django.db.models.Manager objects that allows to use queryable properties methods and returns QueryablePropertiesQuerySet instances.

classmethod apply_to(manager)

Copy the given manager and apply this mixin (and thus queryable properties functionality) to it, returning a new manager that allows to use queryable property interaction.

Parameters:

manager (Manager) – The manager to apply this mixin to.

Returns:

A copy of the given manager with queryable properties functionality.

Return type:

QueryablePropertiesManager

select_properties(*names)

Return a new queryset and 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

class queryable_properties.managers.QueryablePropertiesQuerySet(*args, **kwargs)

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

classmethod get_for_model(model)

Get a new queryset with queryable properties functionality for the given model. The queryset is built using the model’s default manager.

Parameters:

model – The model class for which the queryset should be built.

Returns:

A new queryset with queryable properties functionality.

Return type:

QueryablePropertiesQuerySet

class queryable_properties.managers.QueryablePropertiesQuerySetMixin(*args, **kwargs)

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

classmethod apply_to(queryset)

Copy the given queryset and apply this mixin (and thus queryable properties functionality) to it, returning a new queryset that allows to use queryable property interaction.

Parameters:

queryset (QuerySet) – The queryset to apply this mixin to.

Returns:

A copy of the given queryset with queryable properties functionality.

Return type:

QueryablePropertiesQuerySet

select_properties(*names)

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

Module queryable_properties.utils

queryable_properties.utils.get_queryable_property(model, name)

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.prefetch_queryable_properties(model_instances, *property_paths)

Populate the queryable property caches for a list of model instances based on the given property paths.

Parameters:

• model_instances (collections.Sequence) – The model instances to prefetch the property values for. The instances may be objects of different models as long as the given property paths are valid for all of them.

• property_paths (str) – The paths to the properties whose values should be fetched, which are need to be annotatable. The paths may contain the lookup separator to fetch values of properties on related objects (make sure that the related objects are already prefetched to avoid additional queries).

queryable_properties.utils.reset_queryable_property(obj, name)

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

The requested queryable property does not exist.

exception queryable_properties.exceptions.QueryablePropertyError

Some kind of problem with a queryable property.