py_tasks_melange: comparison thirdparty/google_appengine/lib/django/docs/model-api.txt

equal deleted inserted replaced

-:261778de26ff
+:620f9b141567
+===============
+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``.
+* Metadata used for Django's admin site goes into an inner class named
+``Admin``.
+* 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: http://www.djangoproject.com/documentation/db_api/
+.. _official repository of model examples: http://www.djangoproject.com/documentation/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(maxlength=30)
+last_name = models.CharField(maxlength=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
+overriden. 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: http://www.djangoproject.com/documentation/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(maxlength=50)
+last_name = models.CharField(maxlength=50)
+instrument = models.CharField(maxlength=100)
+class Album(models.Model):
+artist = models.ForeignKey(Musician)
+name = models.CharField(maxlength=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
+manipulators.
+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, ``maxlength``, the maximum length
+(in characters) of the field. The maxlength is enforced at the database level
+and in Django's validation.
+``CommaSeparatedIntegerField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A field of integers separated by commas. As in ``CharField``, the ``maxlength``
+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."
+``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.
+``EmailField``
+~~~~~~~~~~~~~~
+A ``CharField`` that checks that the value is a valid e-mail address.
+This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to
+75.
+``FileField``
+~~~~~~~~~~~~~
+A file-upload field.
+Has an extra required argument, ``upload_to``, a local filesystem path to
+which files should be upload. 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 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``.
+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
+``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``).
+``FloatField``
+~~~~~~~~~~~~~~
+A floating-point number. 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.FloatField(..., max_digits=5, decimal_places=2)
+And to store numbers up to approximately one billion with a resolution of 10
+decimal places::
+models.FloatField(..., max_digits=19, decimal_places=10)
+The admin represents this as an ``<input type="text">`` (a single-line input).
+``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.
+Requires the `Python Imaging Library`_.
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+``IntegerField``
+~~~~~~~~~~~~~~~~
+An integer.
+The admin represents this as an ``<input type="text">`` (a single-line input).
+``IPAddressField``
+~~~~~~~~~~~~~~~~~~
+An IP address, in string format (i.e. "24.124.1.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 ``maxlength``. If ``maxlength`` is
+not specified, Django will use a default length of 50.
+Implies ``db_index=True``.
+Accepts an extra option, ``prepopulate_from``, which is a list of fields
+from which to auto-populate the slug, via JavaScript, in the object's admin
+form::
+models.SlugField(prepopulate_from=("pre_name", "name"))
+``prepopulate_from`` doesn't accept DateTimeFields.
+The admin represents ``SlugField`` as an ``<input type="text">`` (a
+single-line input).
+``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).
+``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`` -- so use ``null=True`` for non-string fields such as integers,
+booleans and dates.
+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``.
+``blank``
+~~~~~~~~~
+If ``True``, the field is allowed to be blank.
+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(maxlength=1, choices=GENDER_CHOICES)
+or outside your model class altogether::
+GENDER_CHOICES = (
+('M', 'Male'),
+('F', 'Female'),
+)
+class Foo(models.Model):
+gender = models.CharField(maxlength=1, choices=GENDER_CHOICES)
+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.
+``default``
+~~~~~~~~~~~
+The default value for the field.
+``editable``
+~~~~~~~~~~~~
+If ``False``, the field will not be editable in the admin or via form
+processing using the object's ``AddManipulator`` or ``ChangeManipulator``
+classes. 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.
+``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 ``blank=False``, ``null=False`` and
+``unique=True``. Only one primary key is allowed on an object.
+``radio_admin``
+~~~~~~~~~~~~~~~
+By default, Django's admin uses a select-box interface (<select>) for
+fields that are ``ForeignKey`` or have ``choices`` set. If ``radio_admin``
+is set to ``True``, Django will use a radio-button interface instead.
+Don't use this for a field unless it's a ``ForeignKey`` or has ``choices``
+set.
+``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.
+``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: http://www.djangoproject.com/documentation/forms/#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", maxlength=30)
+In this example, the verbose name is ``"first name"``::
+first_name = models.CharField(maxlength=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 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.
+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: http://www.djangoproject.com/documentation/models/many_to_one/
+``ForeignKey`` fields take a number of extra arguments for defining how the
+relationship should work. All are optional:
+=======================  ============================================================
+Argument                 Description
+=======================  ============================================================
+``edit_inline``          If not ``False``, this related object is edited
+"inline" on the related object's page. This means
+that the object will not have its own admin
+interface. Use either ``models.TABULAR`` or ``models.STACKED``,
+which, respectively, designate whether the inline-editable
+objects are displayed as a table or as a "stack" of
+fieldsets.
+``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 ``models.LazyDate`` to limit choices of objects
+by date. For example::
+limit_choices_to = {'pub_date__lte': models.LazyDate()}
+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``.
+``max_num_in_admin``     For inline-edited objects, this is the maximum
+number of related objects to display in the admin.
+Thus, if a pizza could only have up to 10
+toppings, ``max_num_in_admin=10`` would ensure
+that a user never enters more than 10 toppings.
+Note that this doesn't ensure more than 10 related
+toppings ever get created. It simply controls the
+admin interface; it doesn't enforce things at the
+Python API level or database level.
+``min_num_in_admin``     The minimum number of related objects displayed in
+the admin. Normally, at the creation stage,
+``num_in_admin`` inline objects are shown, and at
+the edit stage ``num_extra_on_change`` blank
+objects are shown in addition to all pre-existing
+related objects.  However, no fewer than
+``min_num_in_admin`` related objects will ever be
+displayed.
+``num_extra_on_change``  The number of extra blank related-object fields to
+show at the change stage.
+``num_in_admin``         The default number of inline objects to display
+on the object page at the add stage.
+``raw_id_admin``         Only display a field for the integer to be entered
+instead of a drop-down menu. This is useful when
+related to an object type that will have too many
+rows to make a select box practical.
+Not used 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.
+``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`: http://www.djangoproject.com/documentation/db_api/
+.. _related objects documentation: http://www.djangoproject.com/documentation/db_api/#related-objects
+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: http://www.djangoproject.com/documentation/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.
+``filter_interface``     Use a nifty unobtrusive Javascript "filter" interface
+instead of the usability-challenged ``<select multiple>``
+in the admin form for this object. The value should be
+``models.HORIZONTAL`` or ``models.VERTICAL`` (i.e.
+should the interface be stacked horizontally or
+vertically).
+``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.
+=======================  ============================================================
+One-to-one relationships
+~~~~~~~~~~~~~~~~~~~~~~~~
+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, keep reading.
+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.
+This ``OneToOneField`` will actually replace the primary key ``id`` field
+(since one-to-one relations share the same primary key), and will be displayed
+as a read-only field when you edit an object in the admin interface:
+See the `One-to-one relationship model example`_ for a full example.
+.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/
+Meta options
+============
+Give your model metadata by using an inner ``class Meta``, like so::
+class Foo(models.Model):
+bar = models.CharField(maxlength=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.
+``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.
+``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(): http://www.djangoproject.com/documentation/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: http://www.djangoproject.com/documentation/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).
+``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``.
+Admin options
+=============
+If you want your model to be visible to Django's admin site, give your model an
+inner ``"class Admin"``, like so::
+class Person(models.Model):
+first_name = models.CharField(maxlength=30)
+last_name = models.CharField(maxlength=30)
+class Admin:
+# Admin options go here
+pass
+The ``Admin`` class tells Django how to display the model in the admin site.
+Here's a list of all possible ``Admin`` options. None of these options are
+required. To use an admin interface without specifying any options, use
+``pass``, like so::
+class Admin:
+pass
+Adding ``class Admin`` to a model is completely optional.
+``date_hierarchy``
+------------------
+Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
+your model, and the change list page will include a date-based drilldown
+navigation by that field.
+Example::
+date_hierarchy = 'pub_date'
+``fields``
+----------
+Set ``fields`` to control the layout of admin "add" and "change" pages.
+``fields`` is a list of two-tuples, in which each two-tuple represents a
+``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of the
+form.)
+The two-tuples are in the format ``(name, field_options)``, where ``name`` is a
+string representing the title of the fieldset and ``field_options`` is a
+dictionary of information about the fieldset, including a list of fields to be
+displayed in it.
+A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
+class Admin:
+fields = (
+(None, {
+'fields': ('url', 'title', 'content', 'sites')
+}),
+('Advanced options', {
+'classes': 'collapse',
+'fields' : ('enable_comments', 'registration_required', 'template_name')
+}),
+)
+This results in an admin page that looks like:
+.. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
+If ``fields`` isn't given, Django will default to displaying each field that
+isn't an ``AutoField`` and has ``editable=True``, in a single fieldset, in
+the same order as the fields are defined in the model.
+The ``field_options`` dictionary can have the following keys:
+``fields``
+~~~~~~~~~~
+A tuple of field names to display in this fieldset. This key is required.
+Example::
+{
+'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
+}
+To display multiple fields on the same line, wrap those fields in their own
+tuple. In this example, the ``first_name`` and ``last_name`` fields will
+display on the same line::
+{
+'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
+}
+``classes``
+~~~~~~~~~~~
+A string containing extra CSS classes to apply to the fieldset.
+Example::
+{
+'classes': 'wide',
+}
+Apply multiple classes by separating them with spaces. Example::
+{
+'classes': 'wide extrapretty',
+}
+Two useful classes defined by the default admin-site stylesheet are
+``collapse`` and ``wide``. Fieldsets with the ``collapse`` style will be
+initially collapsed in the admin and replaced with a small "click to expand"
+link. Fieldsets with the ``wide`` style will be given extra horizontal space.
+``description``
+~~~~~~~~~~~~~~~
+A string of optional extra text to be displayed at the top of each fieldset,
+under the heading of the fieldset. It's used verbatim, so you can use any HTML
+and you must escape any special HTML characters (such as ampersands) yourself.
+``js``
+------
+A list of strings representing URLs of JavaScript files to link into the admin
+screen via ``<script src="">`` tags. This can be used to tweak a given type of
+admin page in JavaScript or to provide "quick links" to fill in default values
+for certain fields.
+If you use relative URLs -- URLs that don't start with ``http://`` or ``/`` --
+then the admin site will automatically prefix these links with
+``settings.ADMIN_MEDIA_PREFIX``.
+``list_display``
+----------------
+Set ``list_display`` to control which fields are displayed on the change list
+page of the admin.
+Example::
+list_display = ('first_name', 'last_name')
+If you don't set ``list_display``, the admin site will display a single column
+that displays the ``__str__()`` representation of each object.
+A few special cases to note about ``list_display``:
+* If the field is a ``ForeignKey``, Django will display the ``__str__()``
+of the related object.
+* ``ManyToManyField`` fields aren't supported, because that would entail
+executing a separate SQL statement for each row in the table. If you
+want to do this nonetheless, give your model a custom method, and add
+that method's name to ``list_display``. (See below for more on custom
+methods in ``list_display``.)
+* If the field is a ``BooleanField`` or ``NullBooleanField``, Django will
+display a pretty "on" or "off" icon instead of ``True`` or ``False``.
+* If the string given is a method of the model, Django will call it and
+display the output. This method should have a ``short_description``
+function attribute, for use as the header for the field.
+Here's a full example model::
+class Person(models.Model):
+name = models.CharField(maxlength=50)
+birthday = models.DateField()
+class Admin:
+list_display = ('name', 'decade_born_in')
+def decade_born_in(self):
+return self.birthday.strftime('%Y')[:3] + "0's"
+decade_born_in.short_description = 'Birth decade'
+* If the string given is a method of the model, Django will HTML-escape the
+output by default. If you'd rather not escape the output of the method,
+give the method an ``allow_tags`` attribute whose value is ``True``.
+Here's a full example model::
+class Person(models.Model):
+first_name = models.CharField(maxlength=50)
+last_name = models.CharField(maxlength=50)
+color_code = models.CharField(maxlength=6)
+class Admin:
+list_display = ('first_name', 'last_name', 'colored_name')
+def colored_name(self):
+return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
+colored_name.allow_tags = True
+* If the string given is a method of the model that returns True or False
+Django will display a pretty "on" or "off" icon if you give the method a
+``boolean`` attribute whose value is ``True``.
+Here's a full example model::
+class Person(models.Model):
+first_name = models.CharField(maxlength=50)
+birthday = models.DateField()
+class Admin:
+list_display = ('name', 'born_in_fifties')
+def born_in_fifties(self):
+return self.birthday.strftime('%Y')[:3] == 5
+born_in_fifties.boolean = True
+* The ``__str__()`` method is just as valid in ``list_display`` as any
+other model method, so it's perfectly OK to do this::
+list_display = ('__str__', 'some_other_field')
+* Usually, elements of ``list_display`` that aren't actual database fields
+can't be used in sorting (because Django does all the sorting at the
+database level).
+However, if an element of ``list_display`` represents a certain database
+field, you can indicate this fact by setting the ``admin_order_field``
+attribute of the item.
+For example::
+class Person(models.Model):
+first_name = models.CharField(maxlength=50)
+color_code = models.CharField(maxlength=6)
+class Admin:
+list_display = ('first_name', 'colored_first_name')
+def colored_first_name(self):
+return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
+colored_first_name.allow_tags = True
+colored_first_name.admin_order_field = 'first_name'
+The above will tell Django to order by the ``first_name`` field when
+trying to sort by ``colored_first_name`` in the admin.
+``list_display_links``
+----------------------
+Set ``list_display_links`` to control which fields in ``list_display`` should
+be linked to the "change" page for an object.
+By default, the change list page will link the first column -- the first field
+specified in ``list_display`` -- to the change page for each item. But
+``list_display_links`` lets you change which columns are linked. Set
+``list_display_links`` to a list or tuple of field names (in the same format as
+``list_display``) to link.
+``list_display_links`` can specify one or many field names. As long as the
+field names appear in ``list_display``, Django doesn't care how many (or how
+few) fields are linked. The only requirement is: If you want to use
+``list_display_links``, you must define ``list_display``.
+In this example, the ``first_name`` and ``last_name`` fields will be linked on
+the change list page::
+class Admin:
+list_display = ('first_name', 'last_name', 'birthday')
+list_display_links = ('first_name', 'last_name')
+Finally, note that in order to use ``list_display_links``, you must define
+``list_display``, too.
+``list_filter``
+---------------
+Set ``list_filter`` to activate filters in the right sidebar of the change list
+page of the admin. This should be a list of field names, and each specified
+field should be either a ``BooleanField``, ``DateField``, ``DateTimeField``
+or ``ForeignKey``.
+This example, taken from the ``django.contrib.auth.models.User`` model, shows
+how both ``list_display`` and ``list_filter`` work::
+class Admin:
+list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
+list_filter = ('is_staff', 'is_superuser')
+The above code results in an admin change list page that looks like this:
+.. image:: http://media.djangoproject.com/img/doc/users_changelist.png
+(This example also has ``search_fields`` defined. See below.)
+``list_per_page``
+-----------------
+Set ``list_per_page`` to control how many items appear on each paginated admin
+change list page. By default, this is set to ``100``.
+``list_select_related``
+-----------------------
+Set ``list_select_related`` to tell Django to use ``select_related()`` in
+retrieving the list of objects on the admin change list page. This can save you
+a bunch of database queries.
+The value should be either ``True`` or ``False``. Default is ``False``.
+Note that Django will use ``select_related()``, regardless of this setting,
+if one of the ``list_display`` fields is a ``ForeignKey``.
+For more on ``select_related()``, see `the select_related() docs`_.
+.. _the select_related() docs: http://www.djangoproject.com/documentation/db_api/#select-related
+``ordering``
+------------
+Set ``ordering`` to specify how objects on the admin change list page should be
+ordered. This should be a list or tuple in the same format as a model's
+``ordering`` parameter.
+If this isn't provided, the Django admin will use the model's default ordering.
+``save_as``
+-----------
+Set ``save_as`` to enable a "save as" feature on admin change forms.
+Normally, objects have three save options: "Save", "Save and continue editing"
+and "Save and add another". If ``save_as`` is ``True``, "Save and add another"
+will be replaced by a "Save as" button.
+"Save as" means the object will be saved as a new object (with a new ID),
+rather than the old object.
+By default, ``save_as`` is set to ``False``.
+``save_on_top``
+---------------
+Set ``save_on_top`` to add save buttons across the top of your admin change
+forms.
+Normally, the save buttons appear only at the bottom of the forms. If you set
+``save_on_top``, the buttons will appear both on the top and the bottom.
+By default, ``save_on_top`` is set to ``False``.
+``search_fields``
+-----------------
+Set ``search_fields`` to enable a search box on the admin change list page.
+This should be set to a list of field names that will be searched whenever
+somebody submits a search query in that text box.
+These fields should be some kind of text field, such as ``CharField`` or
+``TextField``. You can also perform a related lookup on a ``ForeignKey`` with
+the lookup API "follow" notation::
+search_fields = ['foreign_key__related_fieldname']
+When somebody does a search in the admin search box, Django splits the search
+query into words and returns all objects that contain each of the words, case
+insensitive, where each word must be in at least one of ``search_fields``. For
+example, if ``search_fields`` is set to ``['first_name', 'last_name']`` and a
+user searches for ``john lennon``, Django will do the equivalent of this SQL
+``WHERE`` clause::
+WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
+AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')
+For faster and/or more restrictive searches, prefix the field name
+with an operator:
+``^``
+Matches the beginning of the field. For example, if ``search_fields`` is
+set to ``['^first_name', '^last_name']`` and a user searches for
+``john lennon``, Django will do the equivalent of this SQL ``WHERE``
+clause::
+WHERE (first_name ILIKE 'john%' OR last_name ILIKE 'john%')
+AND (first_name ILIKE 'lennon%' OR last_name ILIKE 'lennon%')
+This query is more efficient than the normal ``'%john%'`` query, because
+the database only needs to check the beginning of a column's data, rather
+than seeking through the entire column's data. Plus, if the column has an
+index on it, some databases may be able to use the index for this query,
+even though it's a ``LIKE`` query.
+``=``
+Matches exactly, case-insensitive. For example, if
+``search_fields`` is set to ``['=first_name', '=last_name']`` and
+a user searches for ``john lennon``, Django will do the equivalent
+of this SQL ``WHERE`` clause::
+WHERE (first_name ILIKE 'john' OR last_name ILIKE 'john')
+AND (first_name ILIKE 'lennon' OR last_name ILIKE 'lennon')
+Note that the query input is split by spaces, so, following this example,
+it's not currently not possible to search for all records in which
+``first_name`` is exactly ``'john winston'`` (containing a space).
+``@``
+Performs a full-text match. This is like the default search method but uses
+an index. Currently this is only available for MySQL.
+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: http://www.djangoproject.com/documentation/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(maxlength=200)
+poll_date = models.DateField()
+objects = PollManager()
+class Response(models.Model):
+poll = models.ForeignKey(Poll)
+person_name = models.CharField(maxlength=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(maxlength=100)
+author = models.CharField(maxlength=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(maxlength=100)
+author = models.CharField(maxlength=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(maxlength=50)
+last_name = models.CharField(maxlength=50)
+sex = models.CharField(maxlength=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 order by which they're defined in the model) has a
+special status. Django interprets the first ``Manager`` defined in a class as
+the "default" ``Manager``. Certain operations -- such as Django's admin site --
+use the default ``Manager`` to obtain lists of objects, so it's generally a
+good idea for the first ``Manager`` to be relatively unfiltered. In the last
+example, the ``people`` ``Manager`` is defined first -- so it's the default
+``Manager``.
+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(maxlength=50)
+last_name = models.CharField(maxlength=50)
+birth_date = models.DateField()
+address = models.CharField(maxlength=100)
+city = models.CharField(maxlength=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)`` 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.
+For example::
+class Person(models.Model):
+first_name = models.CharField(maxlength=50)
+last_name = models.CharField(maxlength=50)
+def __str__(self):
+return '%s %s' % (self.first_name, self.last_name)
+``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.
+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>
+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 and any parameters you
+would use for accessing this instance directly. Django then works out the
+correct full URL path using the URLconf. For example::
+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)
+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.
+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`` simply use the standard `Python DB-API`_. 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
+just 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: http://www.djangoproject.com/documentation/db_api/#extra-params-select-where-tables
+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(maxlength=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(maxlength=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: http://www.djangoproject.com/documentation/db_api/
+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 ``sqlinitialdata``, ``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`: http://www.djangoproject.com/documentation/django_admin/#sqlinitialdata-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``.