Release notes and other minor docs changes

docs/howto/custom-model-fields.txt

@@ -662,6 +662,12 @@ Django filter lookups: ``exact``, ``iexact``, ``contains``, ``icontains``,
 ``endswith``, ``iendswith``, ``range``, ``year``, ``month``, ``day``,
 ``isnull``, ``search``, ``regex``, and ``iregex``.
 
+.. versionadded:: 1.7
+
+    If you are using :doc:`Custom lookups </ref/models/custom-lookups>` the
+    ``lookup_type`` can be any ``lookup_name`` used by the project's custom
+    lookups.
+
 Your method must be prepared to handle all of these ``lookup_type`` values and
 should raise either a ``ValueError`` if the ``value`` is of the wrong sort (a
 list when you were expecting an object, for example) or a ``TypeError`` if

docs/index.txt

@@ -81,7 +81,8 @@ manipulating the data of your Web application. Learn more about it below:
   :doc:`Transactions <topics/db/transactions>` |
   :doc:`Aggregation <topics/db/aggregation>` |
   :doc:`Custom fields <howto/custom-model-fields>` |
-  :doc:`Multiple databases <topics/db/multi-db>`
+  :doc:`Multiple databases <topics/db/multi-db>` |
+  :doc:`Custom lookups <ref/models/custom-lookups>`
 
 * **Other:**
   :doc:`Supported databases <ref/databases>` |

docs/ref/models/custom-lookups.txt

@@ -28,7 +28,7 @@ databases.
 
 There are two steps to making this work. Firstly we need to implement the
 lookup, then we need to tell Django about it. The implementation is quite
-straightforwards::
+straightforward::
 
   from django.db.models import Lookup
 
@@ -280,7 +280,7 @@ Lookup reference
 .. attribute:: lookup_name
 
     This class level attribute is used when registering lookups. It determines
-    the name used in queries to triger this lookup. For example, ``contains``
+    the name used in queries to trigger this lookup. For example, ``contains``
     or ``exact``. This should not contain the string ``__``.
 
 .. method:: process_lhs(qn, connection)
@@ -292,3 +292,22 @@ Lookup reference
 .. method:: process_rhs(qn, connection)
 
     Behaves the same as ``process_lhs`` but acts on the right-hand side.
+
+Transform reference
+~~~~~~~~~~~~~~~~~~~
+
+.. class:: Transform
+
+    In addition to implementing the query expression API Transforms have the
+    following methods and attributes.
+
+.. attribute:: lhs
+
+    The ``lhs`` (left-hand-side) of a transform contains the value to be
+    transformed. The ``lhs`` implements the query expression API.
+
+.. attribute:: lookup_name
+
+    This class level attribute is used when registering lookups. It determines
+    the name used in queries to trigger this lookup. For example, ``year``
+    or ``dayofweek``. This should not contain the string ``__``.

docs/ref/models/index.txt

@@ -13,4 +13,4 @@ Model API reference. For introductory material, see :doc:`/topics/db/models`.
    instances
    querysets
    queries
-   custom_lookups
+   custom-lookups

docs/ref/models/querysets.txt

@@ -1994,6 +1994,9 @@ specified as keyword arguments to the ``QuerySet`` methods :meth:`filter()`,
 For an introduction, see :ref:`models and database queries documentation
 <field-lookups-intro>`.
 
+Django's inbuilt lookups are listed below. It is also possible to write
+:doc:`custom lookups </ref/models/custom-lookups>` for model fields.
+
 .. fieldlookup:: exact
 
 exact

docs/releases/1.7.txt

@@ -180,6 +180,27 @@ for the following, instead of backend specific behavior.
     finally:
         c.close()
 
+Custom lookups
+~~~~~~~~~~~~~~
+
+It is now possible to write custom lookups and transforms for the ORM.
+Custom lookups work just like Django's inbuilt lookups (e.g. ``lte``,
+``icontains``) while transforms are a new concept.
+
+The :class:`django.db.models.Lookup` class provides a way to add lookup
+operators for model fields. As an example it is possible to add ``day_lte``
+opertor for ``DateFields``.
+
+The :class:`django.db.models.Transform` class allows transformations of
+database values prior to the final lookup. For example it is possible to
+write a ``year`` transform that extracts year from the field's value.
+Transforms allow for chaining. After the ``year`` transform has been added
+to ``DateField`` it is possible to filter on the transformed value, for
+example ``qs.filter(author__birthdate__year__lte=1981)``.
+
+For more information about both custom lookups and transforms refer to
+:doc:`custom lookups </ref/models/custom-lookups>` documentation.
+
 Minor features
 ~~~~~~~~~~~~~~