hvad.manager
¶
This module is where most of the functionality is implemented.
-
hvad.manager.
FALLBACK_LANGUAGES
¶ The default sequence for fallback languages, populates itself from
settings.LANGUAGES
, could possibly become a setting on it’s own at some point.
FieldTranslator¶
-
class
hvad.manager.
FieldTranslator
¶ The cache mentioned in this class is the instance of the class itself, since it inherits dict.
Possibly this class is not feature complete since it does not care about multi-relation queries. It should probably use
hvad.fieldtranslator.translate()
after the first level if it hits the Shared Model.てz-
get
(self, key)¶ Returns the translated fieldname for key. If it’s already cached, return it from the cache, otherwise call
build()
-
build
(self, key)¶ Returns the key prefixed by
'master__'
if it’s a shared field, otherwise returns the key unchanged.
-
ValuesMixin¶
-
class
hvad.manager.
ValuesMixin
¶ A mixin class for
django.db.models.query.ValuesQuerySet
which implements the functionality needed byTranslationQueryset.values()
andTranslationQueryset.values_list()
.-
_strip_master
(self, key)¶ Strips
'master__'
from the key if the key starts with that string.
-
iterator
(self)¶ Iterates over the rows from the superclass iterator and calls
_strip_master()
on the key if the row is a dictionary.
-
TranslationQueryset¶
-
class
hvad.manager.
TranslationQueryset
¶ Any method on this queryset that returns a model instance or a queryset of model instances actually returns a Translations Model which gets combined to behave like a Shared Model. While this manager is on the Shared Model, it is actually a manager for the Translations Model since the model gets switched when this queryset is instantiated from the
TranslationManager
.-
override_classes
¶ A dictionary of django classes to hvad classes to mixin when
_clone()
is called with an explicit klass argument.
-
_local_field_names
¶ A list of field names on the Shared Model.
-
_field_translator
¶ The cached field translator for this manager.
-
_real_manager
¶ The real manager of the Shared Model.
-
_fallback_manager
¶ The fallback manager of the Shared Model.
-
_language_code
¶ The language code of this queryset.
-
translations_manager
¶ The (real) manager of the Translations Model.
The Shared Model.
-
field_translator
¶ The field translator for this manager, sets
_field_translator
if it’sNone
.
Returns a list of field names on the Shared Model, sets
_local_field_names
if it’sNone
.
-
_translate_args_kwargs
(self, *args, **kwargs)¶ Translates args (
django.db.models.expressions.Q
objects) and kwargs (dictionary of query lookups and values) to be language aware, by prefixing fields on the Shared Model with'master__'
. Usesfield_translator
for the kwargs and_recurse_q()
for the args. Returns a tuple of translated args and translated kwargs.
-
_translate_fieldnames
(self, fieldnames)¶ Translate a list of fieldnames by prefixing fields on the Shared Model with
'master__'
usingfield_translator
. Returns a list of translated fieldnames.
-
_recurse_q
(self, q)¶ Recursively walks a
django.db.models.expressions.Q
object and translates it’s query lookups to be prefixed by'master__'
if they access a field on Shared Model.Every
django.db.models.expressions.Q
object has an attributedjango.db.models.expressions.Q.children
which is either a list of otherdjango.db.models.expressions.Q
objects or a tuple where the key is the query lookup.This method returns a new
django.db.models.expressions.Q
object.
-
_find_language_code
(self, q)¶ Searches a
django.db.models.expressions.Q
object for language code lookups. If it finds a childdjango.db.models.expressions.Q
object that defines a language code, it returns that language code if it’s notNone
. Used inget()
to ensure a language code is defined.For more information about
django.db.models.expressions.Q
objects, see_recurse_q()
.Returns the language code if one was found or
None
.
-
_split_kwargs
(self, **kwargs)¶ Splits keyword arguments into two dictionaries holding the shared and translated fields.
Returns a tuple of dictionaries of shared and translated fields.
-
_get_class
(self, klass)¶ Given a
django.db.models.query.QuerySet
class or subclass, it checks if the class is a subclass of any class inoverride_classes
and if so, returns a new class which mixes the initial class, the class fromoverride_classes
andTranslationQueryset
. Otherwise returns the class given.
Returns a clone of this queryset but for the shared model. Does so by using
_real_manager
and filtering over this queryset. Returns a queryset for the Shared Model.
-
language
(self, language_code=None)¶ Specifies a language for this queryset. This sets the
_language_code
and filters by the language code.If no language code is given,
django.utils.translations.get_language()
is called to get the current language.Returns a queryset.
-
create
(self, **kwargs)¶ Creates a new instance using the kwargs given. If
_language_code
is not set and language_code is not in kwargs, it usesdjango.utils.translations.get_language()
to get the current language and injects that into kwargs.This causes two queries as opposed to the one by the normal queryset.
Returns the newly created (combined) instance.
-
get
(self, *args, **kwargs)¶ Gets a single instance from this queryset using the args and kwargs given. The args and kwargs are translated using
_translate_args_kwargs()
.If a language code is given in the kwargs, it calls
language()
using the language code provided. If none is given in kwargs, it uses_find_language_code()
on thedjango.db.models.expressions.Q
objects given in args. If no args were given or they don’t contain a language code, it searches thedjango.db.models.sql.where.WhereNode
objects on the current queryset for language codes. If none was found, it callslanguage()
without an argument, which in turn usesdjango.utils.translations.get_language()
to enforce a language to be used in this queryset.Returns a (combined) instance if one can be found for the filters given, otherwise raises an appropriate exception depending on whether no or multiple objects were found.
-
get_or_create
(self, **kwargs)¶ Will try to fetch the translated instance for the kwargs given.
If it can’t find it, it will try to find a shared instance (using
_splitkwargs()
). If it finds a shared instance, it will create the translated instance. If it does not find a shared instance, it will create both.Returns a tuple of a (combined) instance and a boolean flag which is
False
if it found the instance orTrue
if it created either the translated or both instances.
-
filter
(self, *args, **kwargs)¶ Translates args and kwargs using
_translate_args_kwargs()
and calls the superclass using the new args and kwargs.
-
aggregate
(self, *args, **kwargs)¶ Loops through the passed aggregates and translates the fieldnames using
_translate_fieldnames()
and calls the superclass
-
latest
(self, field_name=None)¶ Translates the fieldname (if given) using
field_translator
and calls the superclass.
-
in_bulk
(self, id_list)¶ Not implemented yet.
-
delete
(self)¶ Deletes the Shared Model using
_get_shared_query_set()
.
-
delete_translations
(self)¶ Deletes the translations (and only the translations) by first breaking their relation to the Shared Model and then calling the delete method on the superclass. This uses two queries.
-
update
(self, **kwargs)¶ Updates this queryset using kwargs. Calls
_split_kwargs()
to get two dictionaries holding only the shared or translated fields respectively. If translated fields are given, calls the superclass with the translated fields. If shared fields are given, uses_get_shared_query_set()
to update the shared fields.If both shared and translated fields are updated, two queries are executed, if only one of the two are given, one query is executed.
Returns the count of updated objects, which if both translated and shared fields are given is the sum of the two update calls.
-
values
(self, *fields)¶ Translates fields using
_translated_fieldnames()
and calls the superclass.
-
values_list
(self, *fields, **kwargs)¶ Translates fields using
_translate_fieldnames()
and calls the superclass.
-
dates
(self, field_name, kind, order='ASC')¶ Translates fields using
_translate_fieldnames()
and calls the superclass.
-
complex_filter
(self, filter_obj)¶ Not really implemented yet, but if filter_obj is an empty dictionary it just returns this queryset, since this is required to get admin to work.
-
annotate
(self, *args, **kwargs)¶ Not implemented yet.
-
order_by
(self, *field_names)¶ Translates fields using
_translated_fieldnames()
and calls the superclass.
-
reverse
(self)¶ Not implemented yet.
-
defer
(self, *fields)¶ Not implemented yet.
-
only
(self, *fields)¶ Not implemented yet.
-
_clone
(self, klass=None, setup=False, **kwargs)¶ Injects _local_field_names, _field_translator, _language_code, _real_manager and _fallback_manager into kwargs. If a klass is given, calls
_get_class()
to get a mixed class if necessary.Calls the superclass with the new kwargs and klass.
-
TranslationManager¶
-
class
hvad.manager.
TranslationManager
¶ Manager to be used on
hvad.models.TranslatableModel
.-
translations_model
¶ The Translations Model for this manager.
-
language
(self, language_code=None)¶ Calls
get_query_set()
to get a queryset and callsTranslationQueryset.language()
on that queryset.
-
untranslated
(self)¶ Returns an instance of
FallbackQueryset
for this manager.
-
get_query_set
(self)¶ Returns an instance of
TranslationQueryset
for this manager. The queryset returned will have the master relation to the Shared Model marked to be selected when querying, usingselect_related()
.
-
contribute_to_class
(self, model, name)¶ Contributes this manager, the real manager and the fallback manager onto the class using
contribute_real_manager()
andcontribute_fallback_manager()
.
-
contribute_real_manager
(self)¶ Creates a real manager and contributes it to the model after prefixing the name with an underscore.
-
contribute_fallback_manager
(self)¶ Creates a fallback manager and contributes it to the model after prefixing the name with an underscore and suffixing it with
'_fallback'
.
-
FallbackQueryset¶
-
class
hvad.manager.
FallbackQueryset
¶ A queryset that can optionally use fallbacks and by default only fetches the Shared Model.
-
_translation_fallbacks
¶ List of fallbacks to use (or
None
).
-
iterator
(self)¶ If
_translation_fallbacks
is set, it iterates using the superclass and tries to get the translation using the order of language codes defined in_translation_fallbacks
. As soon as it finds a translation for an object, it yields a combined object using that translation. Otherwise yields an uncombined object. Due to the way this works, it can cause a lot of queries and this should be improved if possible.If no fallbacks are given, it just iterates using the superclass.
-
use_fallbacks
(self, *fallbacks)¶ If this method gets called,
iterator()
will use the fallbacks defined here. If not fallbacks are given,FALLBACK_LANGUAGES
will be used.
-
_clone
(self, klass=None, setup=False, **kwargs)¶ Injects translation_fallbacks into kwargs and calls the superclass.
-
TranslationFallbackManager¶
-
class
hvad.manager.
TranslationFallbackManager
¶ -
use_fallbacks
(self, *fallbacks)¶ Proxies to
FallbackQueryset.use_fallbacks()
by callingget_query_set()
first.
-
get_query_set
(self)¶ Returns an instance of
FallbackQueryset
for this manager.
-
TranslationAwareQueryset¶
-
class
hvad.manager.
TranslationAwareQueryset
¶ -
_language_code
¶ The language code of this queryset.
-
_translate_args_kwargs
(self, *args, **kwargs)¶ Calls
language()
using_language_code
as an argument.Translates args and kwargs into translation aware args and kwargs using
hvad.fieldtranslator.translate()
by iterating over the kwargs dictionary and translating it’s keys and recursing over thedjango.db.models.expressions.Q
objects in args using_recurse_q()
.Returns a triple of newargs, newkwargs and extra_filters where newargs and newkwargs are the translated versions of args and kwargs and extra_filters is a
django.db.models.expressions.Q
object to use to filter for the current language.
-
_recurse_q
(self, q)¶ Recursively translate the keys in the
django.db.models.expressions.Q
object given usinghvad.fieldtranslator.translate()
. For more information aboutdjango.db.models.expressions.Q
, seeTranslationQueryset._recurse_q()
.Returns a tuple of q and language_joins where q is the translated
django.db.models.expressions.Q
object and language_joins is a list of extra language join filters to be applied using the current language.
-
_translate_fieldnames
(self, fields)¶ Calls
language()
using_language_code
as an argument.Translates the fieldnames given using
hvad.fieldtranslator.translate()
Returns a tuple of newfields and extra_filters where newfields is a list of translated fieldnames and extra_filters is a
django.db.models.expressions.Q
object to be used to filter for language joins.
-
language
(self, language_code=None)¶ Sets the
_language_code
attribute either to the language given with language_code or by getting the current language fromdjango.utils.translations.get_language()
. UnlikeTranslationQueryset.language()
, this does not actually filter by the language yet as this happens in_filter_extra()
.
-
get
(self, *args, **kwargs)¶ Gets a single object from this queryset by filtering by args and kwargs, which are first translated using
_translate_args_kwargs()
. Calls_filter_extra()
with the extra_filters returned by_translate_args_kwargs()
to get a queryset from the superclass and to call that queryset.Returns an instance of the model of this queryset or raises an appropriate exception when none or multiple objects were found.
-
filter
(self, *args, **kwargs)¶ Filters the queryset by args and kwargs by translating them using
_translate_args_kwargs()
and calling_filter_extra()
with the extra_filters returned by_translate_args_kwargs()
.
-
aggregate
(self, *args, **kwargs)¶ Not implemented yet.
-
latest
(self, field_name=None)¶ If a fieldname is given, uses
hvad.fieldtranslator.translate()
to translate that fieldname. Calls_filter_extra()
with the extra_filters returned byhvad.fieldtranslator.translate()
if it was used, otherwise with an emptydjango.db.models.expressions.Q
object.
-
in_bulk
(self, id_list)¶ Not implemented yet
-
values
(self, *fields)¶ Calls
_translated_fieldnames()
to translated the fields. Then calls_filter_extra()
with the extra_filters returned by_translated_fieldnames()
.
-
values_list
(self, *fields, **kwargs)¶ Calls
_translated_fieldnames()
to translated the fields. Then calls_filter_extra()
with the extra_filters returned by_translated_fieldnames()
.
-
dates
(self, field_name, kind, order='ASC')¶ Not implemented yet.
-
exclude
(self, *args, **kwargs)¶ Not implemented yet.
-
complex_filter
(self, filter_obj)¶ Not really implemented yet, but if filter_obj is an empty dictionary it just returns this queryset, to make admin work.
-
annotate
(self, *args, **kwargs)¶ Not implemented yet.
-
order_by
(self, *field_names)¶ Calls
_translated_fieldnames()
to translated the fields. Then calls_filter_extra()
with the extra_filters returned by_translated_fieldnames()
.
-
reverse
(self)¶ Not implemented yet.
-
defer
(self, *fields)¶ Not implemented yet.
-
only
(self, *fields)¶ Not implemented yet.
-
_clone
(self, klass=None, setup=False, **kwargs)¶ Injects _language_code into kwargs and calls the superclass.
-
_filter_extra
(self, extra_filters)¶ Filters this queryset by the
django.db.models.expressions.Q
object provided in extra_filters and returns a queryset from the superclass, so that the methods that call this method can directely access methods on the superclass to reduce boilerplate code.
-
TranslationAwareManager¶
-
class
hvad.manager.
TranslationAwareManager
¶ -
get_query_set
(self)¶ Returns an instance of
TranslationAwareQueryset
.
-