diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/howto/custom-model-fields.txt | 61 | ||||
| -rw-r--r-- | docs/ref/models/fields.txt | 23 | ||||
| -rw-r--r-- | docs/releases/1.10.txt | 19 |
3 files changed, 20 insertions, 83 deletions
diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 99dd1e217a..1730419787 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -577,67 +577,6 @@ the end. You should also update the model's attribute if you make any changes to the value so that code holding references to the model will always see the correct value. -.. _preparing-values-for-use-in-database-lookups: - -Preparing values for use in database lookups -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As with value conversions, preparing a value for database lookups is a -two phase process. - -:meth:`.get_prep_lookup` performs the first phase of lookup preparation: -type conversion and data validation. - -Prepares the ``value`` for passing to the database when used in a lookup (a -``WHERE`` constraint in SQL). The ``lookup_type`` parameter will be one of the -valid Django filter lookups: ``exact``, ``iexact``, ``contains``, ``icontains``, -``gt``, ``gte``, ``lt``, ``lte``, ``in``, ``startswith``, ``istartswith``, -``endswith``, ``iendswith``, ``range``, ``year``, ``month``, ``day``, -``isnull``, ``search``, ``regex``, and ``iregex``. - -If you are using :doc:`custom lookups </howto/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 -your field does not support that type of lookup. For many fields, you can get -by with handling the lookup types that need special handling for your field -and pass the rest to the :meth:`~Field.get_db_prep_lookup` method of the parent -class. - -If you needed to implement :meth:`.get_db_prep_save`, you will usually need to -implement :meth:`.get_prep_lookup`. If you don't, :meth:`.get_prep_value` will -be called by the default implementation, to manage ``exact``, ``gt``, ``gte``, -``lt``, ``lte``, ``in`` and ``range`` lookups. - -You may also want to implement this method to limit the lookup types that could -be used with your custom field type. - -Note that, for ``"range"`` and ``"in"`` lookups, ``get_prep_lookup`` will receive -a list of objects (presumably of the right type) and will need to convert them -to a list of things of the right type for passing to the database. Most of the -time, you can reuse ``get_prep_value()``, or at least factor out some common -pieces. - -For example, the following code implements ``get_prep_lookup`` to limit the -accepted lookup types to ``exact`` and ``in``:: - - class HandField(models.Field): - # ... - - def get_prep_lookup(self, lookup_type, value): - # We only handle 'exact' and 'in'. All others are errors. - if lookup_type == 'exact': - return self.get_prep_value(value) - elif lookup_type == 'in': - return [self.get_prep_value(v) for v in value] - else: - raise TypeError('Lookup type %r not supported.' % lookup_type) - -For performing database-specific data conversions required by a lookup, -you can override :meth:`~Field.get_db_prep_lookup`. - .. _specifying-form-field-for-model-field: Specifying the form field for a model field diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 3ecc213892..5bd1a148b8 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -1717,8 +1717,7 @@ Field API reference ``Field`` is an abstract class that represents a database table column. Django uses fields to create the database table (:meth:`db_type`), to map Python types to database (:meth:`get_prep_value`) and vice-versa - (:meth:`from_db_value`), and to apply :doc:`/ref/models/lookups` - (:meth:`get_prep_lookup`). + (:meth:`from_db_value`). A field is thus a fundamental piece in different Django APIs, notably, :class:`models <django.db.models.Model>` and :class:`querysets @@ -1847,26 +1846,6 @@ Field API reference See :ref:`preprocessing-values-before-saving` for usage. - When a lookup is used on a field, the value may need to be "prepared". - Django exposes two methods for this: - - .. method:: get_prep_lookup(lookup_type, value) - - Prepares ``value`` to the database prior to be used in a lookup. - The ``lookup_type`` will be the registered name of the lookup. For - example: ``"exact"``, ``"iexact"``, or ``"contains"``. - - See :ref:`preparing-values-for-use-in-database-lookups` for usage. - - .. method:: get_db_prep_lookup(lookup_type, value, connection, prepared=False) - - Similar to :meth:`get_db_prep_value`, but for performing a lookup. - - As with :meth:`get_db_prep_value`, the specific connection that will - be used for the query is passed as ``connection``. In addition, - ``prepared`` describes whether the value has already been prepared with - :meth:`get_prep_lookup`. - Fields often receive their values as a different type, either from serialization or from forms. diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt index 826752996b..e750fb1d47 100644 --- a/docs/releases/1.10.txt +++ b/docs/releases/1.10.txt @@ -677,6 +677,25 @@ You can check if your database has any of the removed hashers like this:: # Unsalted MD5 passwords might not have an 'md5$$' prefix: User.objects.filter(password__length=32) +``Field.get_prep_lookup()`` and ``Field.get_db_prep_lookup()`` methods are removed +---------------------------------------------------------------------------------- + +If you have a custom field that implements either of these methods, register a +custom lookup for it. For example:: + + from django.db.models import Field + from django.db.models.lookups import Exact + + class MyField(Field): + ... + + class MyFieldExact(Exact): + def get_prep_lookup(self): + # do_custom_stuff_for_myfield + .... + + MyField.register_lookup(MyFieldExact) + :mod:`django.contrib.gis` ------------------------- |