Fixed #24629 -- Unified Transform and Expression APIs

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.

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
 ~~~~~~~~~~~~~~~~