From eb1c8ce164325e0d8641f14202e12486c70efdb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Anssi=20K=C3=A4=C3=A4ri=C3=A4inen?= Date: Tue, 14 Jan 2014 18:59:36 +0200 Subject: [PATCH] Release notes and other minor docs changes --- docs/howto/custom-model-fields.txt | 6 +++++ docs/index.txt | 3 ++- ...{custom_lookups.txt => custom-lookups.txt} | 23 +++++++++++++++++-- docs/ref/models/index.txt | 2 +- docs/ref/models/querysets.txt | 3 +++ docs/releases/1.7.txt | 21 +++++++++++++++++ 6 files changed, 54 insertions(+), 4 deletions(-) rename docs/ref/models/{custom_lookups.txt => custom-lookups.txt} (94%) diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index b7bcefad53..3d6eeadb61 100644 --- a/docs/howto/custom-model-fields.txt +++ b/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 ` 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 diff --git a/docs/index.txt b/docs/index.txt index f37a597276..1856beb65e 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -81,7 +81,8 @@ manipulating the data of your Web application. Learn more about it below: :doc:`Transactions ` | :doc:`Aggregation ` | :doc:`Custom fields ` | - :doc:`Multiple databases ` + :doc:`Multiple databases ` | + :doc:`Custom lookups ` * **Other:** :doc:`Supported databases ` | diff --git a/docs/ref/models/custom_lookups.txt b/docs/ref/models/custom-lookups.txt similarity index 94% rename from docs/ref/models/custom_lookups.txt rename to docs/ref/models/custom-lookups.txt index 4925685f42..2561d55640 100644 --- a/docs/ref/models/custom_lookups.txt +++ b/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 ``__``. diff --git a/docs/ref/models/index.txt b/docs/ref/models/index.txt index 5d67827fe7..4716c03f95 100644 --- a/docs/ref/models/index.txt +++ b/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 diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index e15e55d05c..7ff28d9a64 100644 --- a/docs/ref/models/querysets.txt +++ b/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 `. +Django's inbuilt lookups are listed below. It is also possible to write +:doc:`custom lookups ` for model fields. + .. fieldlookup:: exact exact diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 9fcad38931..42a09df94b 100644 --- a/docs/releases/1.7.txt +++ b/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 ` documentation. + Minor features ~~~~~~~~~~~~~~