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