PageRenderTime 5ms CodeModel.GetById 58ms app.highlight 16ms RepoModel.GetById 18ms app.codeStats 0ms

/docs/topics/db/models.txt

https://code.google.com/p/mango-py/
Plain Text | 1236 lines | 935 code | 301 blank | 0 comment | 0 complexity | 18377b9c58493332c8747f9cae5edc36 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1======
   2Models
   3======
   4
   5.. module:: django.db.models
   6
   7A model is the single, definitive source of data about your data. It contains
   8the essential fields and behaviors of the data you're storing. Generally, each
   9model maps to a single database table.
  10
  11The basics:
  12
  13    * Each model is a Python class that subclasses
  14      :class:`django.db.models.Model`.
  15
  16    * Each attribute of the model represents a database field.
  17
  18    * With all of this, Django gives you an automatically-generated
  19      database-access API; see :doc:`/topics/db/queries`.
  20
  21.. seealso::
  22
  23    A companion to this document is the `official repository of model
  24    examples`_. (In the Django source distribution, these examples are in the
  25    ``tests/modeltests`` directory.)
  26
  27    .. _official repository of model examples: http://code.djangoproject.com/browser/django/trunk/tests/modeltests
  28
  29Quick example
  30=============
  31
  32This example model defines a ``Person``, which has a ``first_name`` and
  33``last_name``::
  34
  35    from django.db import models
  36
  37    class Person(models.Model):
  38        first_name = models.CharField(max_length=30)
  39        last_name = models.CharField(max_length=30)
  40
  41``first_name`` and ``last_name`` are fields_ of the model. Each field is
  42specified as a class attribute, and each attribute maps to a database column.
  43
  44The above ``Person`` model would create a database table like this:
  45
  46.. code-block:: sql
  47
  48    CREATE TABLE myapp_person (
  49        "id" serial NOT NULL PRIMARY KEY,
  50        "first_name" varchar(30) NOT NULL,
  51        "last_name" varchar(30) NOT NULL
  52    );
  53
  54Some technical notes:
  55
  56    * The name of the table, ``myapp_person``, is automatically derived from
  57      some model metadata but can be overridden. See :ref:`table-names` for more
  58      details..
  59
  60    * An ``id`` field is added automatically, but this behavior can be
  61      overridden. See :ref:`automatic-primary-key-fields`.
  62
  63    * The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL
  64      syntax, but it's worth noting Django uses SQL tailored to the database
  65      backend specified in your :doc:`settings file </topics/settings>`.
  66
  67Using models
  68============
  69
  70Once you have defined your models, you need to tell Django you're going to *use*
  71those models. Do this by editing your settings file and changing the
  72:setting:`INSTALLED_APPS` setting to add the name of the module that contains
  73your ``models.py``.
  74
  75For example, if the models for your application live in the module
  76``mysite.myapp.models`` (the package structure that is created for an
  77application by the :djadmin:`manage.py startapp <startapp>` script),
  78:setting:`INSTALLED_APPS` should read, in part::
  79
  80    INSTALLED_APPS = (
  81        #...
  82        'mysite.myapp',
  83        #...
  84    )
  85
  86When you add new apps to :setting:`INSTALLED_APPS`, be sure to run
  87:djadmin:`manage.py syncdb <syncdb>`.
  88
  89Fields
  90======
  91
  92The most important part of a model -- and the only required part of a model --
  93is the list of database fields it defines. Fields are specified by class
  94attributes.
  95
  96Example::
  97
  98    class Musician(models.Model):
  99        first_name = models.CharField(max_length=50)
 100        last_name = models.CharField(max_length=50)
 101        instrument = models.CharField(max_length=100)
 102
 103    class Album(models.Model):
 104        artist = models.ForeignKey(Musician)
 105        name = models.CharField(max_length=100)
 106        release_date = models.DateField()
 107        num_stars = models.IntegerField()
 108
 109Field types
 110-----------
 111
 112Each field in your model should be an instance of the appropriate
 113:class:`~django.db.models.Field` class. Django uses the field class types to
 114determine a few things:
 115
 116    * The database column type (e.g. ``INTEGER``, ``VARCHAR``).
 117
 118    * The :doc:`widget </ref/forms/widgets>` to use in Django's admin interface,
 119      if you care to use it (e.g. ``<input type="text">``, ``<select>``).
 120
 121    * The minimal validation requirements, used in Django's admin and in
 122      automatically-generated forms.
 123
 124Django ships with dozens of built-in field types; you can find the complete list
 125in the :ref:`model field reference <model-field-types>`. You can easily write
 126your own fields if Django's built-in ones don't do the trick; see
 127:doc:`/howto/custom-model-fields`.
 128
 129Field options
 130-------------
 131
 132Each field takes a certain set of field-specific arguments (documented in the
 133:ref:`model field reference <model-field-types>`). For example,
 134:class:`~django.db.models.CharField` (and its subclasses) require a
 135:attr:`~django.db.models.CharField.max_length` argument which specifies the size
 136of the ``VARCHAR`` database field used to store the data.
 137
 138There's also a set of common arguments available to all field types. All are
 139optional. They're fully explained in the :ref:`reference
 140<common-model-field-options>`, but here's a quick summary of the most often-used
 141ones:
 142
 143    :attr:`~Field.null`
 144        If ``True``, Django will store empty values as ``NULL`` in the database.
 145        Default is ``False``.
 146
 147    :attr:`~Field.blank`
 148        If ``True``, the field is allowed to be blank. Default is ``False``.
 149
 150        Note that this is different than :attr:`~Field.null`.
 151        :attr:`~Field.null` is purely database-related, whereas
 152        :attr:`~Field.blank` is validation-related. If a field has
 153        :attr:`blank=True <Field.blank>`, validation on Django's admin site will
 154        allow entry of an empty value. If a field has :attr:`blank=False
 155        <Field.blank>`, the field will be required.
 156
 157    :attr:`~Field.choices`
 158        An iterable (e.g., a list or tuple) of 2-tuples to use as choices for
 159        this field. If this is given, Django's admin will use a select box
 160        instead of the standard text field and will limit choices to the choices
 161        given.
 162
 163        A choices list looks like this::
 164
 165            YEAR_IN_SCHOOL_CHOICES = (
 166                (u'FR', u'Freshman'),
 167                (u'SO', u'Sophomore'),
 168                (u'JR', u'Junior'),
 169                (u'SR', u'Senior'),
 170                (u'GR', u'Graduate'),
 171            )
 172
 173        The first element in each tuple is the value that will be stored in the
 174        database, the second element will be displayed by the admin interface,
 175        or in a ModelChoiceField. Given an instance of a model object, the
 176        display value for a choices field can be accessed using the
 177        ``get_FOO_display`` method. For example::
 178
 179            from django.db import models
 180
 181            class Person(models.Model):
 182                GENDER_CHOICES = (
 183                    (u'M', u'Male'),
 184                    (u'F', u'Female'),
 185                )
 186                name = models.CharField(max_length=60)
 187                gender = models.CharField(max_length=2, choices=GENDER_CHOICES)
 188
 189        ::
 190
 191            >>> p = Person(name="Fred Flintstone", gender="M")
 192            >>> p.save()
 193            >>> p.gender
 194            u'M'
 195            >>> p.get_gender_display()
 196            u'Male'
 197
 198    :attr:`~Field.default`
 199        The default value for the field. This can be a value or a callable
 200        object. If callable it will be called every time a new object is
 201        created.
 202
 203    :attr:`~Field.help_text`
 204        Extra "help" text to be displayed under the field on the object's admin
 205        form. It's useful for documentation even if your object doesn't have an
 206        admin form.
 207
 208    :attr:`~Field.primary_key`
 209        If ``True``, this field is the primary key for the model.
 210
 211        If you don't specify :attr:`primary_key=True <Field.primary_key>` for
 212        any fields in your model, Django will automatically add an
 213        :class:`IntegerField` to hold the primary key, so you don't need to set
 214        :attr:`primary_key=True <Field.primary_key>` on any of your fields
 215        unless you want to override the default primary-key behavior. For more,
 216        see :ref:`automatic-primary-key-fields`.
 217
 218    :attr:`~Field.unique`
 219        If ``True``, this field must be unique throughout the table.
 220
 221Again, these are just short descriptions of the most common field options. Full
 222details can be found in the :ref:`common model field option reference
 223<common-model-field-options>`.
 224
 225.. _automatic-primary-key-fields:
 226
 227Automatic primary key fields
 228----------------------------
 229
 230By default, Django gives each model the following field::
 231
 232    id = models.AutoField(primary_key=True)
 233
 234This is an auto-incrementing primary key.
 235
 236If you'd like to specify a custom primary key, just specify
 237:attr:`primary_key=True <Field.primary_key>` on one of your fields. If Django
 238sees you've explicitly set :attr:`Field.primary_key`, it won't add the automatic
 239``id`` column.
 240
 241Each model requires exactly one field to have :attr:`primary_key=True
 242<Field.primary_key>`.
 243
 244.. _verbose-field-names:
 245
 246Verbose field names
 247-------------------
 248
 249Each field type, except for :class:`~django.db.models.ForeignKey`,
 250:class:`~django.db.models.ManyToManyField` and
 251:class:`~django.db.models.OneToOneField`, takes an optional first positional
 252argument -- a verbose name. If the verbose name isn't given, Django will
 253automatically create it using the field's attribute name, converting underscores
 254to spaces.
 255
 256In this example, the verbose name is ``"person's first name"``::
 257
 258    first_name = models.CharField("person's first name", max_length=30)
 259
 260In this example, the verbose name is ``"first name"``::
 261
 262    first_name = models.CharField(max_length=30)
 263
 264:class:`~django.db.models.ForeignKey`,
 265:class:`~django.db.models.ManyToManyField` and
 266:class:`~django.db.models.OneToOneField` require the first argument to be a
 267model class, so use the :attr:`~Field.verbose_name` keyword argument::
 268
 269    poll = models.ForeignKey(Poll, verbose_name="the related poll")
 270    sites = models.ManyToManyField(Site, verbose_name="list of sites")
 271    place = models.OneToOneField(Place, verbose_name="related place")
 272
 273The convention is not to capitalize the first letter of the
 274:attr:`~Field.verbose_name`. Django will automatically capitalize the first
 275letter where it needs to.
 276
 277Relationships
 278-------------
 279
 280Clearly, the power of relational databases lies in relating tables to each
 281other. Django offers ways to define the three most common types of database
 282relationships: many-to-one, many-to-many and one-to-one.
 283
 284Many-to-one relationships
 285~~~~~~~~~~~~~~~~~~~~~~~~~
 286
 287To define a many-to-one relationship, use :class:`django.db.models.ForeignKey`.
 288You use it just like any other :class:`~django.db.models.Field` type: by
 289including it as a class attribute of your model.
 290
 291:class:`~django.db.models.ForeignKey` requires a positional argument: the class
 292to which the model is related.
 293
 294For example, if a ``Car`` model has a ``Manufacturer`` -- that is, a
 295``Manufacturer`` makes multiple cars but each ``Car`` only has one
 296``Manufacturer`` -- use the following definitions::
 297
 298    class Manufacturer(models.Model):
 299        # ...
 300
 301    class Car(models.Model):
 302        manufacturer = models.ForeignKey(Manufacturer)
 303        # ...
 304
 305You can also create :ref:`recursive relationships <recursive-relationships>` (an
 306object with a many-to-one relationship to itself) and :ref:`relationships to
 307models not yet defined <lazy-relationships>`; see :ref:`the model field
 308reference <ref-foreignkey>` for details.
 309
 310It's suggested, but not required, that the name of a
 311:class:`~django.db.models.ForeignKey` field (``manufacturer`` in the example
 312above) be the name of the model, lowercase. You can, of course, call the field
 313whatever you want. For example::
 314
 315    class Car(models.Model):
 316        company_that_makes_it = models.ForeignKey(Manufacturer)
 317        # ...
 318
 319.. seealso::
 320
 321    :class:`~django.db.models.ForeignKey` fields accept a number of extra
 322    arguments which are explained in :ref:`the model field reference
 323    <foreign-key-arguments>`. These options help define how the relationship
 324    should work; all are optional.
 325
 326    For details on accessing backwards-related objects, see the
 327    `Following relationships backward example`_.
 328    
 329    For sample code, see the `Many-to-one relationship model tests`_.
 330
 331    .. _Following relationships backward example: http://docs.djangoproject.com/en/dev/topics/db/queries/#backwards-related-objects
 332    .. _Many-to-one relationship model tests: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_one
 333
 334Many-to-many relationships
 335~~~~~~~~~~~~~~~~~~~~~~~~~~
 336
 337To define a many-to-many relationship, use
 338:class:`~django.db.models.ManyToManyField`. You use it just like any other
 339:class:`~django.db.models.Field` type: by including it as a class attribute of
 340your model.
 341
 342:class:`~django.db.models.ManyToManyField` requires a positional argument: the
 343class to which the model is related.
 344
 345For example, if a ``Pizza`` has multiple ``Topping`` objects -- that is, a
 346``Topping`` can be on multiple pizzas and each ``Pizza`` has multiple toppings
 347-- here's how you'd represent that::
 348
 349    class Topping(models.Model):
 350        # ...
 351
 352    class Pizza(models.Model):
 353        # ...
 354        toppings = models.ManyToManyField(Topping)
 355
 356As with :class:`~django.db.models.ForeignKey`, you can also create
 357:ref:`recursive relationships <recursive-relationships>` (an object with a
 358many-to-many relationship to itself) and :ref:`relationships to models not yet
 359defined <lazy-relationships>`; see :ref:`the model field reference
 360<ref-manytomany>` for details.
 361
 362It's suggested, but not required, that the name of a
 363:class:`~django.db.models.ManyToManyField` (``toppings`` in the example above)
 364be a plural describing the set of related model objects.
 365
 366It doesn't matter which model gets the
 367:class:`~django.db.models.ManyToManyField`, but you only need it in one of the
 368models -- not in both.
 369
 370Generally, :class:`~django.db.models.ManyToManyField` instances should go in the
 371object that's going to be edited in the admin interface, if you're using
 372Django's admin. In the above example, ``toppings`` is in ``Pizza`` (rather than
 373``Topping`` having a ``pizzas`` :class:`~django.db.models.ManyToManyField` )
 374because it's more natural to think about a pizza having toppings than a
 375topping being on multiple pizzas. The way it's set up above, the ``Pizza`` admin
 376form would let users select the toppings.
 377
 378.. seealso::
 379
 380    See the `Many-to-many relationship model example`_ for a full example.
 381
 382.. _Many-to-many relationship model example: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_many/models.py
 383
 384:class:`~django.db.models.ManyToManyField` fields also accept a number of extra
 385arguments which are explained in :ref:`the model field reference
 386<manytomany-arguments>`. These options help define how the relationship should
 387work; all are optional.
 388
 389.. _intermediary-manytomany:
 390
 391Extra fields on many-to-many relationships
 392~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 393
 394When you're only dealing with simple many-to-many relationships such as
 395mixing and matching pizzas and toppings, a standard :class:`~django.db.models.ManyToManyField` is all you need. However, sometimes
 396you may need to associate data with the relationship between two models.
 397
 398For example, consider the case of an application tracking the musical groups
 399which musicians belong to. There is a many-to-many relationship between a person
 400and the groups of which they are a member, so you could use a
 401:class:`~django.db.models.ManyToManyField` to represent this relationship.
 402However, there is a lot of detail about the membership that you might want to
 403collect, such as the date at which the person joined the group.
 404
 405For these situations, Django allows you to specify the model that will be used
 406to govern the many-to-many relationship. You can then put extra fields on the
 407intermediate model. The intermediate model is associated with the
 408:class:`~django.db.models.ManyToManyField` using the
 409:attr:`through <ManyToManyField.through>` argument to point to the model
 410that will act as an intermediary. For our musician example, the code would look
 411something like this::
 412
 413    class Person(models.Model):
 414        name = models.CharField(max_length=128)
 415
 416        def __unicode__(self):
 417            return self.name
 418
 419    class Group(models.Model):
 420        name = models.CharField(max_length=128)
 421        members = models.ManyToManyField(Person, through='Membership')
 422
 423        def __unicode__(self):
 424            return self.name
 425
 426    class Membership(models.Model):
 427        person = models.ForeignKey(Person)
 428        group = models.ForeignKey(Group)
 429        date_joined = models.DateField()
 430        invite_reason = models.CharField(max_length=64)
 431
 432When you set up the intermediary model, you explicitly specify foreign
 433keys to the models that are involved in the ManyToMany relation. This
 434explicit declaration defines how the two models are related.
 435
 436There are a few restrictions on the intermediate model:
 437
 438    * Your intermediate model must contain one - and *only* one - foreign key
 439      to the target model (this would be ``Person`` in our example). If you
 440      have more than one foreign key, a validation error will be raised.
 441
 442    * Your intermediate model must contain one - and *only* one - foreign key
 443      to the source model (this would be ``Group`` in our example). If you
 444      have more than one foreign key, a validation error will be raised.
 445
 446    * The only exception to this is a model which has a many-to-many
 447      relationship to itself, through an intermediary model. In this
 448      case, two foreign keys to the same model are permitted, but they
 449      will be treated as the two (different) sides of the many-to-many
 450      relation.
 451
 452    * When defining a many-to-many relationship from a model to
 453      itself, using an intermediary model, you *must* use
 454      :attr:`symmetrical=False <ManyToManyField.symmetrical>` (see
 455      :ref:`the model field reference <manytomany-arguments>`).
 456
 457Now that you have set up your :class:`~django.db.models.ManyToManyField` to use
 458your intermediary model (``Membership``, in this case), you're ready to start
 459creating some many-to-many relationships. You do this by creating instances of
 460the intermediate model::
 461
 462    >>> ringo = Person.objects.create(name="Ringo Starr")
 463    >>> paul = Person.objects.create(name="Paul McCartney")
 464    >>> beatles = Group.objects.create(name="The Beatles")
 465    >>> m1 = Membership(person=ringo, group=beatles,
 466    ...     date_joined=date(1962, 8, 16),
 467    ...     invite_reason= "Needed a new drummer.")
 468    >>> m1.save()
 469    >>> beatles.members.all()
 470    [<Person: Ringo Starr>]
 471    >>> ringo.group_set.all()
 472    [<Group: The Beatles>]
 473    >>> m2 = Membership.objects.create(person=paul, group=beatles,
 474    ...     date_joined=date(1960, 8, 1),
 475    ...     invite_reason= "Wanted to form a band.")
 476    >>> beatles.members.all()
 477    [<Person: Ringo Starr>, <Person: Paul McCartney>]
 478
 479Unlike normal many-to-many fields, you *can't* use ``add``, ``create``,
 480or assignment (i.e., ``beatles.members = [...]``) to create relationships::
 481
 482    # THIS WILL NOT WORK
 483    >>> beatles.members.add(john)
 484    # NEITHER WILL THIS
 485    >>> beatles.members.create(name="George Harrison")
 486    # AND NEITHER WILL THIS
 487    >>> beatles.members = [john, paul, ringo, george]
 488
 489Why? You can't just create a relationship between a ``Person`` and a ``Group``
 490- you need to specify all the detail for the relationship required by the
 491``Membership`` model. The simple ``add``, ``create`` and assignment calls
 492don't provide a way to specify this extra detail. As a result, they are
 493disabled for many-to-many relationships that use an intermediate model.
 494The only way to create this type of relationship is to create instances of the
 495intermediate model.
 496
 497The :meth:`~django.db.models.fields.related.RelatedManager.remove` method is
 498disabled for similar reasons. However, the
 499:meth:`~django.db.models.fields.related.RelatedManager.clear` method can be
 500used to remove all many-to-many relationships for an instance::
 501
 502    # Beatles have broken up
 503    >>> beatles.members.clear()
 504
 505Once you have established the many-to-many relationships by creating instances
 506of your intermediate model, you can issue queries. Just as with normal
 507many-to-many relationships, you can query using the attributes of the
 508many-to-many-related model::
 509
 510    # Find all the groups with a member whose name starts with 'Paul'
 511    >>> Group.objects.filter(members__name__startswith='Paul')
 512    [<Group: The Beatles>]
 513
 514As you are using an intermediate model, you can also query on its attributes::
 515
 516    # Find all the members of the Beatles that joined after 1 Jan 1961
 517    >>> Person.objects.filter(
 518    ...     group__name='The Beatles',
 519    ...     membership__date_joined__gt=date(1961,1,1))
 520    [<Person: Ringo Starr]
 521
 522
 523One-to-one relationships
 524~~~~~~~~~~~~~~~~~~~~~~~~
 525
 526To define a one-to-one relationship, use
 527:class:`~django.db.models.OneToOneField`. You use it just like any other
 528``Field`` type: by including it as a class attribute of your model.
 529
 530This is most useful on the primary key of an object when that object "extends"
 531another object in some way.
 532
 533:class:`~django.db.models.OneToOneField` requires a positional argument: the
 534class to which the model is related.
 535
 536For example, if you were building a database of "places", you would
 537build pretty standard stuff such as address, phone number, etc. in the
 538database. Then, if you wanted to build a database of restaurants on
 539top of the places, instead of repeating yourself and replicating those
 540fields in the ``Restaurant`` model, you could make ``Restaurant`` have
 541a :class:`~django.db.models.OneToOneField` to ``Place`` (because a
 542restaurant "is a" place; in fact, to handle this you'd typically use
 543:ref:`inheritance <model-inheritance>`, which involves an implicit
 544one-to-one relation).
 545
 546As with :class:`~django.db.models.ForeignKey`, a
 547:ref:`recursive relationship <recursive-relationships>`
 548can be defined and
 549:ref:`references to as-yet undefined models <lazy-relationships>`
 550can be made; see :ref:`the model field reference <ref-onetoone>` for details.
 551
 552.. seealso::
 553
 554    See the `One-to-one relationship model example`_ for a full example.
 555
 556.. _One-to-one relationship model example: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/one_to_one/models.py
 557
 558:class:`~django.db.models.OneToOneField` fields also accept one optional argument
 559described in the :ref:`model field reference <ref-onetoone>`.
 560
 561:class:`~django.db.models.OneToOneField` classes used to automatically become
 562the primary key on a model. This is no longer true (although you can manually
 563pass in the :attr:`~django.db.models.Field.primary_key` argument if you like).
 564Thus, it's now possible to have multiple fields of type
 565:class:`~django.db.models.OneToOneField` on a single model.
 566
 567Models across files
 568-------------------
 569
 570It's perfectly OK to relate a model to one from another app. To do this,
 571import the related model at the top of the model that holds your model. Then,
 572just refer to the other model class wherever needed. For example::
 573
 574    from geography.models import ZipCode
 575
 576    class Restaurant(models.Model):
 577        # ...
 578        zip_code = models.ForeignKey(ZipCode)
 579
 580Field name restrictions
 581-----------------------
 582
 583Django places only two restrictions on model field names:
 584
 585    1. A field name cannot be a Python reserved word, because that would result
 586       in a Python syntax error. For example::
 587
 588           class Example(models.Model):
 589               pass = models.IntegerField() # 'pass' is a reserved word!
 590
 591    2. A field name cannot contain more than one underscore in a row, due to
 592       the way Django's query lookup syntax works. For example::
 593
 594           class Example(models.Model):
 595               foo__bar = models.IntegerField() # 'foo__bar' has two underscores!
 596
 597These limitations can be worked around, though, because your field name doesn't
 598necessarily have to match your database column name. See the
 599:attr:`~Field.db_column` option.
 600
 601SQL reserved words, such as ``join``, ``where`` or ``select``, *are* allowed as
 602model field names, because Django escapes all database table names and column
 603names in every underlying SQL query. It uses the quoting syntax of your
 604particular database engine.
 605
 606Custom field types
 607------------------
 608
 609If one of the existing model fields cannot be used to fit your purposes, or if
 610you wish to take advantage of some less common database column types, you can
 611create your own field class. Full coverage of creating your own fields is
 612provided in :doc:`/howto/custom-model-fields`.
 613
 614.. _meta-options:
 615
 616Meta options
 617============
 618
 619Give your model metadata by using an inner ``class Meta``, like so::
 620
 621    class Ox(models.Model):
 622        horn_length = models.IntegerField()
 623
 624        class Meta:
 625            ordering = ["horn_length"]
 626            verbose_name_plural = "oxen"
 627
 628Model metadata is "anything that's not a field", such as ordering options
 629(:attr:`~Options.ordering`), database table name (:attr:`~Options.db_table`), or
 630human-readable singular and plural names (:attr:`~Options.verbose_name` and
 631:attr:`~Options.verbose_name_plural`). None are required, and adding ``class
 632Meta`` to a model is completely optional.
 633
 634A complete list of all possible ``Meta`` options can be found in the :doc:`model
 635option reference </ref/models/options>`.
 636
 637.. _model-methods:
 638
 639Model methods
 640=============
 641
 642Define custom methods on a model to add custom "row-level" functionality to your
 643objects. Whereas :class:`~django.db.models.Manager` methods are intended to do
 644"table-wide" things, model methods should act on a particular model instance.
 645
 646This is a valuable technique for keeping business logic in one place -- the
 647model.
 648
 649For example, this model has a few custom methods::
 650
 651    from django.contrib.localflavor.us.models import USStateField
 652
 653    class Person(models.Model):
 654        first_name = models.CharField(max_length=50)
 655        last_name = models.CharField(max_length=50)
 656        birth_date = models.DateField()
 657        address = models.CharField(max_length=100)
 658        city = models.CharField(max_length=50)
 659        state = USStateField() # Yes, this is America-centric...
 660
 661        def baby_boomer_status(self):
 662            "Returns the person's baby-boomer status."
 663            import datetime
 664            if datetime.date(1945, 8, 1) <= self.birth_date <= datetime.date(1964, 12, 31):
 665                return "Baby boomer"
 666            if self.birth_date < datetime.date(1945, 8, 1):
 667                return "Pre-boomer"
 668            return "Post-boomer"
 669
 670        def is_midwestern(self):
 671            "Returns True if this person is from the Midwest."
 672            return self.state in ('IL', 'WI', 'MI', 'IN', 'OH', 'IA', 'MO')
 673
 674        def _get_full_name(self):
 675            "Returns the person's full name."
 676            return '%s %s' % (self.first_name, self.last_name)
 677        full_name = property(_get_full_name)
 678
 679The last method in this example is a :term:`property`. `Read more about
 680properties`_.
 681
 682.. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property
 683
 684The :doc:`model instance reference </ref/models/instances>` has a complete list
 685of :ref:`methods automatically given to each model <model-instance-methods>`.
 686You can override most of these -- see `overriding predefined model methods`_,
 687below -- but there are a couple that you'll almost always want to define:
 688
 689    :meth:`~Model.__unicode__`
 690        A Python "magic method" that returns a unicode "representation" of any
 691        object. This is what Python and Django will use whenever a model
 692        instance needs to be coerced and displayed as a plain string. Most
 693        notably, this happens when you display an object in an interactive
 694        console or in the admin.
 695
 696        You'll always want to define this method; the default isn't very helpful
 697        at all.
 698
 699    :meth:`~Model.get_absolute_url`
 700        This tells Django how to calculate the URL for an object. Django uses
 701        this in its admin interface, and any time it needs to figure out a URL
 702        for an object.
 703
 704        Any object that has a URL that uniquely identifies it should define this
 705        method.
 706
 707.. _overriding-model-methods:
 708
 709Overriding predefined model methods
 710-----------------------------------
 711
 712There's another set of :ref:`model methods <model-instance-methods>` that
 713encapsulate a bunch of database behavior that you'll want to customize. In
 714particular you'll often want to change the way :meth:`~Model.save` and
 715:meth:`~Model.delete` work.
 716
 717You're free to override these methods (and any other model method) to alter
 718behavior.
 719
 720A classic use-case for overriding the built-in methods is if you want something
 721to happen whenever you save an object. For example (see
 722:meth:`~Model.save` for documentation of the parameters it accepts)::
 723
 724    class Blog(models.Model):
 725        name = models.CharField(max_length=100)
 726        tagline = models.TextField()
 727
 728        def save(self, *args, **kwargs):
 729            do_something()
 730            super(Blog, self).save(*args, **kwargs) # Call the "real" save() method.
 731            do_something_else()
 732
 733You can also prevent saving::
 734
 735    class Blog(models.Model):
 736        name = models.CharField(max_length=100)
 737        tagline = models.TextField()
 738
 739        def save(self, *args, **kwargs):
 740            if self.name == "Yoko Ono's blog":
 741                return # Yoko shall never have her own blog!
 742            else:
 743                super(Blog, self).save(*args, **kwargs) # Call the "real" save() method.
 744
 745It's important to remember to call the superclass method -- that's
 746that ``super(Blog, self).save(*args, **kwargs)`` business -- to ensure
 747that the object still gets saved into the database. If you forget to
 748call the superclass method, the default behavior won't happen and the
 749database won't get touched.
 750
 751It's also important that you pass through the arguments that can be
 752passed to the model method -- that's what the ``*args, **kwargs`` bit
 753does. Django will, from time to time, extend the capabilities of
 754built-in model methods, adding new arguments. If you use ``*args,
 755**kwargs`` in your method definitions, you are guaranteed that your
 756code will automatically support those arguments when they are added.
 757
 758.. admonition:: Overriding Delete
 759
 760    Note that the :meth:`~Model.delete()` method for an object is not
 761    necessarily called when :ref:`deleting objects in bulk using a
 762    QuerySet<topics-db-queries-delete>`. To ensure customized delete logic
 763    gets executed, you can use :data:`~django.db.models.signals.pre_delete`
 764    and/or :data:`~django.db.models.signals.post_delete` signals.
 765
 766Executing custom SQL
 767--------------------
 768
 769Another common pattern is writing custom SQL statements in model methods and
 770module-level methods. For more details on using raw SQL, see the documentation
 771on :doc:`using raw SQL</topics/db/sql>`.
 772
 773.. _model-inheritance:
 774
 775Model inheritance
 776=================
 777
 778Model inheritance in Django works almost identically to the way normal
 779class inheritance works in Python. The only decision you have to make
 780is whether you want the parent models to be models in their own right
 781(with their own database tables), or if the parents are just holders
 782of common information that will only be visible through the child
 783models.
 784
 785There are three styles of inheritance that are possible in Django.
 786
 787 1. Often, you will just want to use the parent class to hold information that
 788    you don't want to have to type out for each child model. This class isn't
 789    going to ever be used in isolation, so :ref:`abstract-base-classes` are
 790    what you're after.
 791 2. If you're subclassing an existing model (perhaps something from another
 792    application entirely) and want each model to have its own database table,
 793    :ref:`multi-table-inheritance` is the way to go.
 794 3. Finally, if you only want to modify the Python-level behavior of a model,
 795    without changing the models fields in any way, you can use
 796    :ref:`proxy-models`.
 797
 798.. _abstract-base-classes:
 799
 800Abstract base classes
 801---------------------
 802
 803Abstract base classes are useful when you want to put some common
 804information into a number of other models. You write your base class
 805and put ``abstract=True`` in the :ref:`Meta <meta-options>`
 806class. This model will then not be used to create any database
 807table. Instead, when it is used as a base class for other models, its
 808fields will be added to those of the child class. It is an error to
 809have fields in the abstract base class with the same name as those in
 810the child (and Django will raise an exception).
 811
 812An example::
 813
 814    class CommonInfo(models.Model):
 815        name = models.CharField(max_length=100)
 816        age = models.PositiveIntegerField()
 817
 818        class Meta:
 819            abstract = True
 820
 821    class Student(CommonInfo):
 822        home_group = models.CharField(max_length=5)
 823
 824The ``Student`` model will have three fields: ``name``, ``age`` and
 825``home_group``. The ``CommonInfo`` model cannot be used as a normal Django
 826model, since it is an abstract base class. It does not generate a database
 827table or have a manager, and cannot be instantiated or saved directly.
 828
 829For many uses, this type of model inheritance will be exactly what you want.
 830It provides a way to factor out common information at the Python level, whilst
 831still only creating one database table per child model at the database level.
 832
 833``Meta`` inheritance
 834~~~~~~~~~~~~~~~~~~~~
 835
 836When an abstract base class is created, Django makes any :ref:`Meta <meta-options>`
 837inner class you declared in the base class available as an
 838attribute. If a child class does not declare its own :ref:`Meta <meta-options>`
 839class, it will inherit the parent's :ref:`Meta <meta-options>`. If the child wants to
 840extend the parent's :ref:`Meta <meta-options>` class, it can subclass it. For example::
 841
 842    class CommonInfo(models.Model):
 843        ...
 844        class Meta:
 845            abstract = True
 846            ordering = ['name']
 847
 848    class Student(CommonInfo):
 849        ...
 850        class Meta(CommonInfo.Meta):
 851            db_table = 'student_info'
 852
 853Django does make one adjustment to the :ref:`Meta <meta-options>` class of an abstract base
 854class: before installing the :ref:`Meta <meta-options>` attribute, it sets ``abstract=False``.
 855This means that children of abstract base classes don't automatically become
 856abstract classes themselves. Of course, you can make an abstract base class
 857that inherits from another abstract base class. You just need to remember to
 858explicitly set ``abstract=True`` each time.
 859
 860Some attributes won't make sense to include in the :ref:`Meta <meta-options>` class of an
 861abstract base class. For example, including ``db_table`` would mean that all
 862the child classes (the ones that don't specify their own :ref:`Meta <meta-options>`) would use
 863the same database table, which is almost certainly not what you want.
 864
 865.. _abstract-related-name:
 866
 867Be careful with ``related_name``
 868~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 869
 870If you are using the :attr:`~django.db.models.ForeignKey.related_name` attribute on a ``ForeignKey`` or
 871``ManyToManyField``, you must always specify a *unique* reverse name for the
 872field. This would normally cause a problem in abstract base classes, since the
 873fields on this class are included into each of the child classes, with exactly
 874the same values for the attributes (including :attr:`~django.db.models.ForeignKey.related_name`) each time.
 875
 876.. versionchanged:: 1.2
 877
 878To work around this problem, when you are using :attr:`~django.db.models.ForeignKey.related_name` in an
 879abstract base class (only), part of the name should contain
 880``'%(app_label)s'`` and ``'%(class)s'``.
 881
 882- ``'%(class)s'`` is replaced by the lower-cased name of the child class
 883  that the field is used in.
 884- ``'%(app_label)s'`` is replaced by the lower-cased name of the app the child
 885  class is contained within. Each installed application name must be unique
 886  and the model class names within each app must also be unique, therefore the
 887  resulting name will end up being different.
 888
 889For example, given an app ``common/models.py``::
 890
 891    class Base(models.Model):
 892        m2m = models.ManyToManyField(OtherModel, related_name="%(app_label)s_%(class)s_related")
 893
 894        class Meta:
 895            abstract = True
 896
 897    class ChildA(Base):
 898        pass
 899
 900    class ChildB(Base):
 901        pass
 902
 903Along with another app ``rare/models.py``::
 904
 905    from common.models import Base
 906
 907    class ChildB(Base):
 908        pass
 909
 910The reverse name of the ``commmon.ChildA.m2m`` field will be
 911``common_childa_related``, whilst the reverse name of the
 912``common.ChildB.m2m`` field will be ``common_childb_related``, and finally the
 913reverse name of the ``rare.ChildB.m2m`` field will be ``rare_childb_related``.
 914It is up to you how you use the ``'%(class)s'`` and ``'%(app_label)s`` portion
 915to construct your related name, but if you forget to use it, Django will raise
 916errors when you validate your models (or run :djadmin:`syncdb`).
 917
 918If you don't specify a :attr:`~django.db.models.ForeignKey.related_name`
 919attribute for a field in an abstract base class, the default reverse name will
 920be the name of the child class followed by ``'_set'``, just as it normally
 921would be if you'd declared the field directly on the child class. For example,
 922in the above code, if the :attr:`~django.db.models.ForeignKey.related_name`
 923attribute was omitted, the reverse name for the ``m2m`` field would be
 924``childa_set`` in the ``ChildA`` case and ``childb_set`` for the ``ChildB``
 925field.
 926
 927.. _multi-table-inheritance:
 928
 929Multi-table inheritance
 930-----------------------
 931
 932The second type of model inheritance supported by Django is when each model in
 933the hierarchy is a model all by itself. Each model corresponds to its own
 934database table and can be queried and created individually. The inheritance
 935relationship introduces links between the child model and each of its parents
 936(via an automatically-created :class:`~django.db.models.OneToOneField`).
 937For example::
 938
 939    class Place(models.Model):
 940        name = models.CharField(max_length=50)
 941        address = models.CharField(max_length=80)
 942
 943    class Restaurant(Place):
 944        serves_hot_dogs = models.BooleanField()
 945        serves_pizza = models.BooleanField()
 946
 947All of the fields of ``Place`` will also be available in ``Restaurant``,
 948although the data will reside in a different database table. So these are both
 949possible::
 950
 951    >>> Place.objects.filter(name="Bob's Cafe")
 952    >>> Restaurant.objects.filter(name="Bob's Cafe")
 953
 954If you have a ``Place`` that is also a ``Restaurant``, you can get from the
 955``Place`` object to the ``Restaurant`` object by using the lower-case version
 956of the model name::
 957
 958    >>> p = Place.objects.get(id=12)
 959    # If p is a Restaurant object, this will give the child class:
 960    >>> p.restaurant
 961    <Restaurant: ...>
 962
 963However, if ``p`` in the above example was *not* a ``Restaurant`` (it had been
 964created directly as a ``Place`` object or was the parent of some other class),
 965referring to ``p.restaurant`` would raise a Restaurant.DoesNotExist exception.
 966
 967``Meta`` and multi-table inheritance
 968~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 969
 970In the multi-table inheritance situation, it doesn't make sense for a child
 971class to inherit from its parent's :ref:`Meta <meta-options>` class. All the :ref:`Meta <meta-options>` options
 972have already been applied to the parent class and applying them again would
 973normally only lead to contradictory behavior (this is in contrast with the
 974abstract base class case, where the base class doesn't exist in its own
 975right).
 976
 977So a child model does not have access to its parent's :ref:`Meta
 978<meta-options>` class. However, there are a few limited cases where the child
 979inherits behavior from the parent: if the child does not specify an
 980:attr:`~django.db.models.Options.ordering` attribute or a
 981:attr:`~django.db.models.Options.get_latest_by` attribute, it will inherit
 982these from its parent.
 983
 984If the parent has an ordering and you don't want the child to have any natural
 985ordering, you can explicitly disable it::
 986
 987    class ChildModel(ParentModel):
 988        ...
 989        class Meta:
 990            # Remove parent's ordering effect
 991            ordering = []
 992
 993Inheritance and reverse relations
 994~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 995
 996Because multi-table inheritance uses an implicit
 997:class:`~django.db.models.OneToOneField` to link the child and
 998the parent, it's possible to move from the parent down to the child,
 999as in the above example. However, this uses up the name that is the
1000default :attr:`~django.db.models.ForeignKey.related_name` value for
1001:class:`~django.db.models.ForeignKey` and
1002:class:`~django.db.models.ManyToManyField` relations.  If you
1003are putting those types of relations on a subclass of another model,
1004you **must** specify the
1005:attr:`~django.db.models.ForeignKey.related_name` attribute on each
1006such field. If you forget, Django will raise an error when you run
1007:djadmin:`validate` or :djadmin:`syncdb`.
1008
1009For example, using the above ``Place`` class again, let's create another
1010subclass with a :class:`~django.db.models.ManyToManyField`::
1011
1012    class Supplier(Place):
1013        # Must specify related_name on all relations.
1014        customers = models.ManyToManyField(Restaurant, related_name='provider')
1015
1016
1017Specifying the parent link field
1018~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1019
1020As mentioned, Django will automatically create a
1021:class:`~django.db.models.OneToOneField` linking your child
1022class back any non-abstract parent models. If you want to control the
1023name of the attribute linking back to the parent, you can create your
1024own :class:`~django.db.models.OneToOneField` and set
1025:attr:`parent_link=True <django.db.models.OneToOneField.parent_link>`
1026to indicate that your field is the link back to the parent class.
1027
1028.. _proxy-models:
1029
1030Proxy models
1031------------
1032
1033When using :ref:`multi-table inheritance <multi-table-inheritance>`, a new
1034database table is created for each subclass of a model. This is usually the
1035desired behavior, since the subclass needs a place to store any additional
1036data fields that are not present on the base class. Sometimes, however, you
1037only want to change the Python behavior of a model -- perhaps to change the
1038default manager, or add a new method.
1039
1040This is what proxy model inheritance is for: creating a *proxy* for the
1041original model. You can create, delete and update instances of the proxy model
1042and all the data will be saved as if you were using the original (non-proxied)
1043model. The difference is that you can change things like the default model
1044ordering or the default manager in the proxy, without having to alter the
1045original.
1046
1047Proxy models are declared like normal models. You tell Django that it's a
1048proxy model by setting the :attr:`~django.db.models.Options.proxy` attribute of
1049the ``Meta`` class to ``True``.
1050
1051For example, suppose you want to add a method to the standard
1052:class:`~django.contrib.auth.models.User` model that will be used in your
1053templates. You can do it like this::
1054
1055    from django.contrib.auth.models import User
1056
1057    class MyUser(User):
1058        class Meta:
1059            proxy = True
1060
1061        def do_something(self):
1062            ...
1063
1064The ``MyUser`` class operates on the same database table as its parent
1065:class:`~django.contrib.auth.models.User` class. In particular, any new
1066instances of :class:`~django.contrib.auth.models.User` will also be accessible
1067through ``MyUser``, and vice-versa::
1068
1069    >>> u = User.objects.create(username="foobar")
1070    >>> MyUser.objects.get(username="foobar")
1071    <MyUser: foobar>
1072
1073You could also use a proxy model to define a different default ordering on a
1074model. The standard :class:`~django.contrib.auth.models.User` model has no
1075ordering defined on it (intentionally; sorting is expensive and we don't want
1076to do it all the time when we fetch users). You might want to regularly order
1077by the ``username`` attribute when you use the proxy. This is easy::
1078
1079    class OrderedUser(User):
1080        class Meta:
1081            ordering = ["username"]
1082            proxy = True
1083
1084Now normal :class:`~django.contrib.auth.models.User` queries will be unordered
1085and ``OrderedUser`` queries will be ordered by ``username``.
1086
1087QuerySets still return the model that was requested
1088~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1089
1090There is no way to have Django return, say, a ``MyUser`` object whenever you
1091query for :class:`~django.contrib.auth.models.User` objects. A queryset for
1092``User`` objects will return those types of objects. The whole point of proxy
1093objects is that code relying on the original ``User`` will use those and your
1094own code can use the extensions you included (that no other code is relying on
1095anyway). It is not a way to replace the ``User`` (or any other) model
1096everywhere with something of your own creation.
1097
1098Base class restrictions
1099~~~~~~~~~~~~~~~~~~~~~~~
1100
1101A proxy model must inherit from exactly one non-abstract model class. You
1102can't inherit from multiple non-abstract models as the proxy model doesn't
1103provide any connection between the rows in the different database tables. A
1104proxy model can inherit from any number of abstract model classes, providing
1105they do *not* define any model fields.
1106
1107Proxy models inherit any ``Meta`` options that they don't define from their
1108non-abstract model parent (the model they are proxying for).
1109
1110Proxy model managers
1111~~~~~~~~~~~~~~~~~~~~
1112
1113If you don't specify any model managers on a proxy model, it inherits the
1114managers from its model parents. If you define a manager on the proxy model,
1115it will become the default, although any managers defined on the parent
1116classes will still be available.
1117
1118Continuing our example from above, you could change the default manager used
1119when you query the ``User`` model like this::
1120
1121    class NewManager(models.Manager):
1122        ...
1123
1124    class MyUser(User):
1125        objects = NewManager()
1126
1127        class Meta:
1128            proxy = True
1129
1130If you wanted to add a new manager to the Proxy, without replacing the
1131existing default, you can use the techniques described in the :ref:`custom
1132manager <custom-managers-and-inheritance>` documentation: create a base class
1133containing the new managers and inherit that after the primary base class::
1134
1135    # Create an abstract class for the new manager.
1136    class ExtraManagers(models.Model):
1137        secondary = NewManager()
1138
1139        class Meta:
1140            abstract = True
1141
1142    class MyUser(User, ExtraManagers):
1143        class Meta:
1144            proxy = True
1145
1146You probably won't need to do this very often, but, when you do, it's
1147possible.
1148
1149.. _proxy-vs-unmanaged-models:
1150
1151Differences between proxy inheritance and  unmanaged models
1152~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1153
1154Proxy model inheritance might look fairly similar to creating an unmanaged
1155model, using the :attr:`~django.db.models.Options.managed` attribute on a
1156model's ``Meta`` class. The two alternatives are not quite the same and it's
1157worth considering which one you should use.
1158
1159One difference is that you can (and, in fact, must unless you want an empty
1160model) specify model fields on models with ``Meta.managed=False``. You could,
1161with careful setting of :attr:`Meta.db_table
1162<django.db.models.Options.db_table>` create an unmanaged model that shadowed
1163an existing model and add Python methods to it. However, that would be very
1164repetitive and fragile as you need to keep both copies synchronized if you
1165make any changes.
1166
1167The other difference that is more important for proxy models, is how model
1168managers are handled. Proxy models are intended to behave exactly like the
1169model they are proxying for. So they inherit the parent model's managers,
1170including the default manager. In the normal multi-table model inheritance
1171case, children do not inherit managers from their parents as the custom
1172managers aren't always appropriate when extra fields are involved. The
1173:ref:`manager documentation <custom-managers-and-inheritance>` has more
1174details about this latter case.
1175
1176When these two features were implemented, attempts were made to squash them
1177into a single option. It turned out that interactions with inheritance, in
1178general, and managers, in particular, made the API very complicated and
1179potentially difficult to understand and use. It turned out that two options
1180were needed in any case, so the current separation arose.
1181
1182So, the general rules are:
1183
1184    1. If you are mirroring an existing model or database table and don't want
1185       all the original database table columns, use ``Meta.managed=False``.
1186       That option is normally useful for modeling database views and tables
1187       not under the control of Django.
1188    2. If you are wanting to change the Python-only behavior of a model, but
1189       keep all the same fields as in the original, use ``Meta.proxy=True``.
1190       This sets things up so that the proxy model is an exact copy of the
1191       storage structure of the original model when data is saved.
1192
1193Multiple inheritance
1194--------------------
1195
1196Just as with Python's subclassing, it's possible for a Django model to inherit
1197from multiple parent models. Keep in mind that normal Python name resolution
1198rules apply. The first base class that a particular name (e.g. :ref:`Meta
1199<meta-options>`) appears in will be the one that is used; for example, this
1200means that if multiple parents contain a :ref:`Meta <meta-options>` class,
1201only the first one is going to be used, and all others will be ignored.
1202
1203Generally, you won't need to inherit from multiple parents. The main use-case
1204where this is useful is for "mix-in" classes: adding a particular extra
1205field or method to every class that inherits the mix-in. Try to keep your
1206inheritance hierarchies as simple and straightforward as possible so that you
1207won't have to struggle to work out where a particular piece of information is
1208coming from.
1209
1210Field name "hiding" is not permitted
1211-------------------------------------
1212
1213In normal Python class inheritance, it is permissible for a child class to
1214override any attribute from the parent class. In Django, this is not permitted
1215for attributes that are :class:`~django.db.models.Field` instances (at
1216least, not at the moment). If a base class has a field called ``author``, you
1217cannot create another model field called ``author`` in any class that inherits
1218

Large files files are truncated, but you can click here to view the full file