← Back to branch summary

~ubuntu-branches/debian/sid/python-django/sid

« back to all changes in this revision

Viewing changes to docs/topics/db/models.txt

  • Committer: Package Import Robot
  • Author(s): Raphaël Hertzog
  • Date: 2012-10-22 10:53:30 UTC
  • mfrom: (1.2.14)
  • Revision ID: package-import@ubuntu.com-20121022105330-el5jslfv9tkcrwkv
Tags: 1.4.2-1
http://bugs.debian.org/691145
* New upstream security and maintenance release. Closes: #691145
  Fixes: CVE-2012-4520
* Drop 01_use_stdlib_htmlparser_when_possible.diff which has been
  merged upstream.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/db/models.txt
84
84
 
85
85
The most important part of a model -- and the only required part of a model --
86
86
is the list of database fields it defines. Fields are specified by class
87
 
attributes.
 
87
attributes. Be careful not to choose field names that conflict with the
 
88
:doc:`models API </ref/models/instances>` like ``clean``, ``save``, or
 
89
``delete``.
88
90
 
89
91
Example::
90
92
 
108
110
 
109
111
* The database column type (e.g. ``INTEGER``, ``VARCHAR``).
110
112
 
111
 
* The :doc:`widget </ref/forms/widgets>` to use in Django's admin interface,
112
 
  if you care to use it (e.g. ``<input type="text">``, ``<select>``).
 
113
* The default :doc:`widget </ref/forms/widgets>` to use when rendering a form
 
114
  field (e.g. ``<input type="text">``, ``<select>``).
113
115
 
114
116
* The minimal validation requirements, used in Django's admin and in
115
117
  automatically-generated forms.
143
145
    Note that this is different than :attr:`~Field.null`.
144
146
    :attr:`~Field.null` is purely database-related, whereas
145
147
    :attr:`~Field.blank` is validation-related. If a field has
146
 
    :attr:`blank=True <Field.blank>`, validation on Django's admin site will
 
148
    :attr:`blank=True <Field.blank>`, form validation will
147
149
    allow entry of an empty value. If a field has :attr:`blank=False
148
150
    <Field.blank>`, the field will be required.
149
151
 
150
152
:attr:`~Field.choices`
151
153
    An iterable (e.g., a list or tuple) of 2-tuples to use as choices for
152
 
    this field. If this is given, Django's admin will use a select box
 
154
    this field. If this is given, the default form widget will be a select box
153
155
    instead of the standard text field and will limit choices to the choices
154
156
    given.
155
157
 
164
166
        )
165
167
 
166
168
    The first element in each tuple is the value that will be stored in the
167
 
    database, the second element will be displayed by the admin interface,
 
169
    database, the second element will be displayed by the default form widget
168
170
    or in a ModelChoiceField. Given an instance of a model object, the
169
171
    display value for a choices field can be accessed using the
170
172
    ``get_FOO_display`` method. For example::
195
197
    created.
196
198
 
197
199
:attr:`~Field.help_text`
198
 
    Extra "help" text to be displayed under the field on the object's admin
199
 
    form. It's useful for documentation even if your object doesn't have an
200
 
    admin form.
 
200
    Extra "help" text to be displayed with the form widget. It's useful for
 
201
    documentation even if your field isn't used on a form.
201
202
 
202
203
:attr:`~Field.primary_key`
203
204
    If ``True``, this field is the primary key for the model.
359
360
:class:`~django.db.models.ManyToManyField`, but you should only put it in one
360
361
of the models -- not both.
361
362
 
362
 
Generally, :class:`~django.db.models.ManyToManyField` instances should go in the
363
 
object that's going to be edited in the admin interface, if you're using
364
 
Django's admin. In the above example, ``toppings`` is in ``Pizza`` (rather than
365
 
``Topping`` having a ``pizzas`` :class:`~django.db.models.ManyToManyField` )
366
 
because it's more natural to think about a pizza having toppings than a
367
 
topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin
368
 
form would let users select the toppings.
 
363
Generally, :class:`~django.db.models.ManyToManyField` instances should go in
 
364
the object that's going to be edited on a form. In the above example,
 
365
``toppings`` is in ``Pizza`` (rather than ``Topping`` having a ``pizzas``
 
366
:class:`~django.db.models.ManyToManyField` ) because it's more natural to think
 
367
about a pizza having toppings than a topping being on multiple pizzas. The way
 
368
it's set up above, the ``Pizza`` form would let users select the toppings.
369
369
 
370
370
.. seealso::
371
371
 
761
761
**kwargs`` in your method definitions, you are guaranteed that your
762
762
code will automatically support those arguments when they are added.
763
763
 
764
 
.. admonition:: Overriding Delete
 
764
.. admonition:: Overridden model methods are not called on bulk operations
765
765
 
766
766
    Note that the :meth:`~Model.delete()` method for an object is not
767
767
    necessarily called when :ref:`deleting objects in bulk using a
769
769
    gets executed, you can use :data:`~django.db.models.signals.pre_delete`
770
770
    and/or :data:`~django.db.models.signals.post_delete` signals.
771
771
 
 
772
    Unfortunately, there isn't a workaround when
 
773
    :meth:`creating<django.db.models.query.QuerySet.bulk_create>` or
 
774
    :meth:`updating<django.db.models.query.QuerySet.update>` objects in bulk,
 
775
    since none of :meth:`~Model.save()`,
 
776
    :data:`~django.db.models.signals.pre_save`, and
 
777
    :data:`~django.db.models.signals.post_save` are called.
 
778
 
772
779
Executing custom SQL
773
780
--------------------
774
781