/docs/topics/db/models.txt
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