From fa7a7195f1952a9c8dea7f6e89ee13f81757eda7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Anssi=20K=C3=A4=C3=A4ri=C3=A4inen?= <akaariai@gmail.com>
Date: Sat, 18 Jan 2014 10:53:24 +0200
Subject: [PATCH] Added lookup registration API docs

---
 docs/ref/models/custom-lookups.txt | 35 +++++++++++++++++++++++++-----
 docs/ref/models/fields.txt         |  7 ++++++
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/docs/ref/models/custom-lookups.txt b/docs/ref/models/custom-lookups.txt
index 2561d55640..7798e92d30 100644
--- a/docs/ref/models/custom-lookups.txt
+++ b/docs/ref/models/custom-lookups.txt
@@ -236,6 +236,13 @@ to this API.
     qn.compile(expression) should be used. The qn.compile() method will take
     care of calling vendor-specific methods of the expression.
 
+.. method:: get_lookup(lookup_name)
+
+    The ``get_lookup()`` method is used to fetch lookups. By default the
+    lookup is fetched from the expression's output type in the same way
+    described in registering and fetching lookup documentation below.
+    It is possible to override this method to alter that behaviour.
+
 .. method:: as_vendorname(qn, connection)
 
     Works like ``as_sql()`` method. When an expression is compiled by
@@ -244,12 +251,6 @@ to this API.
     The vendorname is one of ``postgresql``, ``oracle``, ``sqlite`` or
     ``mysql`` for Django's built-in backends.
 
-.. method:: get_lookup(lookup_name)
-
-    The ``get_lookup()`` method is used to fetch lookups. By default the lookup
-    is fetched from the expression's output type, but it is possible to
-    override this method to alter that behaviour.
-
 .. attribute:: output_type
 
     The ``output_type`` attribute is used by the ``get_lookup()`` method to check for
@@ -311,3 +312,25 @@ Transform reference
     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 ``__``.
+
+.. _lookup-registration-api:
+
+Registering and fetching lookups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The lookup registration API is explained below.
+
+.. classmethod:: register_lookup(lookup)
+
+    Registers the Lookup or Transform for the class. For example
+    ``DateField.register_lookup(YearExact)`` will register ``YearExact`` for
+    all ``DateFields`` in the project, but also for fields that are instances
+    of a subclass of ``DateField`` (for example ``DateTimeField``).
+
+.. method:: get_lookup(lookup_name)
+
+    Django uses ``get_lookup(lookup_name)`` to fetch lookups or transforms.
+    The implementation of ``get_lookup()`` fetches lookups or transforms
+    registered for the current class based on their lookup_name attribute.
+
+The lookup registration API is available for ``Transform`` and ``Field`` classes.
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index cc2a4cdcf4..2f62a6448b 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -343,6 +343,13 @@ underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`.
 A list of validators to run for this field. See the :doc:`validators
 documentation </ref/validators>` for more information.
 
+Registering and fetching lookups
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Field`` implements the :ref:`lookup registration API <lookup-registration-api>`.
+The API can be used to customize which lookups are available for a field class, and
+how lookups are fetched from a field.
+
 .. _model-field-types:
 
 Field types