From 534aaf56f4a8e261e111426b2a709e2f8816192f Mon Sep 17 00:00:00 2001 From: Josh Smeaton Date: Mon, 3 Aug 2015 12:30:06 +1000 Subject: Fixed #24629 -- Unified Transform and Expression APIs --- docs/ref/models/database-functions.txt | 24 ++++++++++++++++++++++++ docs/ref/models/lookups.txt | 30 +++++++++++++++--------------- 2 files changed, 39 insertions(+), 15 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt index 51a2e4b998..dd0bd59379 100644 --- a/docs/ref/models/database-functions.txt +++ b/docs/ref/models/database-functions.txt @@ -180,6 +180,18 @@ Usage example:: >>> print(author.name_length, author.goes_by_length) (14, None) +It can also be registered as a transform. For example:: + + >>> from django.db.models import CharField + >>> from django.db.models.functions import Length + >>> CharField.register_lookup(Length, 'length') + >>> # Get authors whose name is longer than 7 characters + >>> authors = Author.objects.filter(name__length__gt=7) + +.. versionchanged:: 1.9 + + The ability to register the function as a transform was added. + Lower ------ @@ -188,6 +200,8 @@ Lower Accepts a single text field or expression and returns the lowercase representation. +It can also be registered as a transform as described in :class:`Length`. + Usage example:: >>> from django.db.models.functions import Lower @@ -196,6 +210,10 @@ Usage example:: >>> print(author.name_lower) margaret smith +.. versionchanged:: 1.9 + + The ability to register the function as a transform was added. + Now --- @@ -246,6 +264,8 @@ Upper Accepts a single text field or expression and returns the uppercase representation. +It can also be registered as a transform as described in :class:`Length`. + Usage example:: >>> from django.db.models.functions import Upper @@ -253,3 +273,7 @@ Usage example:: >>> author = Author.objects.annotate(name_upper=Upper('name')).get() >>> print(author.name_upper) MARGARET SMITH + +.. versionchanged:: 1.9 + + The ability to register the function as a transform was added. diff --git a/docs/ref/models/lookups.txt b/docs/ref/models/lookups.txt index c2304209d7..58e6e35bbf 100644 --- a/docs/ref/models/lookups.txt +++ b/docs/ref/models/lookups.txt @@ -42,12 +42,17 @@ register lookups on itself. The two prominent examples are A mixin that implements the lookup API on a class. - .. classmethod:: register_lookup(lookup) + .. classmethod:: register_lookup(lookup, lookup_name=None) Registers a new lookup in the class. For example ``DateField.register_lookup(YearExact)`` will register ``YearExact`` lookup on ``DateField``. It overrides a lookup that already exists with - the same name. + the same name. ``lookup_name`` will be used for this lookup if + provided, otherwise ``lookup.lookup_name`` will be used. + + .. versionchanged:: 1.9 + + The ``lookup_name`` parameter was added. .. method:: get_lookup(lookup_name) @@ -125,7 +130,14 @@ Transform reference ``__`` (e.g. ``date__year``). This class follows the :ref:`Query Expression API `, which - implies that you can use ``____``. + implies that you can use ``____``. It's + a specialized :ref:`Func() expression ` that only accepts + one argument. It can also be used on the right hand side of a filter or + directly as an annotation. + + .. versionchanged:: 1.9 + + ``Transform`` is now a subclass of ``Func``. .. attribute:: bilateral @@ -152,18 +164,6 @@ Transform reference :class:`~django.db.models.Field` instance. By default is the same as its ``lhs.output_field``. - .. method:: as_sql - - To be overridden; raises :exc:`NotImplementedError`. - - .. method:: get_lookup(lookup_name) - - Same as :meth:`~lookups.RegisterLookupMixin.get_lookup()`. - - .. method:: get_transform(transform_name) - - Same as :meth:`~lookups.RegisterLookupMixin.get_transform()`. - Lookup reference ~~~~~~~~~~~~~~~~ -- cgit v1.3