Added lookup registration API docs

This commit is contained in:
Anssi Kääriäinen 2014-01-18 10:53:24 +02:00
parent 83aa500428
commit fa7a7195f1
2 changed files with 36 additions and 6 deletions

View File

@ -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.

View File

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