mirror of
https://github.com/django/django.git
synced 2025-08-04 10:59:45 +00:00
Fixed many more ReST indentation errors, somehow accidentally missed from [16955]
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16983 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
parent
5109ac3709
commit
d1e5c55258
129 changed files with 5708 additions and 5740 deletions
|
@ -133,14 +133,14 @@ example). If this sounds a bit tricky, don't worry -- it will become clearer in
|
|||
the examples below. Just remember that you will often end up creating two
|
||||
classes when you want a custom field:
|
||||
|
||||
* The first class is the Python object that your users will manipulate.
|
||||
They will assign it to the model attribute, they will read from it for
|
||||
displaying purposes, things like that. This is the ``Hand`` class in our
|
||||
example.
|
||||
* The first class is the Python object that your users will manipulate.
|
||||
They will assign it to the model attribute, they will read from it for
|
||||
displaying purposes, things like that. This is the ``Hand`` class in our
|
||||
example.
|
||||
|
||||
* The second class is the ``Field`` subclass. This is the class that knows
|
||||
how to convert your first class back and forth between its permanent
|
||||
storage form and the Python form.
|
||||
* The second class is the ``Field`` subclass. This is the class that knows
|
||||
how to convert your first class back and forth between its permanent
|
||||
storage form and the Python form.
|
||||
|
||||
Writing a field subclass
|
||||
========================
|
||||
|
@ -198,33 +198,33 @@ card values plus their suits; 104 characters in total.
|
|||
The :meth:`~django.db.models.Field.__init__` method takes the following
|
||||
parameters:
|
||||
|
||||
* :attr:`~django.db.models.Field.verbose_name`
|
||||
* :attr:`~django.db.models.Field.name`
|
||||
* :attr:`~django.db.models.Field.primary_key`
|
||||
* :attr:`~django.db.models.Field.max_length`
|
||||
* :attr:`~django.db.models.Field.unique`
|
||||
* :attr:`~django.db.models.Field.blank`
|
||||
* :attr:`~django.db.models.Field.null`
|
||||
* :attr:`~django.db.models.Field.db_index`
|
||||
* :attr:`~django.db.models.Field.rel`: Used for related fields (like
|
||||
:class:`ForeignKey`). For advanced use only.
|
||||
* :attr:`~django.db.models.Field.default`
|
||||
* :attr:`~django.db.models.Field.editable`
|
||||
* :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
|
||||
not be serialized when the model is passed to Django's :doc:`serializers
|
||||
</topics/serialization>`. Defaults to ``True``.
|
||||
* :attr:`~django.db.models.Field.unique_for_date`
|
||||
* :attr:`~django.db.models.Field.unique_for_month`
|
||||
* :attr:`~django.db.models.Field.unique_for_year`
|
||||
* :attr:`~django.db.models.Field.choices`
|
||||
* :attr:`~django.db.models.Field.help_text`
|
||||
* :attr:`~django.db.models.Field.db_column`
|
||||
* :attr:`~django.db.models.Field.db_tablespace`: Currently only used with
|
||||
the Oracle backend and only for index creation. You can usually ignore
|
||||
this option.
|
||||
* :attr:`~django.db.models.Field.auto_created`: True if the field was
|
||||
automatically created, as for the `OneToOneField` used by model
|
||||
inheritance. For advanced use only.
|
||||
* :attr:`~django.db.models.Field.verbose_name`
|
||||
* :attr:`~django.db.models.Field.name`
|
||||
* :attr:`~django.db.models.Field.primary_key`
|
||||
* :attr:`~django.db.models.Field.max_length`
|
||||
* :attr:`~django.db.models.Field.unique`
|
||||
* :attr:`~django.db.models.Field.blank`
|
||||
* :attr:`~django.db.models.Field.null`
|
||||
* :attr:`~django.db.models.Field.db_index`
|
||||
* :attr:`~django.db.models.Field.rel`: Used for related fields (like
|
||||
:class:`ForeignKey`). For advanced use only.
|
||||
* :attr:`~django.db.models.Field.default`
|
||||
* :attr:`~django.db.models.Field.editable`
|
||||
* :attr:`~django.db.models.Field.serialize`: If ``False``, the field will
|
||||
not be serialized when the model is passed to Django's :doc:`serializers
|
||||
</topics/serialization>`. Defaults to ``True``.
|
||||
* :attr:`~django.db.models.Field.unique_for_date`
|
||||
* :attr:`~django.db.models.Field.unique_for_month`
|
||||
* :attr:`~django.db.models.Field.unique_for_year`
|
||||
* :attr:`~django.db.models.Field.choices`
|
||||
* :attr:`~django.db.models.Field.help_text`
|
||||
* :attr:`~django.db.models.Field.db_column`
|
||||
* :attr:`~django.db.models.Field.db_tablespace`: Currently only used with
|
||||
the Oracle backend and only for index creation. You can usually ignore
|
||||
this option.
|
||||
* :attr:`~django.db.models.Field.auto_created`: True if the field was
|
||||
automatically created, as for the `OneToOneField` used by model
|
||||
inheritance. For advanced use only.
|
||||
|
||||
All of the options without an explanation in the above list have the same
|
||||
meaning they do for normal Django fields. See the :doc:`field documentation
|
||||
|
@ -415,11 +415,11 @@ that are more complex than strings, dates, integers or floats, then you'll need
|
|||
to override this method. As a general rule, the method should deal gracefully
|
||||
with any of the following arguments:
|
||||
|
||||
* An instance of the correct type (e.g., ``Hand`` in our ongoing example).
|
||||
* An instance of the correct type (e.g., ``Hand`` in our ongoing example).
|
||||
|
||||
* A string (e.g., from a deserializer).
|
||||
* A string (e.g., from a deserializer).
|
||||
|
||||
* Whatever the database returns for the column type you're using.
|
||||
* Whatever the database returns for the column type you're using.
|
||||
|
||||
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
|
||||
|
@ -695,19 +695,19 @@ complex conversions between your Python types and your database and
|
|||
serialization formats. Here are a couple of tips to make things go more
|
||||
smoothly:
|
||||
|
||||
1. Look at the existing Django fields (in
|
||||
:file:`django/db/models/fields/__init__.py`) for inspiration. Try to find
|
||||
a field that's similar to what you want and extend it a little bit,
|
||||
instead of creating an entirely new field from scratch.
|
||||
1. Look at the existing Django fields (in
|
||||
:file:`django/db/models/fields/__init__.py`) for inspiration. Try to find
|
||||
a field that's similar to what you want and extend it a little bit,
|
||||
instead of creating an entirely new field from scratch.
|
||||
|
||||
2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're
|
||||
wrapping up as a field. There are a lot of places where the default
|
||||
behavior of the field code is to call
|
||||
:func:`~django.utils.encoding.force_unicode` on the value. (In our
|
||||
examples in this document, ``value`` would be a ``Hand`` instance, not a
|
||||
``HandField``). So if your :meth:`__unicode__` method automatically
|
||||
converts to the string form of your Python object, you can save yourself
|
||||
a lot of work.
|
||||
2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're
|
||||
wrapping up as a field. There are a lot of places where the default
|
||||
behavior of the field code is to call
|
||||
:func:`~django.utils.encoding.force_unicode` on the value. (In our
|
||||
examples in this document, ``value`` would be a ``Hand`` instance, not a
|
||||
``HandField``). So if your :meth:`__unicode__` method automatically
|
||||
converts to the string form of your Python object, you can save yourself
|
||||
a lot of work.
|
||||
|
||||
|
||||
Writing a ``FileField`` subclass
|
||||
|
@ -735,14 +735,14 @@ A few suggestions
|
|||
In addition to the above details, there are a few guidelines which can greatly
|
||||
improve the efficiency and readability of the field's code.
|
||||
|
||||
1. The source for Django's own ``ImageField`` (in
|
||||
``django/db/models/fields/files.py``) is a great example of how to
|
||||
subclass ``FileField`` to support a particular type of file, as it
|
||||
incorporates all of the techniques described above.
|
||||
1. The source for Django's own ``ImageField`` (in
|
||||
``django/db/models/fields/files.py``) is a great example of how to
|
||||
subclass ``FileField`` to support a particular type of file, as it
|
||||
incorporates all of the techniques described above.
|
||||
|
||||
2. Cache file attributes wherever possible. Since files may be stored in
|
||||
remote storage systems, retrieving them may cost extra time, or even
|
||||
money, that isn't always necessary. Once a file is retrieved to obtain
|
||||
some data about its content, cache as much of that data as possible to
|
||||
reduce the number of times the file must be retrieved on subsequent
|
||||
calls for that information.
|
||||
2. Cache file attributes wherever possible. Since files may be stored in
|
||||
remote storage systems, retrieving them may cost extra time, or even
|
||||
money, that isn't always necessary. Once a file is retrieved to obtain
|
||||
some data about its content, cache as much of that data as possible to
|
||||
reduce the number of times the file must be retrieved on subsequent
|
||||
calls for that information.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue