=============== Model reference =============== Django's models are the bread and butter of the framework. There's a huge array of options available to you when defining your data models. This document explains them. Options for models ================== A list of all possible options for a model object follows. Although there's a wide array of options, only ``fields`` is required. ``admin`` A ``meta.Admin`` object; see `Admin options`_. If this field isn't given, the object will not have an admin interface. ``db_table`` The name of the database table to use for the module:: db_table = "pizza_orders" If this isn't given, Django will use ``app_label + '_' + module_name``. ``exceptions`` Names of extra exception subclasses to include in the generated module. These exceptions are available from instance methods and from module-level methods:: exceptions = ("DisgustingToppingsException", "BurntCrust") ``fields`` A list of field objects. See `Field objects`_. For example:: fields = ( meta.CharField('customer_name', maxlength=15), meta.BooleanField('use_extra_cheese'), meta.IntegerField('customer_type', choices=CUSTOMER_TYPE_CHOICES), ... ) ``get_latest_by`` The name of a ``DateField`` or ``DateTimeField``; if given, the module will have a ``get_latest()`` function that fetches the "latest" object according to that field:: get_latest_by = "order_date" ``module_constants`` A dictionary of names/values to use as extra module-level constants:: module_constants = { 'MEAT_TYPE_PEPPERONI' : 1, 'MEAT_TYPE_SAUSAGE' : 2, } ``module_name`` The name of the module:: module_name = "pizza_orders" If this isn't given, Django will use a lowercased version of the class name, plus "s". ``order_with_respect_to`` Marks this object as "orderable" with respect to the given field. This is almost always used with related objects to allow them to be ordered with respect to a parent object. For example, if a ``PizzaToppping`` relates to a ``Pizza`` object, you might use:: order_with_respect_to = 'pizza_id' to allow the toppings to be ordered with respect to the associated pizza. ``ordering`` The default ordering for the object, for use by ``get_list`` and the admin:: ordering = ['-order_date'] This is a tuple or list of strings. Each string is a field name with an optional "-" (indicating descending order). Or, you can use the string "?" to order randomly. ``permissions`` Extra permissions to enter into the permissions table when creating this object. A add, delete, and change permission is automatically created for each object. This option specifies extra permissions:: permissions = (("can_deliver_pizzas", "Can deliver pizzas"),) This is a list of 2-tuples of ``(permission_code, human_readable_permission_name)``. ``unique_together`` Sets of field names that, taken together, must be unique:: unique_together = (("driver_id", "restaurant_id"),) This is a list of lists of fields that must be unique when considered together. It's used in the Django admin. ``verbose_name`` A human-readable name for the object, singular:: verbose_name = "pizza" If this isn't given, Django will use a munged version of the class name: ``CamelCase`` becomes ``camel case``. ``verbose_name_plural`` The plural name for the object:: verbose_name_plural = "stories" If this isn't given, Django will use ``verbose_name + "s"``. Field objects ============= The list of fields is the most important part of a data model. Each item in the ``fields`` list is an instance of a ``meta.Field`` subclass and maps to a database field. All field objects -- except for ``ForeignKey`` and ``ManyToManyField`` (see below) -- require the field's machine-readable name as the first positional argument. This must be a valid Python identifier -- no spaces, punctuation, etc., are allowed. The second positional argument, a human-readable name, is optional. If the human-readable name isn't given, Django will use the machine-readable name, coverting underscores to spaces. General field options --------------------- Each type of field takes a different set of arguments, but some arguments are common to all field types. These arguments are: ====================== =================================================== Argument Description ====================== =================================================== ``blank`` If ``True``, the field is allowed to be blank. Note that this is different from ``null`` in that string fields will store the empty string instead of ``NULL`` internally. This means that to create a field that stores nulls you must pass ``blank=True`` and ``null=True``. ``choices`` A list 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:: YEAR_IN_SCHOOL_CHOICES = ( ('FR', 'Freshman'), ('SO', 'Sophomore'), ('JR', 'Junior'), ('SR', 'Senior'), ('GR', 'Graduate'), ) The first element in each tuple is the actual value to be stored. The second element is the human-readable name for the option. ``core`` For objects that are edited inline to a related object. If all "core" fields in an inline-edited object are cleared, the object will be considered to be deleted. It is an error to have an inline-editable relation without at least one core field. ``db_index`` If ``True``, the SQL generator will create a database index on this field. ``default`` The default value for the field. ``editable`` ``True`` by default. If this is set to ``False``, the field will not be editable in the admin. ``help_text`` Extra "help" text to be displayed under the field on the object's admin form. ``null`` If ``True``, empty values in the field will be stored as ``NULL`` in the database. ``primary_key`` If ``True``, this field is the primary key for the table. You only need to use this if you don't want the standard "id" field created and used as the primary key. Implies ``blank=False``, ``null=False``, and ``unique=True``. Only one primary key is allowed on an object. ``radio_admin`` If ``choices`` is given, or if the field is a ManyToOne relation, use a radio-button interface for the choices instead of the standard select-box interface. ``unique`` If ``True``, this field must be unique throughout the table. This is enforced at the database level and at the Django admin-form level. ``unique_for_date`` Set this to the name of a ``DateField`` or ``DateTimeField`` to require that this field be unique for the value of the date field. For example, if you have a field ``title`` that has ``unique_for_date="pub_date"``, then it is an error to have two rows with the same ``title`` and the same ``pub_date``. ``unique_for_month`` Like ``unique_for_date``, but requires the field to be unique with respect to the month. ``unique_for_year`` Like ``unique_for_date`` and ``unique_for_month``. ``validator_list`` A list of extra validators to apply to the field. ====================== =================================================== Field Types ----------- ``AutoField`` An ``IntegerField`` that automatically increments. You usually won't need to use this directly; a primary key field will automatically be added to your model if you don't specify otherwise. That automatically-added field is:: meta.AutoField('id', primary_key=True) ``BooleanField`` A true/false field. ``CharField`` A text field. These are displayed in the admin as single-line text inputs, so for large amounts of text, use a ``TextField``. ``CharField``s have an extra required argument: ``maxlength``, the maximum length (in characters) of the field. The maxlength is enforced at the database level and in Django's admin validation. ``CommaSeparatedIntegerField`` A field of integers separated by commas. As in ``CharField``s, the ``maxlength`` argument is required. ``DateField`` A date field. Has a few extra optional arguments: ====================== =================================================== Argument Description ====================== =================================================== ``auto_now`` Automatically set the field to now every time the object is saved. Useful for "last-modified" timestamps. ``auto_now_add`` Automatically set the field to now when the object is first created. Useful for creation of timestamps. ====================== =================================================== ``DateTimeField`` A date and time field. Takes the same extra options as ``DateField``. ``EmailField`` A ``CharField`` that checks that the value is a valid e-mail address. Because validating e-mail addresses can be tricky, this is a pretty loose test. ``FileField`` A file-upload field. Takes an additional option, ``upload_to``, which is a local filesystem path to upload the file to. This path may contain `strftime formatting`_, which will be replaced by the date/time of the file upload (so that uploaded files don't fill up the given directory). .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 ``FloatField`` A floating-point number. Has two **required** arguments: ====================== =================================================== Argument Description ====================== =================================================== ``max_digits`` The maximum number of digits allowed in the number. ``decimal_places`` The number of decimal places to store with the number ====================== =================================================== For example, to store numbers up to 999 with a resolution of 2 decimal places, you'd use:: meta.FloatField(..., max_digits=5, decimal_places=2) And to store numbers up to one million with a resolution of 10 decimal places:: meta.FloatField(..., max_digits=19, decimal_places=10) ``ForeignKey`` A many-to-one relationship to the primary key in another object. So, to give a ``Topping`` object a many-to-one relationship to ``Pizza`` (i.e. there are many toppings on a pizza):: meta.ForeignKey(Pizza) .. admonition:: Note To create a recursive relationship, use a ``ForeignKey`` that relates to ``"self"`` (i.e. ``meta.ForeignKey("self")``). ``ForeignKey`` fields take a large number of extra arguments for defining how the relationship should work. All are optional: ======================= ============================================================ Argument Description ======================= ============================================================ ``edit_inline`` If not ``False``, this related object is edited "inline" on the related object's page. This means that the object will not have its own admin interface. Use either ``meta.TABULAR`` or ``meta.STACKED``, which, respectively, designate whether the inline-editable objects are displayed as a table or as a "stack" of fieldsets. ``limit_choices_to`` A dictionary of lookup arguments and values (see the `Database API reference`_) that limit the available admin choices for this object. Use this with ``meta.LazyDate`` to limit choices of objects by date. For example:: limit_choices_to = {'pub_date__lte' : meta.LazyDate()} only allows the choice of related objects with a ``pub_date`` before the current date/time to be chosen. Not compatible with ``edit_inline``. ``max_num_in_admin`` For inline-edited objects, this is the maximum number of related objects to display in the admin. Thus, if a pizza could only have up to 10 toppings, ``max_num_in_admin=10`` would ensure that a user never enters more than 10 toppings. Note that this doesn't ensure more than 10 related toppings ever get created. It just controls the interface. ``min_num_in_admin`` The minimum number of related objects displayed in the admin. Normally, at the creation stage, ``num_in_admin`` inline objects are shown, and at the edit stage ``num_extra_on_change`` blank objects are shown in addition to all pre-existing related objects. However, no fewer than ``min_num_in_admin`` related objects will ever be displayed. ``num_extra_on_change`` The number of extra blank related-object fields to show at the change stage. ``num_in_admin`` The default number of inline objects to display on the object page at the add stage. ``raw_id_admin`` Only display a field for the integer to be entered instead of a drop-down menu. This is useful when related to an object type that will have too many rows to make a select box practical. Not used with ``edit_inline``. ``rel_name`` The name of the relation. In the above example, this would default to 'pizza' (so that the ``Toppings`` object would have a ``get_pizza()`` function. If you set ``rel_name`` to "pie", then the function would be called ``get_pie()`` and the field name would be ``pie_id``. ``related_name`` The name to use for the relation from the related object back to this one. For example, when if ``Topping`` has this field:: meta.ForeignKey(Pizza) the ``related_name`` will be "topping" (taken from the class name which will in turn give ``Pizza`` methods like ``get_topping_list()`` and ``get_topping_count()``. If you instead were to use:: meta.ForeignKey(Pizza, related_name="munchie") then the methods would be called ``get_munchie_list()``, ``get_munchie_count()``, etc. This is only really useful when you have a single object that relates to the same object more than once. For example, if a ``Story`` object has both ``primary_category`` and ``secondary_category`` fields, to make sure that the category objects have the correct methods, you'd use fields like:: ... meta.ForeignKey(Category, name="primary_category_id", rel_name="primary_category", related_name="primary_story"), meta.ForeignKey(Category, name="secondary_category_id", rel_name="secondary_category", related_name="secondary_story"), ... which would give the category objects methods named ``get_primary_story_list()`` and ``get_secondary_story_list()``. ``to_field`` The field on the related object that the relation is to. This is almost always ``id``, but if the primary key on the other object is named something different, this is how to indicate that. ======================= ============================================================ .. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/ ``ImageField`` Like a ``FileField``, but validates that the uploaded object is a valid image. Has two extra optional arguments, ``height_field`` and ``width_field`` which, if set, will be auto-populated with the height and width of the image. Requires the `Python Imaging Library`_. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ ``IntegerField`` An integer. ``IPAddressField`` An IP address, in string format (i.e. "24.124.1.30"). ``ManyToManyField`` A many-to-many relation to another object. For example (taken from the ``core.flatfiles`` object:: class FlatFile(meta.Model): fields = ( ... meta.ManyToManyField(Site), ) Many-to-many relations are a bit different from other fields. First, they aren't actually a field per se, because they use a intermediary join table. Second, they don't take the same options as the rest of the fields. The only arguments taken are: ======================= ============================================================ Argument Description ======================= ============================================================ ``rel_name`` Use this if you have more than one ``ForeignKey`` in the same model that relate to the same model. Django will use ``rel_name`` in the generated API. ``related_name`` See the description of ``related_name`` in ``ForeignKey``, above. ``filter_interface`` Use a nifty unobtrusive Javascript "filter" interface instead of the usability-challenged ``