Commits

Anonymous committed 8a8268c

[1.2.X] Fixed #15308 -- Sphinx/reST fixes for the Custom Model Fields docs.

Backport of [15447] from trunk.

Comments (0)

Files changed (1)

docs/howto/custom-model-fields.txt

 What does a field class do?
 ---------------------------
 
+.. class:: Field
+
 All of Django's fields (and when we say *fields* in this document, we always
 mean model fields and not :doc:`form fields </ref/forms/fields>`) are subclasses
 of :class:`django.db.models.Field`. Most of the information that Django records
     you want your fields to be more strict about the options they select, or
     to use the simpler, more permissive behavior of the current fields.
 
+.. method:: Field.__init__
+
 The :meth:`~django.db.models.Field.__init__` method takes the following
 parameters:
 
 The ``SubfieldBase`` metaclass
 ------------------------------
 
+.. class:: django.db.models.SubfieldBase
+
 As we indicated in the introduction_, field subclasses are often needed for
 two reasons: either to take advantage of a custom database column type, or to
 handle complex Python types. Obviously, a combination of the two is also
 little complex, but the code you need to write in your ``Field`` class is
 simple: make sure your field subclass uses a special metaclass:
 
-.. class:: django.db.models.SubfieldBase
-
 For example::
 
     class HandField(models.Field):
         def __init__(self, *args, **kwargs):
             # ...
 
-This ensures that the :meth:`to_python` method, documented below, will always be
-called when the attribute is initialized.
+This ensures that the :meth:`.to_python` method, documented below, will always
+be called when the attribute is initialized.
 
 ModelForms and custom fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you use :class:`~django.db.models.SubfieldBase`, :meth:`to_python`
+If you use :class:`~django.db.models.SubfieldBase`, :meth:`.to_python`
 will be called every time an instance of the field is assigned a
 value. This means that whenever a value may be assigned to the field,
 you need to ensure that it will be of the correct datatype, or that
 custom field performs whatever input validation and data cleaning is
 necessary to convert user-provided form input into a
 `to_python()`-compatible model field value. This may require writing a
-custom form field, and/or implementing the :meth:`formfield` method on
+custom form field, and/or implementing the :meth:`.formfield` method on
 your field to return a form field class whose `to_python()` returns the
 correct datatype.
 
 Documenting your custom field
 -----------------------------
 
-.. class:: django.db.models.Field
-
-.. attribute:: description
+.. attribute:: Field.description
 
 As always, you should document your field type, so users will know what it is.
 In addition to providing a docstring for it, which is useful for developers,
 field type via the :doc:`django.contrib.admindocs
 </ref/contrib/admin/admindocs>` application. To do this simply provide
 descriptive text in a ``description`` class attribute of your custom field. In
-the above example, the type description displayed by the ``admindocs``
+the above example, the description displayed by the ``admindocs``
 application for a ``HandField`` will be 'A hand of cards (bridge style)'.
 
 Useful methods
 Custom database types
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: db_type(self, connection)
+.. method:: Field.db_type(self, connection)
 
 .. versionadded:: 1.2
    The ``connection`` argument was added to support multiple databases.
 taking into account the connection object, and the settings associated with it.
 
 Say you've created a PostgreSQL custom type called ``mytype``. You can use this
-field with Django by subclassing ``Field`` and implementing the :meth:`db_type`
-method, like so::
+field with Django by subclassing ``Field`` and implementing the
+:meth:`.db_type` method, like so::
 
     from django.db import models
 
 If you aim to build a database-agnostic application, you should account for
 differences in database column types. For example, the date/time column type
 in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
-``datetime``. The simplest way to handle this in a ``db_type()`` method is to
-check the ``connection.settings_dict['ENGINE']`` attribute.
+``datetime``. The simplest way to handle this in a :meth:`.db_type`
+method is to check the ``connection.settings_dict['ENGINE']`` attribute.
 
 For example::
 
             else:
                 return 'timestamp'
 
-The :meth:`db_type` method is only called by Django when the framework
-constructs the ``CREATE TABLE`` statements for your application -- that is, when
-you first create your tables. It's not called at any other time, so it can
-afford to execute slightly complex code, such as the ``connection.settings_dict``
-check in the above example.
+The :meth:`.db_type` method is only called by Django when the framework
+constructs the ``CREATE TABLE`` statements for your application -- that is,
+when you first create your tables. It's not called at any other time, so it can
+afford to execute slightly complex code, such as the
+``connection.settings_dict`` check in the above example.
 
 Some database column types accept parameters, such as ``CHAR(25)``, where the
 parameter ``25`` represents the maximum column length. In cases like these,
         my_field = BetterCharField(25)
 
 Finally, if your column requires truly complex SQL setup, return ``None`` from
-:meth:`db_type`. This will cause Django's SQL creation code to skip over this
-field. You are then responsible for creating the column in the right table in
-some other way, of course, but this gives you a way to tell Django to get out of
-the way.
+:meth:`.db_type`. This will cause Django's SQL creation code to skip
+over this field. You are then responsible for creating the column in the right
+table in some other way, of course, but this gives you a way to tell Django to
+get out of the way.
 
 Converting database values to Python objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: to_python(self, value)
+.. method:: Field.to_python(self, value)
 
 Converts a value as returned by your database (or a serializer) to a Python
 object.
 
 In our ``HandField`` class, we're storing the data as a VARCHAR field in the
 database, so we need to be able to process strings and ``Hand`` instances in
-:meth:`to_python`::
+:meth:`.to_python`::
 
     import re
 
 
 **Remember:** If your custom field needs the :meth:`to_python` method to be
 called when it is created, you should be using `The SubfieldBase metaclass`_
-mentioned earlier. Otherwise :meth:`to_python` won't be called automatically.
+mentioned earlier. Otherwise :meth:`.to_python` won't be called
+automatically.
 
 Converting Python objects to query values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: get_prep_value(self, value)
+.. method:: Field.get_prep_value(self, value)
 
 .. versionadded:: 1.2
    This method was factored out of ``get_db_prep_value()``
 
-This is the reverse of :meth:`to_python` when working with the
+This is the reverse of :meth:`.to_python` when working with the
 database backends (as opposed to serialization). The ``value``
 parameter is the current value of the model's attribute (a field has
 no reference to its containing model, so it cannot retrieve the value
 
 This conversion should *not* include any database-specific
 conversions. If database-specific conversions are required, they
-should be made in the call to :meth:`get_db_prep_value`.
+should be made in the call to :meth:`.get_db_prep_value`.
 
 For example::
 
 Converting query values to database values
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: get_db_prep_value(self, value, connection, prepared=False)
+.. method:: Field.get_db_prep_value(self, value, connection, prepared=False)
 
 .. versionadded:: 1.2
    The ``connection`` and ``prepared`` arguments were added to support multiple databases.
 
 Some data types (for example, dates) need to be in a specific format
 before they can be used by a database backend.
-:meth:`get_db_prep_value` is the method where those conversions should
+:meth:`.get_db_prep_value` is the method where those conversions should
 be made. The specific connection that will be used for the query is
 passed as the ``connection`` parameter. This allows you to use
 backend-specific conversion logic if it is required.
 
 The ``prepared`` argument describes whether or not the value has
-already been passed through :meth:`get_prep_value` conversions. When
+already been passed through :meth:`.get_prep_value` conversions. When
 ``prepared`` is False, the default implementation of
-:meth:`get_db_prep_value` will call :meth:`get_prep_value` to do
+:meth:`.get_db_prep_value` will call :meth:`.get_prep_value` to do
 initial data conversions before performing any database-specific
 processing.
 
-.. method:: get_db_prep_save(self, value, connection)
+.. method:: Field.get_db_prep_save(self, value, connection)
 
 .. versionadded:: 1.2
    The ``connection`` argument was added to support multiple databases.
 
 Same as the above, but called when the Field value must be *saved* to
 the database. As the default implementation just calls
-``get_db_prep_value``, you shouldn't need to implement this method
+:meth:`.get_db_prep_value`, you shouldn't need to implement this method
 unless your custom field needs a special conversion when being saved
 that is not the same as the conversion used for normal query
-parameters (which is implemented by ``get_db_prep_value``).
+parameters (which is implemented by :meth:`.get_db_prep_value`).
 
 Preprocessing values before saving
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: pre_save(self, model_instance, add)
+.. method:: Field.pre_save(self, model_instance, add)
 
-This method is called just prior to :meth:`get_db_prep_save` and should return
+This method is called just prior to :meth:`.get_db_prep_save` and should return
 the value of the appropriate attribute from ``model_instance`` for this field.
 The attribute name is in ``self.attname`` (this is set up by
 :class:`~django.db.models.Field`). If the model is being saved to the database
 As with value conversions, preparing a value for database lookups is a
 two phase process.
 
-.. method:: get_prep_lookup(self, lookup_type, value)
+.. method:: Field.get_prep_lookup(self, lookup_type, value)
 
 .. versionadded:: 1.2
    This method was factored out of ``get_db_prep_lookup()``
 
-:meth:`get_prep_lookup` performs the first phase of lookup preparation,
+:meth:`.get_prep_lookup` performs the first phase of lookup preparation,
 performing generic data validity checks
 
 Prepares the ``value`` for passing to the database when used in a lookup (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:`get_db_prep_lookup` method of the parent class.
+and pass the rest to the :meth:`.get_db_prep_lookup` method of the parent class.
 
 If you needed to implement ``get_db_prep_save()``, you will usually need to
 implement ``get_prep_lookup()``. If you don't, ``get_prep_value`` will be
             else:
                 raise TypeError('Lookup type %r not supported.' % lookup_type)
 
-.. method:: get_db_prep_lookup(self, lookup_type, value, connection, prepared=False)
+.. method:: Field.get_db_prep_lookup(self, lookup_type, value, connection, prepared=False)
 
 .. versionadded:: 1.2
    The ``connection`` and ``prepared`` arguments were added to support multiple databases.
 
 Performs any database-specific data conversions required by a lookup.
-As with :meth:`get_db_prep_value`, the specific connection that will
+As with :meth:`.get_db_prep_value`, the specific connection that will
 be used for the query is passed as the ``connection`` parameter.
 The ``prepared`` argument describes whether the value has already been
-prepared with :meth:`get_prep_lookup`.
+prepared with :meth:`.get_prep_lookup`.
 
 Specifying the form field for a model field
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: formfield(self, form_class=forms.CharField, **kwargs)
+.. method:: Field.formfield(self, form_class=forms.CharField, **kwargs)
 
 Returns the default form field to use when this field is displayed in a model.
 This method is called by the :class:`~django.forms.ModelForm` helper.
 </topics/forms/index>` for information about this, and take a look at the code in
 :mod:`django.contrib.localflavor` for some examples of custom widgets.
 
-Continuing our ongoing example, we can write the :meth:`formfield` method as::
+Continuing our ongoing example, we can write the :meth:`.formfield` method as::
 
     class HandField(models.Field):
         # ...
 Emulating built-in field types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: get_internal_type(self)
+.. method:: Field.get_internal_type(self)
 
 Returns a string giving the name of the :class:`~django.db.models.Field`
 subclass we are emulating at the database level. This is used to determine the
 type of database column for simple cases.
 
-If you have created a :meth:`db_type` method, you don't need to worry about
-:meth:`get_internal_type` -- it won't be used much. Sometimes, though, your
+If you have created a :meth:`.db_type` method, you don't need to worry about
+:meth:`.get_internal_type` -- it won't be used much. Sometimes, though, your
 database storage is similar in type to some other field, so you can use that
 other field's logic to create the right column.
 
 No matter which database backend we are using, this will mean that ``syncdb``
 and other SQL commands create the right column type for storing a string.
 
-If :meth:`get_internal_type` returns a string that is not known to Django for
+If :meth:`.get_internal_type` returns a string that is not known to Django for
 the database backend you are using -- that is, it doesn't appear in
 ``django.db.backends.<db_name>.creation.DATA_TYPES`` -- the string will still be
-used by the serializer, but the default :meth:`db_type` method will return
-``None``. See the documentation of :meth:`db_type` for reasons why this might be
+used by the serializer, but the default :meth:`.db_type` method will return
+``None``. See the documentation of :meth:`.db_type` for reasons why this might be
 useful. Putting a descriptive string in as the type of the field for the
 serializer is a useful idea if you're ever going to be using the serializer
 output in some other place, outside of Django.
 Converting field data for serialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. method:: value_to_string(self, obj)
+.. method:: Field.value_to_string(self, obj)
 
 This method is used by the serializers to convert the field into a string for
 output. Calling :meth:`Field._get_val_from_obj(obj)` is the best way to get the