Fixed #24629 -- Unified Transform and Expression APIs

4 files changed, 50 insertions, 27 deletions

diff --git a/docs/howto/custom-lookups.txt b/docs/howto/custom-lookups.txt
index 58b0215019..f398618e39 100644
--- a/docs/howto/custom-lookups.txt
+++ b/docs/howto/custom-lookups.txt
@@ -120,10 +120,7 @@ function ``ABS()`` to transform the value before comparison::
 
   class AbsoluteValue(Transform):
       lookup_name = 'abs'
-
-      def as_sql(self, compiler, connection):
-          lhs, params = compiler.compile(self.lhs)
-          return "ABS(%s)" % lhs, params
+      function = 'ABS'
 
 Next, let's register it for ``IntegerField``::
 
@@ -157,10 +154,7 @@ be done by adding an ``output_field`` attribute to the transform::
 
     class AbsoluteValue(Transform):
         lookup_name = 'abs'
-
-        def as_sql(self, compiler, connection):
-            lhs, params = compiler.compile(self.lhs)
-            return "ABS(%s)" % lhs, params
+        function = 'ABS'
 
         @property
         def output_field(self):
@@ -243,12 +237,9 @@ this transformation should apply to both ``lhs`` and ``rhs``::
 
   class UpperCase(Transform):
       lookup_name = 'upper'
+      function = 'UPPER'
       bilateral = True
 
-      def as_sql(self, compiler, connection):
-          lhs, params = compiler.compile(self.lhs)
-          return "UPPER(%s)" % lhs, params
-
 Next, let's register it::
 
   from django.db.models import CharField, TextField
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
     ``<expression>__<transformation>`` (e.g. ``date__year``).
 
     This class follows the :ref:`Query Expression API <query-expression>`, which
-    implies that you can use ``<expression>__<transform1>__<transform2>``.
+    implies that you can use ``<expression>__<transform1>__<transform2>``. It's
+    a specialized :ref:`Func() expression <func-expressions>` 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
 ~~~~~~~~~~~~~~~~
 
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 2d87d298a3..18fa8ef6bf 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -520,6 +520,14 @@ Models
 * Added the :class:`~django.db.models.functions.Now` database function, which
   returns the current date and time.
 
+* :class:`~django.db.models.Transform` is now a subclass of
+  :ref:`Func() <func-expressions>` which allows ``Transform``\s to be used on
+  the right hand side of an expression, just like regular ``Func``\s. This
+  allows registering some database functions like
+  :class:`~django.db.models.functions.Length`,
+  :class:`~django.db.models.functions.Lower`, and
+  :class:`~django.db.models.functions.Upper` as transforms.
+
 * :class:`~django.db.models.SlugField` now accepts an
   :attr:`~django.db.models.SlugField.allow_unicode` argument to allow Unicode
   characters in slugs.