mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 10:59:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Massive reorganization of the docs. See the new docs online at http://docs.djangoproject.com/.

Browse source 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jacob Kaplan-Moss 2008-08-23 22:25:40 +00:00
parent b3688e8194
commit 97cb07c3a1
188 changed files with 19913 additions and 17059 deletions
Download patch file Download diff file Expand all files Collapse all files

902
docs/ref/models/fields.txt Normal file
View file

@ -0,0 +1,902 @@
.. _ref-models-fields:
=====================
Model field reference
=====================
.. module:: django.db.models.fields
:synopsis: Built-in field types.
This document contains all the gory details about all the `field options`_ and
`field types`_ Django's got to offer.
.. seealso::
If the built-in fields don't do the trick, you can easily :ref:`write your
own custom model fields <howto-custom-model-fields>`.
.. note::
Technically, these models are defined in :mod:`django.db.models.fields`, but
for convenience they're imported into :mod:`django.db.models`; the standard
convention is to use ``from django.db import models`` and refer to fields as
``models.<Foo>Field``.
.. _common-model-field-options:
Field options
=============
The following arguments are available to all field types. All are optional.
``null``
--------
.. attribute:: Field.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
:attr:`~Field.null` parameter only affects database storage (see
:attr:`~Field.blank`).
Avoid using :attr:`~Field.null` on string-based fields such as
:class:`CharField` and :class:`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``
---------
.. attribute:: Field.blank
If ``True``, the field is allowed to be blank. Default is ``False``.
Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is
purely database-related, whereas :attr:`~Field.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``
-----------
.. attribute:: Field.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 :attr:`~Field.choices` set, Django will add a
method to retrieve the human-readable name for the field's current value. See
:meth:`~django.db.models.Model.get_FOO_display` in the database API
documentation.
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 :attr:`~Field.choices` to be dynamic, you're probably better off using a
proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is
meant for static data that doesn't change much, if ever.
``core``
--------
.. attribute:: Field.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``
-------------
.. attribute:: Field.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``
------------
.. attribute:: Field.db_index
If ``True``, djadmin:`django-admin.py sqlindexes <sqlindexes>` will output a
``CREATE INDEX`` statement for this field.
``db_tablespace``
-----------------
.. attribute:: 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 :setting:`DEFAULT_INDEX_TABLESPACE`
setting, if set, or the :attr:`~Field.db_tablespace` of the model, if any. If
the backend doesn't support tablespaces, this option is ignored.
``default``
-----------
.. attribute:: Field.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``
------------
.. attribute:: Field.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``
-------------
.. attribute:: Field.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 :attr:`~Field.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``
---------------
.. attribute:: Field.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 an :class:`IntegerField` to hold the primary key, so you
don't need to set ``primary_key=True`` on any of your fields unless you want to
override the default primary-key behavior. For more, see
:ref:`automatic-primary-key-fields`.
``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
Only one primary key is allowed on an object.
``unique``
----------
.. attribute:: Field.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 :attr:`~Field.unique`
field, a :exc:`django.db.IntegrityError` will be raised by the model's
:meth:`~django.db.models.Model.save` method.
This options is valid on all field types except :class:`ManyToManyField`.
``unique_for_date``
-------------------
.. attribute:: Field.unique_for_date
Set this to the name of a :class:`DateField` or :class:`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``
--------------------
.. attribute:: Field.unique_for_month
Like :attr:`~Field.unique_for_date`, but requires the field to be unique with
respect to the month.
``unique_for_year``
-------------------
.. attribute:: Field.unique_for_year
Like :attr:`~Field.unique_for_date` and :attr:`~Field.unique_for_month`.
``validator_list``
------------------
.. attribute:: Field.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
:exc:`django.core.validators.ValidationError` for errors.
.. _model-field-types:
Field types
===========
.. currentmodule:: django.db.models
``AutoField``
-------------
.. class:: AutoField(**options)
An :class:`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 :ref:`automatic-primary-key-fields`.
``BooleanField``
----------------
.. class:: BooleanField(**options)
A true/false field.
The admin represents this as a checkbox.
``CharField``
-------------
.. class:: CharField(max_length=None, [**options])
A string field, for small- to large-sized strings.
For large amounts of text, use :class:`~django.db.models.TextField`.
The admin represents this as an ``<input type="text">`` (a single-line input).
:class:`CharField` has one extra required argument:
.. attribute:: CharField.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``
------------------------------
.. class:: CommaSeparatedIntegerField(max_length=None, [**options])
A field of integers separated by commas. As in :class:`CharField`, the
:attr:`~CharField.max_length` argument is required.
``DateField``
-------------
.. class:: DateField([auto_now=False, auto_now_add=False, **options])
A date field. Has a few extra optional arguments:
.. attribute:: DateField.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.
.. attribute:: DateField.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``
-----------------
.. class:: DateTimeField([auto_now=False, auto_now_add=False, **options])
A date and time field. Takes the same extra options as :class:`DateField`.
The admin represents this as two ``<input type="text">`` fields, with JavaScript
shortcuts.
``DecimalField``
----------------
**New in Django development version**
.. class:: DecimalField(max_digits=None, decimal_places=None, [**options])
A fixed-precision decimal number, represented in Python by a
:class:`~decimal.Decimal` instance. Has two **required** arguments:
.. attribute:: DecimalField.max_digits
The maximum number of digits allowed in the number
.. attribute:: DecimalField.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``
--------------
.. class:: EmailField([max_length=75, **options])
A :class:`CharField` that checks that the value is a valid e-mail address.
In Django 0.96, this doesn't accept :attr:`~CharField.max_length`; its
:class:`~CharField.max_length` is automatically set to 75. In the Django
development version, :class:`~CharField.max_length` is set to 75 by default, but
you can specify it to override default behavior.
``FileField``
-------------
.. class:: FileField(upload_to=None, [max_length=100, **options])
A file-upload field. Has one **required** argument:
.. attribute:: FileField.upload_to
A local filesystem path that will be appended to your :setting:`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).
**New in Django development version**
This may also be a callable, such as a function, which will be called to
obtain the upload path, including the filename. This callable must be
able to accept two arguments, and return a Unix-style path (with forward
slashes) to be passed along to the storage system. The two arguments that will
be passed are:
====================== ===============================================
Argument Description
====================== ===============================================
``instance`` An instance of the model where the
``FileField`` is defined. More specifically,
this is the particular instance where the
current file is being attached.
In most cases, this object will not have been
saved to the database yet, so if it uses the
default ``AutoField``, *it might not yet have a
value for its primary key field*.
``filename`` The filename that was originally given to the
file. This may or may not be taken into account
when determining the final destination path.
====================== ===============================================
Also has one optional argument:
.. attribute:: FileField.storage
**New in Django development version.**
Optional. A storage object, which handles the storage and retrieval of your
files. See :ref:`topics-files` for details on how to provide this object.
The admin represents this field as an ``<input type="file">`` (a file-upload
widget).
Using a :class:`FileField` or an :class:`ImageField` (see below) in a model
takes a few steps:
1. In your settings file, you'll need to define :setting:`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
:setting:`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 :class:`FileField` or :class:`ImageField` to your model, making
sure to define the :attr:`~FileField.upload_to` option to tell Django to
which subdirectory of :setting:`MEDIA_ROOT` it should upload files.
3. All that will be stored in your database is a path to the file
(relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
convenience ``get_<fieldname>_url`` function provided by Django. For
example, if your :class:`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 :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'``
part of :attr:`~FileField.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 ``File.name``, ``File.url``
and ``File.size`` attributes; see :ref:`topics-files`.
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.
**New in development version:** By default, :class:`FileField` instances are
created as ``varchar(100)`` columns in your database. As with other fields, you
can change the maximum length using the :attr:`~CharField.max_length` argument.
.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
``FilePathField``
-----------------
.. class:: FilePathField(path=None, [match=None, recursive=False, max_length=100, **options])
A :class:`CharField` whose choices are limited to the filenames in a certain
directory on the filesystem. Has three special arguments, of which the first is
**required**:
.. attribute:: FilePathField.path
Required. The absolute filesystem path to a directory from which this
:class:`FilePathField` should get its choices. Example: ``"/home/images"``.
.. attribute:: FilePathField.match
Optional. A regular expression, as a string, that :class:`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``.
.. attribute:: FilePathField.recursive
Optional. Either ``True`` or ``False``. Default is ``False``. Specifies
whether all subdirectories of :attr:`~FilePathField.path` should be included
Of course, these arguments can be used together.
The one potential gotcha is that :attr:`~FilePathField.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 :attr:`~FilePathField.match` applies to the base filename
(``foo.gif`` and ``bar.gif``).
**New in development version:** By default, :class:`FilePathField` instances are
created as ``varchar(100)`` columns in your database. As with other fields, you
can change the maximum length using the :attr:`~CharField.max_length` argument.
``FloatField``
--------------
.. class:: FloatField([**options])
**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 :class:`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``
--------------
.. class:: ImageField(upload_to-None, [height_field=None, width_field=None, max_length=100, **options])
Like :class:`FileField`, but validates that the uploaded object is a valid
image. Has two extra optional arguments:
.. attribute:: ImageField.height_field
Name of a model field which will be auto-populated with the height of the
image each time the model instance is saved.
.. attribute:: ImageField.width_field`
Name of a model field which will be auto-populated with the width of the
image each time the model instance is saved.
In addition to the special attributes that are available for :class:`FileField`,
an :class:`ImageField` also has ``File.height`` and ``File.width`` attributes.
See :ref:`topics-files`.
Requires the `Python Imaging Library`_.
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
**New in development version:** By default, :class:`ImageField` instances are
created as ``varchar(100)`` columns in your database. As with other fields, you
can change the maximum length using the :attr:`~CharField.max_length` argument.
``IntegerField``
----------------
.. class:: IntegerField([**options])
An integer. The admin represents this as an ``<input type="text">`` (a
single-line input).
``IPAddressField``
------------------
.. class:: IPAddressField([**options])
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``
--------------------
.. class:: NullBooleanField([**options])
Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use
this instead of a :class:`BooleanField` with ``null=True``. The admin represents
this as a ``<select>`` box with "Unknown", "Yes" and "No" choices.
``PhoneNumberField``
--------------------
.. class:: PhoneNumberField([**options])
A :class:`CharField` that checks that the value is a valid U.S.A.-style phone
number (in the format ``XXX-XXX-XXXX``).
``PositiveIntegerField``
------------------------
.. class:: PositiveIntegerField([**options])
Like an :class:`IntegerField`, but must be positive.
``PositiveSmallIntegerField``
-----------------------------
.. class:: PositiveIntegerField([**options])
Like a :class:`PositiveIntegerField`, but only allows values under a certain
(database-dependent) point.
``SlugField``
-------------
.. class:: SlugField([max_length=50, **options])
:term:`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 :attr:`~CharField.max_length`. If
:attr:`~CharField.max_length` is not specified, Django will use a default length
of 50.
Implies setting :attr:`Field.db_index` to ``True``.
``SmallIntegerField``
---------------------
.. class:: SmallIntegerField([**options])
Like an :class:`IntegerField`, but only allows values under a certain
(database-dependent) point.
``TextField``
-------------
.. class:: TextField([**options])
A large text field. The admin represents this as a ``<textarea>`` (a multi-line
input).
``TimeField``
-------------
.. class:: TimeField([auto_now=False, auto_now_add=False, **options])
A time. Accepts the same auto-population options as :class:`DateField` and
:class:`DateTimeField`. The admin represents this as an ``<input type="text">``
with some JavaScript shortcuts.
``URLField``
------------
.. class:: URLField([verify_exists=True, max_length=200, **options])
A :class:`CharField` for a URL. Has one extra optional argument:
.. attribute:: URLField.verify_exists
If ``True`` (the 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).
Like all ::class:`CharField` subclasses, :class:`URLField` takes the optional
:attr:`~CharField.max_length`argument. If you don't specify
:attr:`~CharField.max_length`, a default of 200 is used.
``USStateField``
----------------
.. class:: USStateField([**options])
A two-letter U.S. state abbreviation. The admin represents this as an ``<input
type="text">`` (a single-line input).
``XMLField``
------------
.. class:: XMLField(schema_path=None, [**options])
A :class:`TextField` that checks that the value is valid XML that matches a
given schema. Takes one required argument:
.. attribute:: schema_path
The filesystem path to a RelaxNG_ schema against which to validate the
field.
.. _RelaxNG: http://www.relaxng.org/
Relationship fields
===================
.. module:: django.db.models.fields.related
:synopsis: Related field types
.. currentmodule:: django.db.models
Django also defines a set of fields that represent relations.
.. _ref-foreignkey:
``ForeignKey``
--------------
.. class:: ForeignKey(othermodel, [**options])
A many-to-one relationship. Requires a positional argument: the class to which
the model is related.
.. _recursive-relationships:
To create a recursive relationship -- an object that has a many-to-one
relationship with itself -- use ``models.ForeignKey('self')``.
.. _lazy-relationships:
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 :attr:`~Field.db_column`) 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.
.. _foreign-key-arguments:
:class:`ForeignKey` accepts an extra set of arguments -- all optional -- that
define the details of how the relation works.
.. attribute:: ForeignKey.limit_choices_to
A dictionary of lookup arguments and values (see :ref:`topics-db-queries`)
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 :class:`~django.db.models.Q`
object (an object with a :meth:`get_sql` method) for more complex queries.
``limit_choices_to`` has no effect on the inline FormSets that are created
to display related objects in the admin.
.. attribute:: ForeignKey.related_name
The name to use for the relation from the related object back to this one.
See the :ref:`related objects documentation <backwards-related-objects>` for
a full explanation and example.
.. attribute:: ForeignKey.to_field
The field on the related object that the relation is to. By default, Django
uses the primary key of the related object.
.. _ref-manytomany:
``ManyToManyField``
-------------------
.. class:: ManyToManyField(othermodel, [**options])
A many-to-many relationship. Requires a positional argument: the class to which
the model is related. This works exactly the same as it does for
:class:`ForeignKey`, including all the options regarding :ref:`recursive
<recursive-relationships>` and :ref:`lazy <lazy-relationships>` relationships.
Behind the scenes, Django creates an intermediary join table to represent the
many-to-many relationship. By default, this table name is generated using the
names of the two tables being joined. Since some databases don't support table
names above a certain length (often 32 characters), these table names will be
automatically truncated to 32 characters and a uniqueness hash will be used.
This means you might see table names like ``author_books_9cdf4``; this is
perfectly normal. You can manually provide the name of the join table using
the :attr:`~ManyToManyField.db_table` option.
.. _manytomany-arguments:
:class:`ManyToManyField` accepts an extra set of arguments -- all optional --
that control how the relationship functions.
.. attribute:: ManyToManyField.related_name
Same as :attr:`ForeignKey.related_name`.
.. attribute:: ManyToManyFields.limit_choices_to
Same as :attr:`ForeignKey.limit_choices_to`.
``limit_choices_to`` has no effect when used on a ``ManyToManyField`` with
an intermediate table.
.. attribute:: ManyToManyFields.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
:class:`ManyToManyField` on itself, and as a result, it doesn't add a
``person_set`` attribute to the ``Person`` class. Instead, the
:class:`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 many-to-many relationships with ``self``, set
:attr:`~ManyToManyField.symmetrical` to ``False``. This will force Django to
add the descriptor for the reverse relationship, allowing
:class:`ManyToManyField` relationships to be non-symmetrical.
.. attribute:: ManyToManyField.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.
``OneToOneField``
-----------------
.. class:: OneToOneField(othermodel, [**options])
The semantics of one-to-one relationships will be changing soon, so we don't
recommend you use them. If that doesn't scare you away, however,
:class:`OneToOneField` takes the same options that :class:`ForeignKey` does,
except for the various :attr:`~ForeignKey.edit_inline`-related options.

15
docs/ref/models/index.txt Normal file
View file

@ -0,0 +1,15 @@
.. _ref-models-index:
Models
======
Model API reference. For introductory material, see :ref:`topics-db-models`.
.. toctree::
:maxdepth: 1
fields
relations
options
instances
querysets

430
docs/ref/models/instances.txt Normal file
View file

@ -0,0 +1,430 @@
.. _ref-models-instances:
========================
Model instance reference
========================
.. currentmodule:: django.db.models
This document describes the details of the ``Model`` API. It builds on the
material presented in the :ref:`model <topics-db-models>` and `database query
<topics-db-queries>` guides, so you'll probably want to read and understand
those documents before reading this one.
Throughout this reference we'll use the :ref:`example weblog models
<queryset-model-example>` presented in the :ref:`database query guide
<topics-db-queries>`.
Creating objects
================
To create a new instance of a model, just instantiate it like any other Python class:
.. class:: Model(**kwargs)
The keyword arguments to are simply the names of the fields you've defined on
your model. Note that instantiating a model in no way touches your database; for
that, you need to ``save()``.
Saving objects
==============
To save an object back to the database, call ``save()``:
.. method:: Model.save([raw=False])
Of course, there's some subtleties; see the sections below.
Auto-incrementing primary keys
------------------------------
If a model has an ``AutoField`` -- an auto-incrementing primary key -- then
that auto-incremented value will be calculated and saved as an attribute on
your object the first time you call ``save()``::
>>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b2.id # Returns None, because b doesn't have an ID yet.
>>> b2.save()
>>> b2.id # Returns the ID of your new object.
There's no way to tell what the value of an ID will be before you call
``save()``, because that value is calculated by your database, not by Django.
(For convenience, each model has an ``AutoField`` named ``id`` by default
unless you explicitly specify ``primary_key=True`` on a field. See the
documentation for ``AutoField`` for more details.
The ``pk`` property
~~~~~~~~~~~~~~~~~~~
**New in Django development version**
.. attribute:: Model.pk
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.
Explicitly specifying auto-primary-key values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If a model has an ``AutoField`` but you want to define a new object's ID
explicitly when saving, just define it explicitly before saving, rather than
relying on the auto-assignment of the ID::
>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')
>>> b3.id # Returns 3.
>>> b3.save()
>>> b3.id # Returns 3.
If you assign auto-primary-key values manually, make sure not to use an
already-existing primary-key value! If you create a new object with an explicit
primary-key value that already exists in the database, Django will assume you're
changing the existing record rather than creating a new one.
Given the above ``'Cheddar Talk'`` blog example, this example would override the
previous record in the database::
b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.')
b4.save() # Overrides the previous blog with ID=3!
See `How Django knows to UPDATE vs. INSERT`_, below, for the reason this
happens.
Explicitly specifying auto-primary-key values is mostly useful for bulk-saving
objects, when you're confident you won't have primary-key collision.
What happens when you save?
---------------------------
When you save an object, Django performs the following steps:
1. **Emit a ``pre_save`` signal.** This provides a notification that
an object is about to be saved. You can register a listener that
will be invoked whenever this signal is emitted. (These signals are
not yet documented.)
2. **Pre-process the data.** Each field on the object is asked to
perform any automated data modification that the field may need
to perform.
Most fields do *no* pre-processing -- the field data is kept as-is.
Pre-processing is only used on fields that have special behavior.
For example, if your model has a ``DateField`` with ``auto_now=True``,
the pre-save phase will alter the data in the object to ensure that
the date field contains the current date stamp. (Our documentation
doesn't yet include a list of all the fields with this "special
behavior.")
3. **Prepare the data for the database.** Each field is asked to provide
its current value in a data type that can be written to the database.
Most fields require *no* data preparation. Simple data types, such as
integers and strings, are 'ready to write' as a Python object. However,
more complex data types often require some modification.
For example, ``DateFields`` use a Python ``datetime`` object to store
data. Databases don't store ``datetime`` objects, so the field value
must be converted into an ISO-compliant date string for insertion
into the database.
4. **Insert the data into the database.** The pre-processed, prepared
data is then composed into an SQL statement for insertion into the
database.
5. **Emit a ``post_save`` signal.** As with the ``pre_save`` signal, this
is used to provide notification that an object has been successfully
saved. (These signals are not yet documented.)
Raw saves
~~~~~~~~~
**New in Django development version**
The pre-processing step (#2 in the previous section) is useful, but it modifies
the data stored in a field. This can cause problems if you're relying upon the
data you provide being used as-is.
For example, if you're setting up conditions for a test, you'll want the test
conditions to be repeatable. If pre-processing is performed, the data used
to specify test conditions may be modified, changing the conditions for the
test each time the test is run.
In cases such as this, you need to prevent pre-processing from being performed
when you save an object. To do this, you can invoke a **raw save** by passing
``raw=True`` as an argument to the ``save()`` method::
b4.save(raw=True) # Save object, but do no pre-processing
A raw save skips the usual data pre-processing that is performed during the
save. All other steps in the save (pre-save signal, data preparation, data
insertion, and post-save signal) are performed as normal.
.. admonition:: When to use a raw save
Generally speaking, you shouldn't need to use a raw save. Disabling field
pre-processing is an extraordinary measure that should only be required
in extraordinary circumstances, such as setting up reliable test
conditions.
How Django knows to UPDATE vs. INSERT
-------------------------------------
You may have noticed Django database objects use the same ``save()`` method
for creating and changing objects. Django abstracts the need to use ``INSERT``
or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django
follows this algorithm:
* If the object's primary key attribute is set to a value that evaluates to
``True`` (i.e., a value other than ``None`` or the empty string), Django
executes a ``SELECT`` query to determine whether a record with the given
primary key already exists.
* If the record with the given primary key does already exist, Django
executes an ``UPDATE`` query.
* If the object's primary key attribute is *not* set, or if it's set but a
record doesn't exist, Django executes an ``INSERT``.
The one gotcha here is that you should be careful not to specify a primary-key
value explicitly when saving new objects, if you cannot guarantee the
primary-key value is unused. For more on this nuance, see `Explicitly specifying
auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below.
Forcing an INSERT or UPDATE
~~~~~~~~~~~~~~~~~~~~~~~~~~~
**New in Django development version**
In some rare circumstances, it's necessary to be able to force the ``save()``
method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``.
Or vice-versa: update, if possible, but not insert a new row. In these cases
you can pass the ``force_insert=True`` or ``force_update=True`` parameters to
the ``save()`` method. Passing both parameters is an error, since you cannot
both insert *and* update at the same time.
It should be very rare that you'll need to use these parameters. Django will
almost always do the right thing and trying to override that will lead to
errors that are difficult to track down. This feature is for advanced use
only.
.. _model-instance-methods:
Other model instance methods
============================
A few object methods have special purposes.
``__str__``
-----------
.. method:: Model.__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__``
---------------
.. method:: Model.__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``
--------------------
.. method:: Model.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 :ref:`syndication feed
framework <ref-contrib-syndication>`, use ``get_absolute_url()`` as a
convenience to reward people who've defined the method.
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:
.. function:: django.db.models.permalink()
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 import models
@models.permalink
def get_absolute_url(self):
return ('people.views.details', [str(self.id)])
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::
@models.permalink
def get_absolute_url(self):
return ('archive_view', (), {
'year': self.created.year,
'month': self.created.month,
'day': self.created.day})
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 :ref:`URL dispatch documentation
<topics-http-urls>`.
Extra instance methods
======================
In addition to ``save()``, ``delete()``, a model object might get any or all
of the following methods:
get_FOO_display()
-----------------
For every field that has ``choices`` set, the object will have a
``get_FOO_display()`` method, where ``FOO`` is the name of the field. This
method returns the "human-readable" value of the field. For example, in the
following model::
GENDER_CHOICES = (
('M', 'Male'),
('F', 'Female'),
)
class Person(models.Model):
name = models.CharField(max_length=20)
gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
>>> p = Person(name='John', gender='M')
>>> p.save()
>>> p.gender
'M'
>>> p.get_gender_display()
'Male'
get_next_by_FOO(\**kwargs) and get_previous_by_FOO(\**kwargs)
-------------------------------------------------------------
For every ``DateField`` and ``DateTimeField`` that does not have ``null=True``,
the object will have ``get_next_by_FOO()`` and ``get_previous_by_FOO()``
methods, where ``FOO`` is the name of the field. This returns the next and
previous object with respect to the date field, raising the appropriate
``DoesNotExist`` exception when appropriate.
Both methods accept optional keyword arguments, which should be in the format
described in :ref:`Field lookups <field-lookups>`.
Note that in the case of identical date values, these methods will use the ID
as a fallback check. This guarantees that no records are skipped or duplicated.

175
docs/ref/models/options.txt Normal file
View file

@ -0,0 +1,175 @@
.. _ref-models-options:
======================
Model ``Meta`` options
======================
This document explains all the possible :ref:`metadata options <meta-options>` that you can give your model in its internal ``class Meta``.
Available ``Meta`` options
==========================
.. currentmodule:: django.db.models
``db_table``
------------
.. attribute:: Options.db_table
The name of the database table to use for the model::
db_table = 'music_album'
.. _table-names:
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``.
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``
-----------------
.. attribute:: Options.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``
-----------------
.. attribute:: Options.get_latest_by
The name of a :class:`DateField` or :class:`DateTimeField` in the model. This
specifies the default field to use in your model :class:`Manager`'s
:class:`~QuerySet.latest` method.
Example::
get_latest_by = "order_date"
See the docs for :meth:`~django.db.models.QuerySet.latest` for more.
``order_with_respect_to``
-------------------------
.. attribute:: Options.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``
------------
.. attribute:: Options.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.
.. note::
Regardless of how many fields are in :attr:`~Options.ordering`, the admin
site uses only the first field.
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']
``permissions``
---------------
.. attribute:: Options.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``
-------------------
.. attribute:: Options.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).
**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``
----------------
.. attribute:: Options.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``
-----------------------
.. attribute:: Options.verbose_name_plural
The plural name for the object::
verbose_name_plural = "stories"
If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.

1060
docs/ref/models/querysets.txt Normal file
View file

File diff suppressed because it is too large Load diff

77
docs/ref/models/relations.txt Normal file
View file

@ -0,0 +1,77 @@
.. _ref-models-relations:
=========================
Related objects reference
=========================
Extra methods on managers when used in a ForeignKey context
===========================================================
.. currentmodule:: django.db.models
.. method:: QuerySet.add(obj1, [obj2, ...])
Adds the specified model objects to the related object set.
Example::
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.add(e) # Associates Entry e with Blog b.
.. method:: QuerySet.create(**kwargs)`
Creates a new object, saves it and puts it in the related object set.
Returns the newly created object::
>>> b = Blog.objects.get(id=1)
>>> e = b.entry_set.create(
... headline='Hello',
... body_text='Hi',
... pub_date=datetime.date(2005, 1, 1)
... )
# No need to call e.save() at this point -- it's already been saved.
This is equivalent to (but much simpler than)::
>>> b = Blog.objects.get(id=1)
>>> e = Entry(
.... blog=b,
.... headline='Hello',
.... body_text='Hi',
.... pub_date=datetime.date(2005, 1, 1)
.... )
>>> e.save()
Note that there's no need to specify the keyword argument of the model that
defines the relationship. In the above example, we don't pass the parameter
``blog`` to ``create()``. Django figures out that the new ``Entry`` object's
``blog`` field should be set to ``b``.
.. method:: QuerySet.remove(obj1, [obj2, ...])
Removes the specified model objects from the related object set::
>>> b = Blog.objects.get(id=1)
>>> e = Entry.objects.get(id=234)
>>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
In order to prevent database inconsistency, this method only exists on
``ForeignKey`` objects where ``null=True``. If the related field can't be
set to ``None`` (``NULL``), then an object can't be removed from a relation
without being added to another. In the above example, removing ``e`` from
``b.entry_set()`` is equivalent to doing ``e.blog = None``, and because the
``blog`` ``ForeignKey`` doesn't have ``null=True``, this is invalid.
.. method:: QuerySet.clear()
Removes all objects from the related object set::
>>> b = Blog.objects.get(id=1)
>>> b.entry_set.clear()
Note this doesn't delete the related objects -- it just disassociates them.
Just like ``remove()``, ``clear()`` is only available on ``ForeignKey``s
where ``null=True``.