2108 lines
80 KiB
Plaintext
2108 lines
80 KiB
Plaintext
===============
|
|
Model reference
|
|
===============
|
|
|
|
A model is the single, definitive source of data about your data. It contains
|
|
the essential fields and behaviors of the data you're storing. Generally, each
|
|
model maps to a single database table.
|
|
|
|
The basics:
|
|
|
|
* Each model is a Python class that subclasses ``django.db.models.Model``.
|
|
* Each attribute of the model represents a database field.
|
|
* Model metadata (non-field information) goes in an inner class named
|
|
``Meta``.
|
|
* With all of this, Django gives you an automatically-generated
|
|
database-access API, which is explained in the `Database API reference`_.
|
|
|
|
A companion to this document is the `official repository of model examples`_.
|
|
(In the Django source distribution, these examples are in the
|
|
``tests/modeltests`` directory.)
|
|
|
|
.. _Database API reference: ../db-api/
|
|
.. _official repository of model examples: ../models/
|
|
|
|
Quick example
|
|
=============
|
|
|
|
This example model defines a ``Person``, which has a ``first_name`` and
|
|
``last_name``::
|
|
|
|
from django.db import models
|
|
|
|
class Person(models.Model):
|
|
first_name = models.CharField(max_length=30)
|
|
last_name = models.CharField(max_length=30)
|
|
|
|
``first_name`` and ``last_name`` are *fields* of the model. Each field is
|
|
specified as a class attribute, and each attribute maps to a database column.
|
|
|
|
The above ``Person`` model would create a database table like this::
|
|
|
|
CREATE TABLE myapp_person (
|
|
"id" serial NOT NULL PRIMARY KEY,
|
|
"first_name" varchar(30) NOT NULL,
|
|
"last_name" varchar(30) NOT NULL
|
|
);
|
|
|
|
Some technical notes:
|
|
|
|
* The name of the table, ``myapp_person``, is automatically derived from
|
|
some model metadata but can be overridden. See `Table names`_ below.
|
|
* An ``id`` field is added automatically, but this behavior can be
|
|
overridden. See `Automatic primary key fields`_ below.
|
|
* The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
|
|
syntax, but it's worth noting Django uses SQL tailored to the database
|
|
backend specified in your `settings file`_.
|
|
|
|
.. _settings file: ../settings/
|
|
|
|
Fields
|
|
======
|
|
|
|
The most important part of a model -- and the only required part of a model --
|
|
is the list of database fields it defines. Fields are specified by class
|
|
attributes.
|
|
|
|
Example::
|
|
|
|
class Musician(models.Model):
|
|
first_name = models.CharField(max_length=50)
|
|
last_name = models.CharField(max_length=50)
|
|
instrument = models.CharField(max_length=100)
|
|
|
|
class Album(models.Model):
|
|
artist = models.ForeignKey(Musician)
|
|
name = models.CharField(max_length=100)
|
|
release_date = models.DateField()
|
|
num_stars = models.IntegerField()
|
|
|
|
Field name restrictions
|
|
-----------------------
|
|
|
|
Django places only two restrictions on model field names:
|
|
|
|
1. A field name cannot be a Python reserved word, because that would result
|
|
in a Python syntax error. For example::
|
|
|
|
class Example(models.Model):
|
|
pass = models.IntegerField() # 'pass' is a reserved word!
|
|
|
|
2. A field name cannot contain more than one underscore in a row, due to
|
|
the way Django's query lookup syntax works. For example::
|
|
|
|
class Example(models.Model):
|
|
foo__bar = models.IntegerField() # 'foo__bar' has two underscores!
|
|
|
|
These limitations can be worked around, though, because your field name doesn't
|
|
necessarily have to match your database column name. See `db_column`_ below.
|
|
|
|
SQL reserved words, such as ``join``, ``where`` or ``select``, *are* allowed as
|
|
model field names, because Django escapes all database table names and column
|
|
names in every underlying SQL query. It uses the quoting syntax of your
|
|
particular database engine.
|
|
|
|
Field types
|
|
-----------
|
|
|
|
Each field in your model should be an instance of the appropriate ``Field``
|
|
class. Django uses the field class types to determine a few things:
|
|
|
|
* The database column type (e.g. ``INTEGER``, ``VARCHAR``).
|
|
* The widget to use in Django's admin interface, if you care to use it
|
|
(e.g. ``<input type="text">``, ``<select>``).
|
|
* The minimal validation requirements, used in Django's admin and in
|
|
automatically-generated forms.
|
|
|
|
Here are all available field types:
|
|
|
|
``AutoField``
|
|
~~~~~~~~~~~~~
|
|
|
|
An ``IntegerField`` that automatically increments according to available IDs.
|
|
You usually won't need to use this directly; a primary key field will
|
|
automatically be added to your model if you don't specify otherwise. See
|
|
`Automatic primary key fields`_.
|
|
|
|
``BooleanField``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
A true/false field.
|
|
|
|
The admin represents this as a checkbox.
|
|
|
|
``CharField``
|
|
~~~~~~~~~~~~~
|
|
|
|
A string field, for small- to large-sized strings.
|
|
|
|
For large amounts of text, use ``TextField``.
|
|
|
|
The admin represents this as an ``<input type="text">`` (a single-line input).
|
|
|
|
``CharField`` has an extra required argument, ``max_length``, the maximum length
|
|
(in characters) of the field. The max_length is enforced at the database level
|
|
and in Django's validation.
|
|
|
|
``CommaSeparatedIntegerField``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A field of integers separated by commas. As in ``CharField``, the ``max_length``
|
|
argument is required.
|
|
|
|
``DateField``
|
|
~~~~~~~~~~~~~
|
|
|
|
A date field. Has a few extra optional arguments:
|
|
|
|
====================== ===================================================
|
|
Argument Description
|
|
====================== ===================================================
|
|
``auto_now`` Automatically set the field to now every time the
|
|
object is saved. Useful for "last-modified"
|
|
timestamps. Note that the current date is *always*
|
|
used; it's not just a default value that you can
|
|
override.
|
|
|
|
``auto_now_add`` Automatically set the field to now when the object
|
|
is first created. Useful for creation of
|
|
timestamps. Note that the current date is *always*
|
|
used; it's not just a default value that you can
|
|
override.
|
|
====================== ===================================================
|
|
|
|
The admin represents this as an ``<input type="text">`` with a JavaScript
|
|
calendar, and a shortcut for "Today." The JavaScript calendar will always start
|
|
the week on a Sunday.
|
|
|
|
``DateTimeField``
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
A date and time field. Takes the same extra options as ``DateField``.
|
|
|
|
The admin represents this as two ``<input type="text">`` fields, with
|
|
JavaScript shortcuts.
|
|
|
|
``DecimalField``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
A fixed-precision decimal number, represented in Python by a ``Decimal`` instance.
|
|
Has two **required** arguments:
|
|
|
|
====================== ===================================================
|
|
Argument Description
|
|
====================== ===================================================
|
|
``max_digits`` The maximum number of digits allowed in the number.
|
|
|
|
``decimal_places`` The number of decimal places to store with the
|
|
number.
|
|
====================== ===================================================
|
|
|
|
For example, to store numbers up to 999 with a resolution of 2 decimal places,
|
|
you'd use::
|
|
|
|
models.DecimalField(..., max_digits=5, decimal_places=2)
|
|
|
|
And to store numbers up to approximately one billion with a resolution of 10
|
|
decimal places::
|
|
|
|
models.DecimalField(..., max_digits=19, decimal_places=10)
|
|
|
|
The admin represents this as an ``<input type="text">`` (a single-line input).
|
|
|
|
``EmailField``
|
|
~~~~~~~~~~~~~~
|
|
|
|
A ``CharField`` that checks that the value is a valid e-mail address.
|
|
|
|
In Django 0.96, this doesn't accept ``max_length``; its ``max_length`` is
|
|
automatically set to 75. In the Django development version, ``max_length`` is
|
|
set to 75 by default, but you can specify it to override default behavior.
|
|
|
|
``FileField``
|
|
~~~~~~~~~~~~~
|
|
|
|
A file-upload field. Has one **required** argument:
|
|
|
|
====================== ===================================================
|
|
Argument Description
|
|
====================== ===================================================
|
|
``upload_to`` A local filesystem path that will be appended to
|
|
your ``MEDIA_ROOT`` setting to determine the
|
|
output of the ``get_<fieldname>_url()`` helper
|
|
function.
|
|
====================== ===================================================
|
|
|
|
This path may contain `strftime formatting`_, which will be replaced by the
|
|
date/time of the file upload (so that uploaded files don't fill up the given
|
|
directory).
|
|
|
|
The admin represents this field as an ``<input type="file">`` (a file-upload
|
|
widget).
|
|
|
|
Using a ``FileField`` or an ``ImageField`` (see below) in a model takes a few
|
|
steps:
|
|
|
|
1. In your settings file, you'll need to define ``MEDIA_ROOT`` as the
|
|
full path to a directory where you'd like Django to store uploaded
|
|
files. (For performance, these files are not stored in the database.)
|
|
Define ``MEDIA_URL`` as the base public URL of that directory. Make
|
|
sure that this directory is writable by the Web server's user
|
|
account.
|
|
|
|
2. Add the ``FileField`` or ``ImageField`` to your model, making sure
|
|
to define the ``upload_to`` option to tell Django to which
|
|
subdirectory of ``MEDIA_ROOT`` it should upload files.
|
|
|
|
3. All that will be stored in your database is a path to the file
|
|
(relative to ``MEDIA_ROOT``). You'll most likely want to use the
|
|
convenience ``get_<fieldname>_url`` function provided by Django. For
|
|
example, if your ``ImageField`` is called ``mug_shot``, you can get
|
|
the absolute URL to your image in a template with ``{{
|
|
object.get_mug_shot_url }}``.
|
|
|
|
For example, say your ``MEDIA_ROOT`` is set to ``'/home/media'``, and
|
|
``upload_to`` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of
|
|
``upload_to`` is strftime formatting; ``'%Y'`` is the four-digit year,
|
|
``'%m'`` is the two-digit month and ``'%d'`` is the two-digit day. If you
|
|
upload a file on Jan. 15, 2007, it will be saved in the directory
|
|
``/home/media/photos/2007/01/15``.
|
|
|
|
If you want to retrieve the upload file's on-disk filename, or a URL that
|
|
refers to that file, or the file's size, you can use the
|
|
``get_FOO_filename()``, ``get_FOO_url()`` and ``get_FOO_size()`` methods.
|
|
They are all documented here__.
|
|
|
|
__ ../db-api/#get-foo-filename
|
|
|
|
Note that whenever you deal with uploaded files, you should pay close attention
|
|
to where you're uploading them and what type of files they are, to avoid
|
|
security holes. *Validate all uploaded files* so that you're sure the files are
|
|
what you think they are. For example, if you blindly let somebody upload files,
|
|
without validation, to a directory that's within your Web server's document
|
|
root, then somebody could upload a CGI or PHP script and execute that script by
|
|
visiting its URL on your site. Don't allow that.
|
|
|
|
.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
|
|
|
|
**New in development version:** By default, ``FileField`` instances are
|
|
created as ``varchar(100)`` columns in your database. As with other fields, you
|
|
can change the maximum length using the ``max_length`` argument.
|
|
|
|
``FilePathField``
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
A field whose choices are limited to the filenames in a certain directory
|
|
on the filesystem. Has three special arguments, of which the first is
|
|
**required**:
|
|
|
|
====================== ===================================================
|
|
Argument Description
|
|
====================== ===================================================
|
|
``path`` Required. The absolute filesystem path to a
|
|
directory from which this ``FilePathField`` should
|
|
get its choices. Example: ``"/home/images"``.
|
|
|
|
``match`` Optional. A regular expression, as a string, that
|
|
``FilePathField`` will use to filter filenames.
|
|
Note that the regex will be applied to the
|
|
base filename, not the full path. Example:
|
|
``"foo.*\.txt$"``, which will match a file called
|
|
``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``.
|
|
|
|
``recursive`` Optional. Either ``True`` or ``False``. Default is
|
|
``False``. Specifies whether all subdirectories of
|
|
``path`` should be included.
|
|
====================== ===================================================
|
|
|
|
Of course, these arguments can be used together.
|
|
|
|
The one potential gotcha is that ``match`` applies to the base filename,
|
|
not the full path. So, this example::
|
|
|
|
FilePathField(path="/home/images", match="foo.*", recursive=True)
|
|
|
|
...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif``
|
|
because the ``match`` applies to the base filename (``foo.gif`` and
|
|
``bar.gif``).
|
|
|
|
**New in development version:** By default, ``FilePathField`` instances are
|
|
created as ``varchar(100)`` columns in your database. As with other fields, you
|
|
can change the maximum length using the ``max_length`` argument.
|
|
|
|
``FloatField``
|
|
~~~~~~~~~~~~~~
|
|
|
|
**Changed in Django development version**
|
|
|
|
A floating-point number represented in Python by a ``float`` instance.
|
|
|
|
The admin represents this as an ``<input type="text">`` (a single-line input).
|
|
|
|
**NOTE:** The semantics of ``FloatField`` have changed in the Django
|
|
development version. See the `Django 0.96 documentation`_ for the old behavior.
|
|
|
|
.. _Django 0.96 documentation: http://www.djangoproject.com/documentation/0.96/model-api/#floatfield
|
|
|
|
``ImageField``
|
|
~~~~~~~~~~~~~~
|
|
|
|
Like `FileField`_, but validates that the uploaded object is a valid
|
|
image. Has two extra optional arguments, ``height_field`` and
|
|
``width_field``, which, if set, will be auto-populated with the height and
|
|
width of the image each time a model instance is saved.
|
|
|
|
In addition to the special ``get_FOO_*`` methods that are available for
|
|
``FileField``, an ``ImageField`` also has ``get_FOO_height()`` and
|
|
``get_FOO_width()`` methods. These are documented elsewhere_.
|
|
|
|
Requires the `Python Imaging Library`_.
|
|
|
|
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
|
|
.. _elsewhere: ../db-api/#get-foo-height-and-get-foo-width
|
|
|
|
**New in development version:** By default, ``ImageField`` instances are
|
|
created as ``varchar(100)`` columns in your database. As with other fields, you
|
|
can change the maximum length using the ``max_length`` argument.
|
|
|
|
|
|
``IntegerField``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
An integer.
|
|
|
|
The admin represents this as an ``<input type="text">`` (a single-line input).
|
|
|
|
``IPAddressField``
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
An IP address, in string format (e.g. "192.0.2.30").
|
|
|
|
The admin represents this as an ``<input type="text">`` (a single-line input).
|
|
|
|
``NullBooleanField``
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like a ``BooleanField``, but allows ``NULL`` as one of the options. Use this
|
|
instead of a ``BooleanField`` with ``null=True``.
|
|
|
|
The admin represents this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.
|
|
|
|
``PhoneNumberField``
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A ``CharField`` that checks that the value is a valid U.S.A.-style phone
|
|
number (in the format ``XXX-XXX-XXXX``).
|
|
|
|
``PositiveIntegerField``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like an ``IntegerField``, but must be positive.
|
|
|
|
``PositiveSmallIntegerField``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like a ``PositiveIntegerField``, but only allows values under a certain
|
|
(database-dependent) point.
|
|
|
|
``SlugField``
|
|
~~~~~~~~~~~~~
|
|
|
|
"Slug" is a newspaper term. A slug is a short label for something,
|
|
containing only letters, numbers, underscores or hyphens. They're generally
|
|
used in URLs.
|
|
|
|
Like a CharField, you can specify ``max_length``. If ``max_length`` is
|
|
not specified, Django will use a default length of 50.
|
|
|
|
Implies ``db_index=True``.
|
|
|
|
``SmallIntegerField``
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like an ``IntegerField``, but only allows values under a certain
|
|
(database-dependent) point.
|
|
|
|
``TextField``
|
|
~~~~~~~~~~~~~
|
|
|
|
A large text field.
|
|
|
|
The admin represents this as a ``<textarea>`` (a multi-line input).
|
|
|
|
``TimeField``
|
|
~~~~~~~~~~~~~
|
|
|
|
A time. Accepts the same auto-population options as ``DateField`` and
|
|
``DateTimeField``.
|
|
|
|
The admin represents this as an ``<input type="text">`` with some
|
|
JavaScript shortcuts.
|
|
|
|
``URLField``
|
|
~~~~~~~~~~~~
|
|
|
|
A field for a URL. If the ``verify_exists`` option is ``True`` (default),
|
|
the URL given will be checked for existence (i.e., the URL actually loads
|
|
and doesn't give a 404 response).
|
|
|
|
The admin represents this as an ``<input type="text">`` (a single-line input).
|
|
|
|
``URLField`` takes an optional argument, ``max_length``, the maximum length (in
|
|
characters) of the field. The maximum length is enforced at the database level and
|
|
in Django's validation. If you don't specify ``max_length``, a default of 200
|
|
is used.
|
|
|
|
``USStateField``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
A two-letter U.S. state abbreviation.
|
|
|
|
The admin represents this as an ``<input type="text">`` (a single-line input).
|
|
|
|
``XMLField``
|
|
~~~~~~~~~~~~
|
|
|
|
A ``TextField`` that checks that the value is valid XML that matches a
|
|
given schema. Takes one required argument, ``schema_path``, which is the
|
|
filesystem path to a RelaxNG_ schema against which to validate the field.
|
|
|
|
.. _RelaxNG: http://www.relaxng.org/
|
|
|
|
Field options
|
|
-------------
|
|
|
|
The following arguments are available to all field types. All are optional.
|
|
|
|
``null``
|
|
~~~~~~~~
|
|
|
|
If ``True``, Django will store empty values as ``NULL`` in the database.
|
|
Default is ``False``.
|
|
|
|
Note that empty string values will always get stored as empty strings, not
|
|
as ``NULL``. Only use ``null=True`` for non-string fields such as integers,
|
|
booleans and dates. For both types of fields, you will also need to set
|
|
``blank=True`` if you wish to permit empty values in forms, as the ``null``
|
|
parameter only affects database storage (see blank_, below).
|
|
|
|
Avoid using ``null`` on string-based fields such as ``CharField`` and
|
|
``TextField`` unless you have an excellent reason. If a string-based field
|
|
has ``null=True``, that means it has two possible values for "no data":
|
|
``NULL``, and the empty string. In most cases, it's redundant to have two
|
|
possible values for "no data;" Django convention is to use the empty
|
|
string, not ``NULL``.
|
|
|
|
.. note::
|
|
When using the Oracle database backend, the ``null=True`` option will
|
|
be coerced for string-based fields that can blank, and the value
|
|
``NULL`` will be stored to denote the empty string.
|
|
|
|
``blank``
|
|
~~~~~~~~~
|
|
|
|
If ``True``, the field is allowed to be blank. Default is ``False``.
|
|
|
|
Note that this is different than ``null``. ``null`` is purely
|
|
database-related, whereas ``blank`` is validation-related. If a field has
|
|
``blank=True``, validation on Django's admin site will allow entry of an
|
|
empty value. If a field has ``blank=False``, the field will be required.
|
|
|
|
``choices``
|
|
~~~~~~~~~~~
|
|
|
|
An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this
|
|
field.
|
|
|
|
If this is given, Django's admin will use a select box instead of the
|
|
standard text field and will limit choices to the choices given.
|
|
|
|
A choices list looks like this::
|
|
|
|
YEAR_IN_SCHOOL_CHOICES = (
|
|
('FR', 'Freshman'),
|
|
('SO', 'Sophomore'),
|
|
('JR', 'Junior'),
|
|
('SR', 'Senior'),
|
|
('GR', 'Graduate'),
|
|
)
|
|
|
|
The first element in each tuple is the actual value to be stored. The
|
|
second element is the human-readable name for the option.
|
|
|
|
The choices list can be defined either as part of your model class::
|
|
|
|
class Foo(models.Model):
|
|
GENDER_CHOICES = (
|
|
('M', 'Male'),
|
|
('F', 'Female'),
|
|
)
|
|
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
|
|
|
|
or outside your model class altogether::
|
|
|
|
GENDER_CHOICES = (
|
|
('M', 'Male'),
|
|
('F', 'Female'),
|
|
)
|
|
class Foo(models.Model):
|
|
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
|
|
|
|
You can also collect your available choices into named groups that can
|
|
be used for organizational purposes::
|
|
|
|
MEDIA_CHOICES = (
|
|
('Audio', (
|
|
('vinyl', 'Vinyl'),
|
|
('cd', 'CD'),
|
|
)
|
|
),
|
|
('Video', (
|
|
('vhs', 'VHS Tape'),
|
|
('dvd', 'DVD'),
|
|
)
|
|
),
|
|
('unknown', 'Unknown'),
|
|
)
|
|
|
|
The first element in each tuple is the name to apply to the group. The
|
|
second element is an iterable of 2-tuples, with each 2-tuple containing
|
|
a value and a human-readable name for an option. Grouped options may be
|
|
combined with ungrouped options within a single list (such as the
|
|
`unknown` option in this example).
|
|
|
|
For each model field that has ``choices`` set, Django will add a method to
|
|
retrieve the human-readable name for the field's current value. See
|
|
`get_FOO_display`_ in the database API documentation.
|
|
|
|
.. _get_FOO_display: ../db-api/#get-foo-display
|
|
|
|
Finally, note that choices can be any iterable object -- not necessarily a
|
|
list or tuple. This lets you construct choices dynamically. But if you find
|
|
yourself hacking ``choices`` to be dynamic, you're probably better off using
|
|
a proper database table with a ``ForeignKey``. ``choices`` is meant for static
|
|
data that doesn't change much, if ever.
|
|
|
|
``core``
|
|
~~~~~~~~
|
|
|
|
For objects that are edited inline to a related object.
|
|
|
|
In the Django admin, if all "core" fields in an inline-edited object are
|
|
cleared, the object will be deleted.
|
|
|
|
It is an error to have an inline-editable relation without at least one
|
|
``core=True`` field.
|
|
|
|
Please note that each field marked "core" is treated as a required field by the
|
|
Django admin site. Essentially, this means you should put ``core=True`` on all
|
|
required fields in your related object that is being edited inline.
|
|
|
|
``db_column``
|
|
~~~~~~~~~~~~~
|
|
|
|
The name of the database column to use for this field. If this isn't given,
|
|
Django will use the field's name.
|
|
|
|
If your database column name is an SQL reserved word, or contains
|
|
characters that aren't allowed in Python variable names -- notably, the
|
|
hyphen -- that's OK. Django quotes column and table names behind the
|
|
scenes.
|
|
|
|
``db_index``
|
|
~~~~~~~~~~~~
|
|
|
|
If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX``
|
|
statement for this field.
|
|
|
|
``db_tablespace``
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
The name of the database tablespace to use for this field's index, if
|
|
this field is indexed. The default is the project's
|
|
``DEFAULT_INDEX_TABLESPACE`` setting, if set, or the ``db_tablespace``
|
|
of the model, if any. If the backend doesn't support tablespaces, this
|
|
option is ignored.
|
|
|
|
``default``
|
|
~~~~~~~~~~~
|
|
|
|
The default value for the field. This can be a value or a callable object. If
|
|
callable it will be called every time a new object is created.
|
|
|
|
``editable``
|
|
~~~~~~~~~~~~
|
|
|
|
If ``False``, the field will not be editable in the admin or via forms
|
|
automatically generated from the model class. Default is ``True``.
|
|
|
|
``help_text``
|
|
~~~~~~~~~~~~~
|
|
|
|
Extra "help" text to be displayed under the field on the object's admin
|
|
form. It's useful for documentation even if your object doesn't have an
|
|
admin form.
|
|
|
|
Note that this value is *not* HTML-escaped when it's displayed in the admin
|
|
interface. This lets you include HTML in ``help_text`` if you so desire. For
|
|
example::
|
|
|
|
help_text="Please use the following format: <em>YYYY-MM-DD</em>."
|
|
|
|
Alternatively you can use plain text and
|
|
``django.utils.html.escape()`` to escape any HTML special characters.
|
|
|
|
``primary_key``
|
|
~~~~~~~~~~~~~~~
|
|
|
|
If ``True``, this field is the primary key for the model.
|
|
|
|
If you don't specify ``primary_key=True`` for any fields in your model,
|
|
Django will automatically add this field::
|
|
|
|
id = models.AutoField('ID', primary_key=True)
|
|
|
|
Thus, you don't need to set ``primary_key=True`` on any of your fields
|
|
unless you want to override the default primary-key behavior.
|
|
|
|
``primary_key=True`` implies ``null=False`` and ``unique=True``. Only
|
|
one primary key is allowed on an object.
|
|
|
|
``unique``
|
|
~~~~~~~~~~
|
|
|
|
If ``True``, this field must be unique throughout the table.
|
|
|
|
This is enforced at the database level and at the Django admin-form level. If
|
|
you try to save a model with a duplicate value in a ``unique`` field, a
|
|
``django.db.IntegrityError`` will be raised by the model's ``save()`` method.
|
|
|
|
``unique_for_date``
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Set this to the name of a ``DateField`` or ``DateTimeField`` to require
|
|
that this field be unique for the value of the date field.
|
|
|
|
For example, if you have a field ``title`` that has
|
|
``unique_for_date="pub_date"``, then Django wouldn't allow the entry of
|
|
two records with the same ``title`` and ``pub_date``.
|
|
|
|
This is enforced at the Django admin-form level but not at the database level.
|
|
|
|
``unique_for_month``
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like ``unique_for_date``, but requires the field to be unique with respect
|
|
to the month.
|
|
|
|
``unique_for_year``
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like ``unique_for_date`` and ``unique_for_month``.
|
|
|
|
``validator_list``
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
A list of extra validators to apply to the field. Each should be a callable
|
|
that takes the parameters ``field_data, all_data`` and raises
|
|
``django.core.validators.ValidationError`` for errors. (See the
|
|
`validator docs`_.)
|
|
|
|
Django comes with quite a few validators. They're in ``django.core.validators``.
|
|
|
|
.. _validator docs: ../oldforms/#validators
|
|
|
|
Verbose field names
|
|
-------------------
|
|
|
|
Each field type, except for ``ForeignKey``, ``ManyToManyField`` and
|
|
``OneToOneField``, takes an optional first positional argument -- a
|
|
verbose name. If the verbose name isn't given, Django will automatically create
|
|
it using the field's attribute name, converting underscores to spaces.
|
|
|
|
In this example, the verbose name is ``"Person's first name"``::
|
|
|
|
first_name = models.CharField("Person's first name", max_length=30)
|
|
|
|
In this example, the verbose name is ``"first name"``::
|
|
|
|
first_name = models.CharField(max_length=30)
|
|
|
|
``ForeignKey``, ``ManyToManyField`` and ``OneToOneField`` require the first
|
|
argument to be a model class, so use the ``verbose_name`` keyword argument::
|
|
|
|
poll = models.ForeignKey(Poll, verbose_name="the related poll")
|
|
sites = models.ManyToManyField(Site, verbose_name="list of sites")
|
|
place = models.OneToOneField(Place, verbose_name="related place")
|
|
|
|
Convention is not to capitalize the first letter of the ``verbose_name``.
|
|
Django will automatically capitalize the first letter where it needs to.
|
|
|
|
Relationships
|
|
-------------
|
|
|
|
Clearly, the power of relational databases lies in relating tables to each
|
|
other. Django offers ways to define the three most common types of database
|
|
relationships: Many-to-one, many-to-many and one-to-one.
|
|
|
|
Many-to-one relationships
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To define a many-to-one relationship, use ``ForeignKey``. You use it just like
|
|
any other ``Field`` type: by including it as a class attribute of your model.
|
|
|
|
``ForeignKey`` requires a positional argument: the class to which the model is
|
|
related.
|
|
|
|
For example, if a ``Car`` model has a ``Manufacturer`` -- that is, a
|
|
``Manufacturer`` makes multiple cars but each ``Car`` only has one
|
|
``Manufacturer`` -- use the following definitions::
|
|
|
|
class Manufacturer(models.Model):
|
|
# ...
|
|
|
|
class Car(models.Model):
|
|
manufacturer = models.ForeignKey(Manufacturer)
|
|
# ...
|
|
|
|
To create a recursive relationship -- an object that has a many-to-one
|
|
relationship with itself -- use ``models.ForeignKey('self')``.
|
|
|
|
If you need to create a relationship on a model that has not yet been defined,
|
|
you can use the name of the model, rather than the model object itself::
|
|
|
|
class Car(models.Model):
|
|
manufacturer = models.ForeignKey('Manufacturer')
|
|
# ...
|
|
|
|
class Manufacturer(models.Model):
|
|
# ...
|
|
|
|
Note, however, that this only refers to models in the same models.py file -- you
|
|
cannot use a string to reference a model defined in another application or
|
|
imported from elsewhere.
|
|
|
|
**New in Django development version:** To refer to models defined in another
|
|
application, you must instead explicitly specify the application label. For
|
|
example, if the ``Manufacturer`` model above is defined in another application
|
|
called ``production``, you'd need to use::
|
|
|
|
class Car(models.Model):
|
|
manufacturer = models.ForeignKey('production.Manufacturer')
|
|
|
|
Behind the scenes, Django appends ``"_id"`` to the field name to create its
|
|
database column name. In the above example, the database table for the ``Car``
|
|
model will have a ``manufacturer_id`` column. (You can change this explicitly
|
|
by specifying ``db_column``; see ``db_column`` below.) However, your code
|
|
should never have to deal with the database column name, unless you write
|
|
custom SQL. You'll always deal with the field names of your model object.
|
|
|
|
It's suggested, but not required, that the name of a ``ForeignKey`` field
|
|
(``manufacturer`` in the example above) be the name of the model, lowercase.
|
|
You can, of course, call the field whatever you want. For example::
|
|
|
|
class Car(models.Model):
|
|
company_that_makes_it = models.ForeignKey(Manufacturer)
|
|
# ...
|
|
|
|
See the `Many-to-one relationship model example`_ for a full example.
|
|
|
|
.. _Many-to-one relationship model example: ../models/many_to_one/
|
|
|
|
``ForeignKey`` fields take a number of extra arguments for defining how the
|
|
relationship should work. All are optional:
|
|
|
|
======================= ============================================================
|
|
Argument Description
|
|
======================= ============================================================
|
|
``limit_choices_to`` A dictionary of lookup arguments and values (see
|
|
the `Database API reference`_) that limit the
|
|
available admin choices for this object. Use this
|
|
with functions from the Python ``datetime`` module
|
|
to limit choices of objects by date. For example::
|
|
|
|
limit_choices_to = {'pub_date__lte': datetime.now}
|
|
|
|
only allows the choice of related objects with a
|
|
``pub_date`` before the current date/time to be
|
|
chosen.
|
|
|
|
Instead of a dictionary this can also be a ``Q`` object
|
|
(an object with a ``get_sql()`` method) for more complex
|
|
queries.
|
|
|
|
Not compatible with ``edit_inline``.
|
|
|
|
``related_name`` The name to use for the relation from the related
|
|
object back to this one. See the
|
|
`related objects documentation`_ for a full
|
|
explanation and example.
|
|
|
|
If using this in an `abstract base class`_, be
|
|
sure to read the `extra notes`_ in that section
|
|
about ``related_name``.
|
|
|
|
``to_field`` The field on the related object that the relation
|
|
is to. By default, Django uses the primary key of
|
|
the related object.
|
|
======================= ============================================================
|
|
|
|
.. _`Database API reference`: ../db-api/
|
|
.. _related objects documentation: ../db-api/#related-objects
|
|
.. _abstract base class: `Abstract base classes`_
|
|
.. _extra notes: `Be careful with related_name`_
|
|
|
|
Many-to-many relationships
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To define a many-to-many relationship, use ``ManyToManyField``. You use it just
|
|
like any other ``Field`` type: by including it as a class attribute of your
|
|
model.
|
|
|
|
``ManyToManyField`` requires a positional argument: the class to which the
|
|
model is related.
|
|
|
|
For example, if a ``Pizza`` has multiple ``Topping`` objects -- that is, a
|
|
``Topping`` can be on multiple pizzas and each ``Pizza`` has multiple toppings --
|
|
here's how you'd represent that::
|
|
|
|
class Topping(models.Model):
|
|
# ...
|
|
|
|
class Pizza(models.Model):
|
|
# ...
|
|
toppings = models.ManyToManyField(Topping)
|
|
|
|
As with ``ForeignKey``, a relationship to self can be defined by using the
|
|
string ``'self'`` instead of the model name, and you can refer to as-yet
|
|
undefined models by using a string containing the model name. However, you
|
|
can only use strings to refer to models in the same models.py file -- you
|
|
cannot use a string to reference a model in a different application, or to
|
|
reference a model that has been imported from elsewhere.
|
|
|
|
It's suggested, but not required, that the name of a ``ManyToManyField``
|
|
(``toppings`` in the example above) be a plural describing the set of related
|
|
model objects.
|
|
|
|
Behind the scenes, Django creates an intermediary join table to represent the
|
|
many-to-many relationship.
|
|
|
|
It doesn't matter which model gets the ``ManyToManyField``, but you only need
|
|
it in one of the models -- not in both.
|
|
|
|
Generally, ``ManyToManyField`` instances should go in the object that's going
|
|
to be edited in the admin interface, if you're using Django's admin. In the
|
|
above example, ``toppings`` is in ``Pizza`` (rather than ``Topping`` having a
|
|
``pizzas`` ``ManyToManyField`` ) because it's more natural to think about a
|
|
``Pizza`` having toppings than a topping being on multiple pizzas. The way it's
|
|
set up above, the ``Pizza`` admin form would let users select the toppings.
|
|
|
|
See the `Many-to-many relationship model example`_ for a full example.
|
|
|
|
.. _Many-to-many relationship model example: ../models/many_to_many/
|
|
|
|
``ManyToManyField`` objects take a number of extra arguments for defining how
|
|
the relationship should work. All are optional:
|
|
|
|
======================= ============================================================
|
|
Argument Description
|
|
======================= ============================================================
|
|
``related_name`` See the description under ``ForeignKey`` above.
|
|
|
|
``limit_choices_to`` See the description under ``ForeignKey`` above.
|
|
|
|
``symmetrical`` Only used in the definition of ManyToManyFields on self.
|
|
Consider the following model::
|
|
|
|
class Person(models.Model):
|
|
friends = models.ManyToManyField("self")
|
|
|
|
When Django processes this model, it identifies that it has
|
|
a ``ManyToManyField`` on itself, and as a result, it
|
|
doesn't add a ``person_set`` attribute to the ``Person``
|
|
class. Instead, the ``ManyToManyField`` is assumed to be
|
|
symmetrical -- that is, if I am your friend, then you are
|
|
my friend.
|
|
|
|
If you do not want symmetry in ``ManyToMany`` relationships
|
|
with ``self``, set ``symmetrical`` to ``False``. This will
|
|
force Django to add the descriptor for the reverse
|
|
relationship, allowing ``ManyToMany`` relationships to be
|
|
non-symmetrical.
|
|
|
|
``db_table`` The name of the table to create for storing the many-to-many
|
|
data. If this is not provided, Django will assume a default
|
|
name based upon the names of the two tables being joined.
|
|
|
|
======================= ============================================================
|
|
|
|
Extra fields on many-to-many relationships
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
**New in Django development version**
|
|
|
|
When you're only dealing with simple many-to-many relationships such as
|
|
mixing and matching pizzas and toppings, a standard ``ManyToManyField``
|
|
is all you need. However, sometimes you may need to associate data with the
|
|
relationship between two models.
|
|
|
|
For example, consider the case of an application tracking the musical groups
|
|
which musicians belong to. There is a many-to-many relationship between a person
|
|
and the groups of which they are a member, so you could use a ManyToManyField
|
|
to represent this relationship. However, there is a lot of detail about the
|
|
membership that you might want to collect, such as the date at which the person
|
|
joined the group.
|
|
|
|
For these situations, Django allows you to specify the model that will be used
|
|
to govern the many-to-many relationship. You can then put extra fields on the
|
|
intermediate model. The intermediate model is associated with the
|
|
``ManyToManyField`` using the ``through`` argument to point to the model
|
|
that will act as an intermediary. For our musician example, the code would look
|
|
something like this::
|
|
|
|
class Person(models.Model):
|
|
name = models.CharField(max_length=128)
|
|
|
|
def __unicode__(self):
|
|
return self.name
|
|
|
|
class Group(models.Model):
|
|
name = models.CharField(max_length=128)
|
|
members = models.ManyToManyField(Person, through='Membership')
|
|
|
|
def __unicode__(self):
|
|
return self.name
|
|
|
|
class Membership(models.Model):
|
|
person = models.ForeignKey(Person)
|
|
group = models.ForeignKey(Group)
|
|
date_joined = models.DateField()
|
|
invite_reason = models.CharField(max_length=64)
|
|
|
|
When you set up the intermediary model, you explicitly specify foreign
|
|
keys to the models that are involved in the ManyToMany relation. This
|
|
explicit declaration defines how the two models are related.
|
|
|
|
There are a few restrictions on the intermediate model:
|
|
|
|
* Your intermediate model must contain one - and *only* one - foreign key
|
|
on the target model (this would be ``Person`` in our example). If you
|
|
have more than one foreign key, a validation error will be raised.
|
|
|
|
* Your intermediate model must contain one - and *only* one - foreign key
|
|
on the source model (this would be ``Group`` in our example). If you
|
|
have more than one foreign key, a validation error will be raised.
|
|
|
|
* The only exception to this is a model which has a many-to-many
|
|
relationship to itself, through an intermediary model. In this
|
|
case, two foreign keys to the same model are permitted, but they
|
|
will be treated as the two (different) sides of the many-to-many
|
|
relation.
|
|
|
|
* When defining a many-to-many relationship from a model to
|
|
itself, using an intermediary model, you *must* use
|
|
``symmetrical=False`` (see the documentation for
|
|
``ManyToManyField`` above).
|
|
|
|
Now that you have set up your ``ManyToManyField`` to use your intermediary
|
|
model (Membership, in this case), you're ready to start creating some
|
|
many-to-many relationships. You do this by creating instances of the
|
|
intermediate model::
|
|
|
|
>>> ringo = Person.objects.create(name="Ringo Starr")
|
|
>>> paul = Person.objects.create(name="Paul McCartney")
|
|
>>> beatles = Group.objects.create(name="The Beatles")
|
|
>>> m1 = Membership(person=ringo, group=beatles,
|
|
... date_joined=date(1962, 8, 16),
|
|
... invite_reason= "Needed a new drummer.")
|
|
>>> m1.save()
|
|
>>> beatles.members.all()
|
|
[<Person: Ringo Starr>]
|
|
>>> ringo.group_set.all()
|
|
[<Group: The Beatles>]
|
|
>>> m2 = Membership.objects.create(person=paul, group=beatles,
|
|
... date_joined=date(1960, 8, 1),
|
|
... invite_reason= "Wanted to form a band.")
|
|
>>> beatles.members.all()
|
|
[<Person: Ringo Starr>, <Person: Paul McCartney>]
|
|
|
|
Unlike normal many-to-many fields, you *can't* use ``add``, ``create``,
|
|
or assignment (i.e., ``beatles.members = [...]``) to create relationships::
|
|
|
|
# THIS WILL NOT WORK
|
|
>>> beatles.members.add(john)
|
|
# NEITHER WILL THIS
|
|
>>> beatles.members.create(name="George Harrison")
|
|
# AND NEITHER WILL THIS
|
|
>>> beatles.members = [john, paul, ringo, george]
|
|
|
|
Why? You can't just create a relationship between a Person and a Group - you
|
|
need to specify all the detail for the relationship required by the
|
|
Membership table. The simple ``add``, ``create`` and assignment calls
|
|
don't provide a way to specify this extra detail. As a result, they are
|
|
disabled for many-to-many relationships that use an intermediate model.
|
|
The only way to create a many-to-many relationship with an intermediate table
|
|
is to create instances of the intermediate model.
|
|
|
|
The ``remove`` method is disabled for similar reasons. However, the
|
|
``clear()`` method can be used to remove all many-to-many relationships
|
|
for an instance::
|
|
|
|
# Beatles have broken up
|
|
>>> beatles.members.clear()
|
|
|
|
Once you have established the many-to-many relationships by creating instances
|
|
of your intermediate model, you can issue queries. Just as with normal
|
|
many-to-many relationships, you can query using the attributes of the
|
|
many-to-many-related model::
|
|
|
|
# Find all the groups with a member whose name starts with 'Paul'
|
|
>>> Groups.objects.filter(person__name__startswith='Paul')
|
|
[<Group: The Beatles>]
|
|
|
|
As you are using an intermediate table, you can also query on the attributes
|
|
of the intermediate model::
|
|
|
|
# Find all the members of the Beatles that joined after 1 Jan 1961
|
|
>>> Person.objects.filter(
|
|
... group__name='The Beatles',
|
|
... membership__date_joined__gt=date(1961,1,1))
|
|
[<Person: Ringo Starr]
|
|
|
|
One-to-one relationships
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To define a one-to-one relationship, use ``OneToOneField``. You use it just
|
|
like any other ``Field`` type: by including it as a class attribute of your
|
|
model.
|
|
|
|
This is most useful on the primary key of an object when that object "extends"
|
|
another object in some way.
|
|
|
|
``OneToOneField`` requires a positional argument: the class to which the
|
|
model is related.
|
|
|
|
For example, if you're building a database of "places", you would build pretty
|
|
standard stuff such as address, phone number, etc. in the database. Then, if you
|
|
wanted to build a database of restaurants on top of the places, instead of
|
|
repeating yourself and replicating those fields in the ``Restaurant`` model, you
|
|
could make ``Restaurant`` have a ``OneToOneField`` to ``Place`` (because a
|
|
restaurant "is-a" place).
|
|
|
|
As with ``ForeignKey``, a relationship to self can be defined by using the
|
|
string ``"self"`` instead of the model name; references to as-yet undefined
|
|
models can be made by using a string containing the model name.
|
|
|
|
Finally, ``OneToOneField`` takes the following extra option:
|
|
|
|
======================= ============================================================
|
|
Argument Description
|
|
======================= ============================================================
|
|
``parent_link`` When ``True`` and used in a model inherited from
|
|
another model, indicates that this field should
|
|
be used as the link from the child back to the
|
|
parent. See `Model inheritance`_ for more
|
|
details.
|
|
|
|
**New in Django development version**
|
|
|
|
======================= ============================================================
|
|
|
|
**New in Django development version:** ``OneToOneField`` classes used to
|
|
automatically become the primary key on a model. This is no longer true,
|
|
although you can manually pass in the ``primary_key`` attribute if you like.
|
|
Thus, it's now possible to have multiple fields of type ``OneToOneField`` on a
|
|
single model.
|
|
|
|
See the `One-to-one relationship model example`_ for a full example.
|
|
|
|
.. _One-to-one relationship model example: ../models/one_to_one/
|
|
|
|
Custom field types
|
|
------------------
|
|
|
|
**New in Django development version**
|
|
|
|
If one of the existing model fields cannot be used to fit your purposes, or if
|
|
you wish to take advantage of some less common database column types, you can
|
|
create your own field class. Full coverage of creating your own fields is
|
|
provided in the `Custom Model Fields`_ documentation.
|
|
|
|
.. _Custom Model Fields: ../custom_model_fields/
|
|
|
|
Meta options
|
|
============
|
|
|
|
Give your model metadata by using an inner ``class Meta``, like so::
|
|
|
|
class Foo(models.Model):
|
|
bar = models.CharField(max_length=30)
|
|
|
|
class Meta:
|
|
# ...
|
|
|
|
Model metadata is "anything that's not a field", such as ordering options, etc.
|
|
|
|
Here's a list of all possible ``Meta`` options. No options are required. Adding
|
|
``class Meta`` to a model is completely optional.
|
|
|
|
``abstract``
|
|
------------
|
|
|
|
**New in Django development version**
|
|
|
|
When set to ``True``, denotes this model as an abstract base class. See
|
|
`Abstract base classes`_ for more details. Defaults to ``False``.
|
|
|
|
``db_table``
|
|
------------
|
|
|
|
The name of the database table to use for the model::
|
|
|
|
db_table = 'music_album'
|
|
|
|
If this isn't given, Django will use ``app_label + '_' + model_class_name``.
|
|
See "Table names" below for more.
|
|
|
|
If your database table name is an SQL reserved word, or contains characters
|
|
that aren't allowed in Python variable names -- notably, the hyphen --
|
|
that's OK. Django quotes column and table names behind the scenes.
|
|
|
|
``db_tablespace``
|
|
-----------------
|
|
|
|
**New in Django development version**
|
|
|
|
The name of the database tablespace to use for the model. If the backend
|
|
doesn't support tablespaces, this option is ignored.
|
|
|
|
``get_latest_by``
|
|
-----------------
|
|
|
|
The name of a ``DateField`` or ``DateTimeField`` in the model. This specifies
|
|
the default field to use in your model ``Manager``'s ``latest()`` method.
|
|
|
|
Example::
|
|
|
|
get_latest_by = "order_date"
|
|
|
|
See the `docs for latest()`_ for more.
|
|
|
|
.. _docs for latest(): ../db-api/#latest-field-name-none
|
|
|
|
``order_with_respect_to``
|
|
-------------------------
|
|
|
|
Marks this object as "orderable" with respect to the given field. This is
|
|
almost always used with related objects to allow them to be ordered with
|
|
respect to a parent object. For example, if an ``Answer`` relates to a
|
|
``Question`` object, and a question has more than one answer, and the order
|
|
of answers matters, you'd do this::
|
|
|
|
class Answer(models.Model):
|
|
question = models.ForeignKey(Question)
|
|
# ...
|
|
|
|
class Meta:
|
|
order_with_respect_to = 'question'
|
|
|
|
``ordering``
|
|
------------
|
|
|
|
The default ordering for the object, for use when obtaining lists of objects::
|
|
|
|
ordering = ['-order_date']
|
|
|
|
This is a tuple or list of strings. Each string is a field name with an
|
|
optional "-" prefix, which indicates descending order. Fields without a
|
|
leading "-" will be ordered ascending. Use the string "?" to order randomly.
|
|
|
|
For example, to order by a ``pub_date`` field ascending, use this::
|
|
|
|
ordering = ['pub_date']
|
|
|
|
To order by ``pub_date`` descending, use this::
|
|
|
|
ordering = ['-pub_date']
|
|
|
|
To order by ``pub_date`` descending, then by ``author`` ascending, use this::
|
|
|
|
ordering = ['-pub_date', 'author']
|
|
|
|
See `Specifying ordering`_ for more examples.
|
|
|
|
Note that, regardless of how many fields are in ``ordering``, the admin
|
|
site uses only the first field.
|
|
|
|
.. _Specifying ordering: ../models/ordering/
|
|
|
|
``permissions``
|
|
---------------
|
|
|
|
Extra permissions to enter into the permissions table when creating this
|
|
object. Add, delete and change permissions are automatically created for
|
|
each object that has ``admin`` set. This example specifies an extra
|
|
permission, ``can_deliver_pizzas``::
|
|
|
|
permissions = (("can_deliver_pizzas", "Can deliver pizzas"),)
|
|
|
|
This is a list or tuple of 2-tuples in the format
|
|
``(permission_code, human_readable_permission_name)``.
|
|
|
|
``unique_together``
|
|
-------------------
|
|
|
|
Sets of field names that, taken together, must be unique::
|
|
|
|
unique_together = (("driver", "restaurant"),)
|
|
|
|
This is a list of lists of fields that must be unique when considered
|
|
together. It's used in the Django admin and is enforced at the database
|
|
level (i.e., the appropriate ``UNIQUE`` statements are included in the
|
|
``CREATE TABLE`` statement).
|
|
|
|
All the fields specified in ``unique_together`` must be part of the current
|
|
model. If you are using `model inheritance`_, you cannot refer to fields from
|
|
any parent classes in ``unique_together``.
|
|
|
|
**New in Django development version**
|
|
|
|
For convenience, unique_together can be a single list when dealing
|
|
with a single set of fields::
|
|
|
|
unique_together = ("driver", "restaurant")
|
|
|
|
``verbose_name``
|
|
----------------
|
|
|
|
A human-readable name for the object, singular::
|
|
|
|
verbose_name = "pizza"
|
|
|
|
If this isn't given, Django will use a munged version of the class name:
|
|
``CamelCase`` becomes ``camel case``.
|
|
|
|
``verbose_name_plural``
|
|
-----------------------
|
|
|
|
The plural name for the object::
|
|
|
|
verbose_name_plural = "stories"
|
|
|
|
If this isn't given, Django will use ``verbose_name + "s"``.
|
|
|
|
Table names
|
|
===========
|
|
|
|
To save you time, Django automatically derives the name of the database table
|
|
from the name of your model class and the app that contains it. A model's
|
|
database table name is constructed by joining the model's "app label" -- the
|
|
name you used in ``manage.py startapp`` -- to the model's class name, with an
|
|
underscore between them.
|
|
|
|
For example, if you have an app ``bookstore`` (as created by
|
|
``manage.py startapp bookstore``), a model defined as ``class Book`` will have
|
|
a database table named ``bookstore_book``.
|
|
|
|
To override the database table name, use the ``db_table`` parameter in
|
|
``class Meta``.
|
|
|
|
Automatic primary key fields
|
|
============================
|
|
|
|
By default, Django gives each model the following field::
|
|
|
|
id = models.AutoField(primary_key=True)
|
|
|
|
This is an auto-incrementing primary key.
|
|
|
|
If you'd like to specify a custom primary key, just specify ``primary_key=True``
|
|
on one of your fields. If Django sees you've explicitly set ``primary_key``, it
|
|
won't add the automatic ``id`` column.
|
|
|
|
Each model requires exactly one field to have ``primary_key=True``.
|
|
|
|
The ``pk`` property
|
|
-------------------
|
|
**New in Django development version**
|
|
|
|
Regardless of whether you define a primary key field yourself, or let Django
|
|
supply one for you, each model will have a property called ``pk``. It behaves
|
|
like a normal attribute on the model, but is actually an alias for whichever
|
|
attribute is the primary key field for the model. You can read and set this
|
|
value, just as you would for any other attribute, and it will update the
|
|
correct field in the model.
|
|
|
|
Managers
|
|
========
|
|
|
|
A ``Manager`` is the interface through which database query operations are
|
|
provided to Django models. At least one ``Manager`` exists for every model in
|
|
a Django application.
|
|
|
|
The way ``Manager`` classes work is documented in the `Retrieving objects`_
|
|
section of the database API docs, but this section specifically touches on
|
|
model options that customize ``Manager`` behavior.
|
|
|
|
.. _Retrieving objects: ../db-api/#retrieving-objects
|
|
|
|
Manager names
|
|
-------------
|
|
|
|
By default, Django adds a ``Manager`` with the name ``objects`` to every Django
|
|
model class. However, if you want to use ``objects`` as a field name, or if you
|
|
want to use a name other than ``objects`` for the ``Manager``, you can rename
|
|
it on a per-model basis. To rename the ``Manager`` for a given class, define a
|
|
class attribute of type ``models.Manager()`` on that model. For example::
|
|
|
|
from django.db import models
|
|
|
|
class Person(models.Model):
|
|
#...
|
|
people = models.Manager()
|
|
|
|
Using this example model, ``Person.objects`` will generate an
|
|
``AttributeError`` exception, but ``Person.people.all()`` will provide a list
|
|
of all ``Person`` objects.
|
|
|
|
Custom Managers
|
|
---------------
|
|
|
|
You can use a custom ``Manager`` in a particular model by extending the base
|
|
``Manager`` class and instantiating your custom ``Manager`` in your model.
|
|
|
|
There are two reasons you might want to customize a ``Manager``: to add extra
|
|
``Manager`` methods, and/or to modify the initial ``QuerySet`` the ``Manager``
|
|
returns.
|
|
|
|
Adding extra Manager methods
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Adding extra ``Manager`` methods is the preferred way to add "table-level"
|
|
functionality to your models. (For "row-level" functionality -- i.e., functions
|
|
that act on a single instance of a model object -- use `Model methods`_, not
|
|
custom ``Manager`` methods.)
|
|
|
|
A custom ``Manager`` method can return anything you want. It doesn't have to
|
|
return a ``QuerySet``.
|
|
|
|
For example, this custom ``Manager`` offers a method ``with_counts()``, which
|
|
returns a list of all ``OpinionPoll`` objects, each with an extra
|
|
``num_responses`` attribute that is the result of an aggregate query::
|
|
|
|
class PollManager(models.Manager):
|
|
def with_counts(self):
|
|
from django.db import connection
|
|
cursor = connection.cursor()
|
|
cursor.execute("""
|
|
SELECT p.id, p.question, p.poll_date, COUNT(*)
|
|
FROM polls_opinionpoll p, polls_response r
|
|
WHERE p.id = r.poll_id
|
|
GROUP BY 1, 2, 3
|
|
ORDER BY 3 DESC""")
|
|
result_list = []
|
|
for row in cursor.fetchall():
|
|
p = self.model(id=row[0], question=row[1], poll_date=row[2])
|
|
p.num_responses = row[3]
|
|
result_list.append(p)
|
|
return result_list
|
|
|
|
class OpinionPoll(models.Model):
|
|
question = models.CharField(max_length=200)
|
|
poll_date = models.DateField()
|
|
objects = PollManager()
|
|
|
|
class Response(models.Model):
|
|
poll = models.ForeignKey(Poll)
|
|
person_name = models.CharField(max_length=50)
|
|
response = models.TextField()
|
|
|
|
With this example, you'd use ``OpinionPoll.objects.with_counts()`` to return
|
|
that list of ``OpinionPoll`` objects with ``num_responses`` attributes.
|
|
|
|
Another thing to note about this example is that ``Manager`` methods can
|
|
access ``self.model`` to get the model class to which they're attached.
|
|
|
|
Modifying initial Manager QuerySets
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
A ``Manager``'s base ``QuerySet`` returns all objects in the system. For
|
|
example, using this model::
|
|
|
|
class Book(models.Model):
|
|
title = models.CharField(max_length=100)
|
|
author = models.CharField(max_length=50)
|
|
|
|
...the statement ``Book.objects.all()`` will return all books in the database.
|
|
|
|
You can override a ``Manager``\'s base ``QuerySet`` by overriding the
|
|
``Manager.get_query_set()`` method. ``get_query_set()`` should return a
|
|
``QuerySet`` with the properties you require.
|
|
|
|
For example, the following model has *two* ``Manager``\s -- one that returns
|
|
all objects, and one that returns only the books by Roald Dahl::
|
|
|
|
# First, define the Manager subclass.
|
|
class DahlBookManager(models.Manager):
|
|
def get_query_set(self):
|
|
return super(DahlBookManager, self).get_query_set().filter(author='Roald Dahl')
|
|
|
|
# Then hook it into the Book model explicitly.
|
|
class Book(models.Model):
|
|
title = models.CharField(max_length=100)
|
|
author = models.CharField(max_length=50)
|
|
|
|
objects = models.Manager() # The default manager.
|
|
dahl_objects = DahlBookManager() # The Dahl-specific manager.
|
|
|
|
With this sample model, ``Book.objects.all()`` will return all books in the
|
|
database, but ``Book.dahl_objects.all()`` will only return the ones written by
|
|
Roald Dahl.
|
|
|
|
Of course, because ``get_query_set()`` returns a ``QuerySet`` object, you can
|
|
use ``filter()``, ``exclude()`` and all the other ``QuerySet`` methods on it.
|
|
So these statements are all legal::
|
|
|
|
Book.dahl_objects.all()
|
|
Book.dahl_objects.filter(title='Matilda')
|
|
Book.dahl_objects.count()
|
|
|
|
This example also pointed out another interesting technique: using multiple
|
|
managers on the same model. You can attach as many ``Manager()`` instances to
|
|
a model as you'd like. This is an easy way to define common "filters" for your
|
|
models.
|
|
|
|
For example::
|
|
|
|
class MaleManager(models.Manager):
|
|
def get_query_set(self):
|
|
return super(MaleManager, self).get_query_set().filter(sex='M')
|
|
|
|
class FemaleManager(models.Manager):
|
|
def get_query_set(self):
|
|
return super(FemaleManager, self).get_query_set().filter(sex='F')
|
|
|
|
class Person(models.Model):
|
|
first_name = models.CharField(max_length=50)
|
|
last_name = models.CharField(max_length=50)
|
|
sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female')))
|
|
people = models.Manager()
|
|
men = MaleManager()
|
|
women = FemaleManager()
|
|
|
|
This example allows you to request ``Person.men.all()``, ``Person.women.all()``,
|
|
and ``Person.people.all()``, yielding predictable results.
|
|
|
|
If you use custom ``Manager`` objects, take note that the first
|
|
``Manager`` Django encounters (in the order in which they're defined
|
|
in the model) has a special status. Django interprets this first
|
|
``Manager`` defined in a class as the "default" ``Manager``, and
|
|
several parts of Django (though not the admin application) will use
|
|
that ``Manager`` exclusively for that model. As a result, it's often a
|
|
good idea to be careful in your choice of default manager, in order to
|
|
avoid a situation where overriding of ``get_query_set()`` results in
|
|
an inability to retrieve objects you'd like to work with.
|
|
|
|
Using managers for related object access
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
By default, Django uses a "bare" (i.e. default) manager when accessing related
|
|
objects (i.e. ``choice.poll``). If this default isn't appropriate for your
|
|
default manager, you can force Django to use a custom manager for related object
|
|
attributes by giving it a ``use_for_related_fields`` property::
|
|
|
|
class MyManager(models.Manager)::
|
|
use_for_related_fields = True
|
|
|
|
...
|
|
|
|
Model methods
|
|
=============
|
|
|
|
Define custom methods on a model to add custom "row-level" functionality to
|
|
your objects. Whereas ``Manager`` methods are intended to do "table-wide"
|
|
things, model methods should act on a particular model instance.
|
|
|
|
This is a valuable technique for keeping business logic in one place -- the
|
|
model.
|
|
|
|
For example, this model has a few custom methods::
|
|
|
|
class Person(models.Model):
|
|
first_name = models.CharField(max_length=50)
|
|
last_name = models.CharField(max_length=50)
|
|
birth_date = models.DateField()
|
|
address = models.CharField(max_length=100)
|
|
city = models.CharField(max_length=50)
|
|
state = models.USStateField() # Yes, this is America-centric...
|
|
|
|
def baby_boomer_status(self):
|
|
"Returns the person's baby-boomer status."
|
|
import datetime
|
|
if datetime.date(1945, 8, 1) <= self.birth_date <= datetime.date(1964, 12, 31):
|
|
return "Baby boomer"
|
|
if self.birth_date < datetime.date(1945, 8, 1):
|
|
return "Pre-boomer"
|
|
return "Post-boomer"
|
|
|
|
def is_midwestern(self):
|
|
"Returns True if this person is from the Midwest."
|
|
return self.state in ('IL', 'WI', 'MI', 'IN', 'OH', 'IA', 'MO')
|
|
|
|
def _get_full_name(self):
|
|
"Returns the person's full name."
|
|
return '%s %s' % (self.first_name, self.last_name)
|
|
full_name = property(_get_full_name)
|
|
|
|
The last method in this example is a *property*. `Read more about properties`_.
|
|
|
|
.. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property
|
|
|
|
A few object methods have special meaning:
|
|
|
|
``__str__``
|
|
-----------
|
|
|
|
``__str__()`` is a Python "magic method" that defines what should be returned
|
|
if you call ``str()`` on the object. Django uses ``str(obj)`` (or the related
|
|
function, ``unicode(obj)`` -- see below) in a number of places, most notably
|
|
as the value displayed to render an object in the Django admin site and as the
|
|
value inserted into a template when it displays an object. Thus, you should
|
|
always return a nice, human-readable string for the object's ``__str__``.
|
|
Although this isn't required, it's strongly encouraged (see the description of
|
|
``__unicode__``, below, before putting ``__str__`` methods everywhere).
|
|
|
|
For example::
|
|
|
|
class Person(models.Model):
|
|
first_name = models.CharField(max_length=50)
|
|
last_name = models.CharField(max_length=50)
|
|
|
|
def __str__(self):
|
|
# Note use of django.utils.encoding.smart_str() here because
|
|
# first_name and last_name will be unicode strings.
|
|
return smart_str('%s %s' % (self.first_name, self.last_name))
|
|
|
|
``__unicode__``
|
|
---------------
|
|
|
|
The ``__unicode__()`` method is called whenever you call ``unicode()`` on an
|
|
object. Since Django's database backends will return Unicode strings in your
|
|
model's attributes, you would normally want to write a ``__unicode__()``
|
|
method for your model. The example in the previous section could be written
|
|
more simply as::
|
|
|
|
class Person(models.Model):
|
|
first_name = models.CharField(max_length=50)
|
|
last_name = models.CharField(max_length=50)
|
|
|
|
def __unicode__(self):
|
|
return u'%s %s' % (self.first_name, self.last_name)
|
|
|
|
If you define a ``__unicode__()`` method on your model and not a ``__str__()``
|
|
method, Django will automatically provide you with a ``__str__()`` that calls
|
|
``__unicode__()`` and then converts the result correctly to a UTF-8 encoded
|
|
string object. This is recommended development practice: define only
|
|
``__unicode__()`` and let Django take care of the conversion to string objects
|
|
when required.
|
|
|
|
``get_absolute_url``
|
|
--------------------
|
|
|
|
Define a ``get_absolute_url()`` method to tell Django how to calculate the
|
|
URL for an object. For example::
|
|
|
|
def get_absolute_url(self):
|
|
return "/people/%i/" % self.id
|
|
|
|
Django uses this in its admin interface. If an object defines
|
|
``get_absolute_url()``, the object-editing page will have a "View on site"
|
|
link that will jump you directly to the object's public view, according to
|
|
``get_absolute_url()``.
|
|
|
|
Also, a couple of other bits of Django, such as the `syndication feed framework`_,
|
|
use ``get_absolute_url()`` as a convenience to reward people who've defined the
|
|
method.
|
|
|
|
.. _syndication feed framework: ../syndication_feeds/
|
|
|
|
It's good practice to use ``get_absolute_url()`` in templates, instead of
|
|
hard-coding your objects' URLs. For example, this template code is bad::
|
|
|
|
<a href="/people/{{ object.id }}/">{{ object.name }}</a>
|
|
|
|
But this template code is good::
|
|
|
|
<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>
|
|
|
|
.. note::
|
|
The string you return from ``get_absolute_url()`` must contain only ASCII
|
|
characters (required by the URI spec, `RFC 2396`_) that have been
|
|
URL-encoded, if necessary. Code and templates using ``get_absolute_url()``
|
|
should be able to use the result directly without needing to do any
|
|
further processing. You may wish to use the
|
|
``django.utils.encoding.iri_to_uri()`` function to help with this if you
|
|
are using unicode strings a lot.
|
|
|
|
.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt
|
|
|
|
The ``permalink`` decorator
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The problem with the way we wrote ``get_absolute_url()`` above is that it
|
|
slightly violates the DRY principle: the URL for this object is defined both
|
|
in the URLConf file and in the model.
|
|
|
|
You can further decouple your models from the URLconf using the ``permalink``
|
|
decorator. This decorator is passed the view function, a list of positional
|
|
parameters and (optionally) a dictionary of named parameters. Django then
|
|
works out the correct full URL path using the URLconf, substituting the
|
|
parameters you have given into the URL. For example, if your URLconf
|
|
contained a line such as::
|
|
|
|
(r'^people/(\d+)/$', 'people.views.details'),
|
|
|
|
...your model could have a ``get_absolute_url`` method that looked like this::
|
|
|
|
from django.db.models import permalink
|
|
|
|
def get_absolute_url(self):
|
|
return ('people.views.details', [str(self.id)])
|
|
get_absolute_url = permalink(get_absolute_url)
|
|
|
|
Similarly, if you had a URLconf entry that looked like::
|
|
|
|
(r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view)
|
|
|
|
...you could reference this using ``permalink()`` as follows::
|
|
|
|
def get_absolute_url(self):
|
|
return ('archive_view', (), {
|
|
'year': self.created.year,
|
|
'month': self.created.month,
|
|
'day': self.created.day})
|
|
get_absolute_url = permalink(get_absolute_url)
|
|
|
|
Notice that we specify an empty sequence for the second parameter in this case,
|
|
because we only want to pass keyword parameters, not positional ones.
|
|
|
|
In this way, you're tying the model's absolute URL to the view that is used
|
|
to display it, without repeating the URL information anywhere. You can still
|
|
use the ``get_absolute_url`` method in templates, as before.
|
|
|
|
In some cases, such as the use of generic views or the re-use of
|
|
custom views for multiple models, specifying the view function may
|
|
confuse the reverse URL matcher (because multiple patterns point to
|
|
the same view).
|
|
|
|
For that problem, Django has **named URL patterns**. Using a named
|
|
URL pattern, it's possible to give a name to a pattern, and then
|
|
reference the name rather than the view function. A named URL
|
|
pattern is defined by replacing the pattern tuple by a call to
|
|
the ``url`` function)::
|
|
|
|
from django.conf.urls.defaults import *
|
|
|
|
url(r'^people/(\d+)/$',
|
|
'django.views.generic.list_detail.object_detail',
|
|
name='people_view'),
|
|
|
|
...and then using that name to perform the reverse URL resolution instead
|
|
of the view name::
|
|
|
|
from django.db.models import permalink
|
|
|
|
def get_absolute_url(self):
|
|
return ('people_view', [str(self.id)])
|
|
get_absolute_url = permalink(get_absolute_url)
|
|
|
|
More details on named URL patterns are in the `URL dispatch documentation`_.
|
|
|
|
.. _URL dispatch documentation: ../url_dispatch/#naming-url-patterns
|
|
|
|
Executing custom SQL
|
|
--------------------
|
|
|
|
Feel free to write custom SQL statements in custom model methods and
|
|
module-level methods. The object ``django.db.connection`` represents the
|
|
current database connection. To use it, call ``connection.cursor()`` to get a
|
|
cursor object. Then, call ``cursor.execute(sql, [params])`` to execute the SQL
|
|
and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return the resulting
|
|
rows. Example::
|
|
|
|
def my_custom_sql(self):
|
|
from django.db import connection
|
|
cursor = connection.cursor()
|
|
cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
|
|
row = cursor.fetchone()
|
|
return row
|
|
|
|
``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
|
|
(except when it comes to `transaction handling`_). If you're not familiar with
|
|
the Python DB-API, note that the SQL statement in ``cursor.execute()`` uses
|
|
placeholders, ``"%s"``, rather than adding parameters directly within the SQL.
|
|
If you use this technique, the underlying database library will automatically
|
|
add quotes and escaping to your parameter(s) as necessary. (Also note that
|
|
Django expects the ``"%s"`` placeholder, *not* the ``"?"`` placeholder, which is
|
|
used by the SQLite Python bindings. This is for the sake of consistency and
|
|
sanity.)
|
|
|
|
A final note: If all you want to do is a custom ``WHERE`` clause, you can just
|
|
use the ``where``, ``tables`` and ``params`` arguments to the standard lookup
|
|
API. See `Other lookup options`_.
|
|
|
|
.. _Python DB-API: http://www.python.org/peps/pep-0249.html
|
|
.. _Other lookup options: ../db-api/#extra-select-none-where-none-params-none-tables-none
|
|
.. _transaction handling: ../transactions/
|
|
|
|
Overriding default model methods
|
|
--------------------------------
|
|
|
|
As explained in the `database API docs`_, each model gets a few methods
|
|
automatically -- most notably, ``save()`` and ``delete()``. You can override
|
|
these methods to alter behavior.
|
|
|
|
A classic use-case for overriding the built-in methods is if you want something
|
|
to happen whenever you save an object. For example::
|
|
|
|
class Blog(models.Model):
|
|
name = models.CharField(max_length=100)
|
|
tagline = models.TextField()
|
|
|
|
def save(self):
|
|
do_something()
|
|
super(Blog, self).save() # Call the "real" save() method.
|
|
do_something_else()
|
|
|
|
You can also prevent saving::
|
|
|
|
class Blog(models.Model):
|
|
name = models.CharField(max_length=100)
|
|
tagline = models.TextField()
|
|
|
|
def save(self):
|
|
if self.name == "Yoko Ono's blog":
|
|
return # Yoko shall never have her own blog!
|
|
else:
|
|
super(Blog, self).save() # Call the "real" save() method.
|
|
|
|
.. _database API docs: ../db-api/
|
|
|
|
Model inheritance
|
|
=================
|
|
|
|
**New in Django development version**
|
|
|
|
Model inheritance in Django works almost identically to the way normal class
|
|
inheritance works in Python. The only decision you have to make is whether you
|
|
want the parent models to be models in their own right (with their own
|
|
database tables), or if the parents are just holders of common information
|
|
that will only be visible through the child models.
|
|
|
|
Often, you will just want to use the parent class to hold information that you
|
|
don't want to have to type out for each child model. This class isn't going to
|
|
ever be used in isolation, so `abstract base classes`_ are what you're after. However, if you're subclassing an existing model (perhaps something from another application entirely), or want each model to have its own database table, `multi-table inheritance`_ is the way to go.
|
|
|
|
Abstract base classes
|
|
---------------------
|
|
|
|
Abstract base classes are useful when you want to put some common information
|
|
into a number of other models. You write your base class and put
|
|
``abstract=True`` in the ``Meta`` class. This model will then not be used to
|
|
create any database table. Instead, when it is used as a base class for other
|
|
models, its fields will be added to those of the child class. It is an error
|
|
to have fields in the abstract base class with the same name as those in the
|
|
child (and Django will raise an exception).
|
|
|
|
An example::
|
|
|
|
class CommonInfo(models.Model):
|
|
name = models.CharField(max_length=100)
|
|
age = models.PositiveIntegerField()
|
|
|
|
class Meta:
|
|
abstract = True
|
|
|
|
class Student(CommonInfo):
|
|
home_group = models.CharField(max_length=5)
|
|
|
|
The ``Student`` model will have three fields: ``name``, ``age`` and
|
|
``home_group``. The ``CommonInfo`` model cannot be used as a normal Django
|
|
model, since it is an abstract base class. It does not generate a database
|
|
table or have a manager or anything like that.
|
|
|
|
For many uses, this type of model inheritance will be exactly what you want.
|
|
It provides a way to factor out common information at the Python level, whilst
|
|
still only creating one database table per child model at the database level.
|
|
|
|
``Meta`` inheritance
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When an abstract base class is created, Django makes any ``Meta`` inner class
|
|
you declared on the base class available as an attribute. If a child class
|
|
does not declare its own ``Meta`` class, it will inherit the parent's
|
|
``Meta``. If the child wants to extend the parent's ``Meta`` class, it can
|
|
subclass it. For example::
|
|
|
|
class CommonInfo(models.Model):
|
|
...
|
|
class Meta:
|
|
abstract = True
|
|
ordering = ['name']
|
|
|
|
class Student(CommonInfo):
|
|
...
|
|
class Meta(CommonInfo.Meta):
|
|
db_table = 'student_info'
|
|
|
|
Django does make one adjustment to the ``Meta`` class of an abstract base
|
|
class: before installing the ``Meta`` attribute, it sets ``abstract=False``.
|
|
This means that children of abstract base classes don't automatically become
|
|
abstract classes themselves. Of course, you can make an abstract base class
|
|
that inherits from another abstract base class. You just need to remember to
|
|
explicitly set ``abstract=True`` each time.
|
|
|
|
Some attributes won't make sense to include in the ``Meta`` class of an
|
|
abstract base class. For example, including ``db_table`` would mean that all
|
|
the child classes (the ones that don't specify their own ``Meta``) would use
|
|
the same database table, which is almost certainly not what you want.
|
|
|
|
Be careful with ``related_name``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If you are using the ``related_name`` attribute on a ``ForeignKey`` or
|
|
``ManyToManyField``, you must always specify a *unique* reverse name for the
|
|
field. This would normally cause a problem in abstract base classes, since the
|
|
fields on this class are included into each of the child classes, with exactly
|
|
the same values for the attributes (including ``related_name``) each time.
|
|
|
|
To work around this problem, when you are using ``related_name`` in an
|
|
abstract base class (only), part of the name should be the string
|
|
``'%(class)s'``. This is replaced by the lower-cased name of the child class
|
|
that the field is used in. Since each class has a different name, each related
|
|
name will end up being different. For example::
|
|
|
|
class Base(models.Model):
|
|
m2m = models.ManyToMany(OtherModel, related_name="%(class)s_related")
|
|
|
|
class Meta:
|
|
abstract = True
|
|
|
|
class ChildA(Base):
|
|
pass
|
|
|
|
class ChildB(Base):
|
|
pass
|
|
|
|
The reverse name of the ``ChildA.m2m`` field will be ``childa_related``,
|
|
whilst the reverse name of the ``ChildB.m2m`` field will be
|
|
``childb_related``. It is up to you how you use the ``'%(class)s'`` portion to
|
|
construct your related name, but if you forget to use it, Django will raise
|
|
errors when you validate your models (or run ``syncdb``).
|
|
|
|
If you don't specify a ``related_name`` attribute for a field in an abstract
|
|
base class, the default reverse name will be the name of the child class
|
|
followed by ``'_set'``, just as it normally would be if you'd declared the field directly on the child class. For example, in the above code, if the ``related_name`` attribute was omitted, the reverse name for the ``m2m`` field would be ``childa_set`` in the ``ChildA`` case and ``childb_set`` for the ``ChildB`` field.
|
|
|
|
Multi-table inheritance
|
|
-----------------------
|
|
|
|
The second type of model inheritance supported by Django is when each model in
|
|
the hierarchy is a model all by itself. Each model corresponds to its own
|
|
database table and can be queried and created individually. The inheritance
|
|
relationship introduces links between the child model and each of its parents
|
|
(via an automatically created ``OneToOneField``). For example::
|
|
|
|
class Place(models.Model):
|
|
name = models.CharField(max_length=50)
|
|
address = models.CharField(max_length=80)
|
|
|
|
class Restaurant(Place):
|
|
serves_hot_dogs = models.BooleanField()
|
|
serves_pizza = models.BooleanField()
|
|
|
|
All of the fields of ``Place`` will also be available in ``Restaurant``,
|
|
although the data will reside in a different database table. So these are both
|
|
possible::
|
|
|
|
>>> Place.objects.filter(name="Bob's Cafe")
|
|
>>> Restaurant.objects.filter(name="Bob's Cafe")
|
|
|
|
If you have a ``Place`` that is also a ``Restaurant``, you can get from the
|
|
``Place`` object to the ``Restaurant`` object by using the lower-case version
|
|
of the model name::
|
|
|
|
>>> p = Place.objects.filter(name="Bob's Cafe")
|
|
# If Bob's Cafe is a Restaurant object, this will give the child class:
|
|
>>> p.restaurant
|
|
<Restaurant: ...>
|
|
|
|
However, if ``p`` in the above example was *not* a ``Restaurant`` (it had been
|
|
created directly as a ``Place`` object or was the parent of some other class),
|
|
referring to ``p.restaurant`` would give an error.
|
|
|
|
``Meta`` and multi-table inheritance
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
In the multi-table inheritance situation, it doesn't make sense for a child
|
|
class to inherit from its parent's ``Meta`` class. All the ``Meta`` options
|
|
have already been applied to the parent class and applying them again would
|
|
normally only lead to contradictory behaviour (this is in contrast with the
|
|
abstract base class case, where the base class doesn't exist in its own
|
|
right).
|
|
|
|
So a child model does not have access to its parent's ``Meta`` class. However,
|
|
there are a few limited cases where the child inherits behaviour from the
|
|
parent: if the child does not specify an ``ordering`` attribute or a
|
|
``get_latest_by`` attribute, it will inherit these from its parent.
|
|
|
|
If the parent has an ordering and you don't want the child to have any natural
|
|
ordering, you can explicitly set it to be empty::
|
|
|
|
class ChildModel(ParentModel):
|
|
...
|
|
class Meta:
|
|
# Remove parent's ordering effect
|
|
ordering = []
|
|
|
|
Inheritance and reverse relations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Because multi-table inheritance uses an implicit ``OneToOneField`` to link the
|
|
child and the parent, it's possible to move from the parent down to the child,
|
|
as in the above example. However, this uses up the name that is the default
|
|
``related_name`` value for ``ForeignKey`` and ``ManyToManyField`` relations.
|
|
If you are putting those type of relations on a subclass of another model, you
|
|
**must** specify the ``related_name`` attribute on each such field. If you
|
|
forget, Django will raise an error when you run ``manage.py validate`` or try
|
|
to syncdb.
|
|
|
|
For example, using the above ``Place`` class again, let's create another
|
|
subclass with a ``ManyToManyField``::
|
|
|
|
class Supplier(Place):
|
|
# Must specify related_name on all relations.
|
|
customers = models.ManyToManyField(Restaurant,
|
|
related_name='provider')
|
|
|
|
For more information about reverse relations, refer to the `Database API
|
|
reference`_ . For now, just remember to run ``manage.py validate`` when
|
|
you're writing your models and pay attention to the error messages.
|
|
|
|
Specifying the parent link field
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
As mentioned, Django will automatically create a ``OneToOneField`` linking
|
|
your child class back any non-abstract parent models. If you want to control
|
|
the name of the attribute linking back to the parent, you can create your own
|
|
link field and pass it ``parent_link=True``. For example, to explicitly
|
|
specify the field that will link ``Supplier`` to ``Place`` in the above
|
|
example, you could write::
|
|
|
|
class Supplier(Place):
|
|
parent = models.OneToOneField(Place, parent_link=True)
|
|
...
|
|
|
|
Multiple inheritance
|
|
--------------------
|
|
|
|
Just as with Python's subclassing, it's possible for a Django model to inherit
|
|
from multiple parent models. Keep in mind that normal Python name resolution
|
|
rules apply. The first base class that a particular name appears in (e.g.
|
|
``Meta``) will be the one that is used. We stop searching once we find the
|
|
name once. This means that if multiple parents contain a ``Meta`` class, only
|
|
the first one is going to be used. All others will be ignored.
|
|
|
|
Generally, you won't need to inherit from multiple parents. The main use-case
|
|
where this is useful is for ''mix-in'' classes: adding a particular extra
|
|
field or method to every class that inherits the mix-in. Try to keep your
|
|
inheritance hierarchies as simple and straightforward as possible so that you
|
|
won't have to struggle to work out where a particular piece of information is
|
|
coming from.
|
|
|
|
Models across files
|
|
===================
|
|
|
|
It's perfectly OK to relate a model to one from another app. To do this, just
|
|
import the related model at the top of the model that holds your model. Then,
|
|
just refer to the other model class wherever needed. For example::
|
|
|
|
from mysite.geography.models import ZipCode
|
|
|
|
class Restaurant(models.Model):
|
|
# ...
|
|
zip_code = models.ForeignKey(ZipCode)
|
|
|
|
Using models
|
|
============
|
|
|
|
Once you have created your models, the final step is to tell Django you're
|
|
going to *use* those models.
|
|
|
|
Do this by editing your settings file and changing the ``INSTALLED_APPS``
|
|
setting to add the name of the module that contains your ``models.py``.
|
|
|
|
For example, if the models for your application live in the module
|
|
``mysite.myapp.models`` (the package structure that is created for an
|
|
application by the ``manage.py startapp`` script), ``INSTALLED_APPS`` should
|
|
read, in part::
|
|
|
|
INSTALLED_APPS = (
|
|
#...
|
|
'mysite.myapp',
|
|
#...
|
|
)
|
|
|
|
Providing initial SQL data
|
|
==========================
|
|
|
|
Django provides a hook for passing the database arbitrary SQL that's executed
|
|
just after the CREATE TABLE statements. Use this hook, for example, if you want
|
|
to populate default records, or create SQL functions, automatically.
|
|
|
|
The hook is simple: Django just looks for a file called
|
|
``<appname>/sql/<modelname>.sql``, where ``<appname>`` is your app directory and
|
|
``<modelname>`` is the model's name in lowercase.
|
|
|
|
In the ``Person`` example model at the top of this document, assuming it lives
|
|
in an app called ``myapp``, you could add arbitrary SQL to the file
|
|
``myapp/sql/person.sql``. Here's an example of what the file might contain::
|
|
|
|
INSERT INTO myapp_person (first_name, last_name) VALUES ('John', 'Lennon');
|
|
INSERT INTO myapp_person (first_name, last_name) VALUES ('Paul', 'McCartney');
|
|
|
|
Each SQL file, if given, is expected to contain valid SQL. The SQL files are
|
|
piped directly into the database after all of the models' table-creation
|
|
statements have been executed.
|
|
|
|
The SQL files are read by the ``sqlcustom``, ``sqlreset``, ``sqlall`` and
|
|
``reset`` commands in ``manage.py``. Refer to the `manage.py documentation`_
|
|
for more information.
|
|
|
|
Note that if you have multiple SQL data files, there's no guarantee of the
|
|
order in which they're executed. The only thing you can assume is that, by the
|
|
time your custom data files are executed, all the database tables already will
|
|
have been created.
|
|
|
|
.. _`manage.py documentation`: ../django-admin/#sqlcustom-appname-appname
|
|
|
|
Database-backend-specific SQL data
|
|
----------------------------------
|
|
|
|
There's also a hook for backend-specific SQL data. For example, you can have
|
|
separate initial-data files for PostgreSQL and MySQL. For each app, Django
|
|
looks for a file called ``<appname>/sql/<modelname>.<backend>.sql``, where
|
|
``<appname>`` is your app directory, ``<modelname>`` is the model's name in
|
|
lowercase and ``<backend>`` is the value of ``DATABASE_ENGINE`` in your
|
|
settings file (e.g., ``postgresql``, ``mysql``).
|
|
|
|
Backend-specific SQL data is executed before non-backend-specific SQL data. For
|
|
example, if your app contains the files ``sql/person.sql`` and
|
|
``sql/person.postgresql.sql`` and you're installing the app on PostgreSQL,
|
|
Django will execute the contents of ``sql/person.postgresql.sql`` first, then
|
|
``sql/person.sql``.
|