=============== Model reference =============== A model is the single, definitive source of data about your data. It contains the essential fields and behaviors of the data you're storing. Generally, each model maps to a single database table. The basics: * Each model is a Python class that subclasses ``django.db.models.Model``. * Each attribute of the model represents a database field. * Model metadata (non-field information) goes in an inner class named ``Meta``. * Metadata used for Django's admin site goes into an inner class named ``Admin``. * With all of this, Django gives you an automatically-generated database-access API, which is explained in the `Database API reference`_. A companion to this document is the `official repository of model examples`_. (In the Django source distribution, these examples are in the ``tests/modeltests`` directory.) .. _Database API reference: ../db-api/ .. _official repository of model examples: http://www.djangoproject.com/documentation/models/ Quick example ============= This example model defines a ``Person``, which has a ``first_name`` and ``last_name``:: from django.db import models class Person(models.Model): first_name = models.CharField(maxlength=30) last_name = models.CharField(maxlength=30) ``first_name`` and ``last_name`` are *fields* of the model. Each field is specified as a class attribute, and each attribute maps to a database column. The above ``Person`` model would create a database table like this:: CREATE TABLE myapp_person ( "id" serial NOT NULL PRIMARY KEY, "first_name" varchar(30) NOT NULL, "last_name" varchar(30) NOT NULL ); Some technical notes: * The name of the table, ``myapp_person``, is automatically derived from some model metadata but can be overridden. See _`Table names` below. * An ``id`` field is added automatically, but this behavior can be overriden. See `Automatic primary key fields`_ below. * The ``CREATE TABLE`` SQL in this example is formatted using PostgreSQL syntax, but it's worth noting Django uses SQL tailored to the database backend specified in your `settings file`_. .. _settings file: ../settings/ Fields ====== The most important part of a model -- and the only required part of a model -- is the list of database fields it defines. Fields are specified by class attributes. Example:: class Musician(models.Model): first_name = models.CharField(maxlength=50) last_name = models.CharField(maxlength=50) instrument = models.CharField(maxlength=100) class Album(models.Model): artist = models.ForeignKey(Musician) name = models.CharField(maxlength=100) release_date = models.DateField() num_stars = models.IntegerField() Field name restrictions ----------------------- Django places only two restrictions on model field names: 1. A field name cannot be a Python reserved word, because that would result in a Python syntax error. For example:: class Example(models.Model): pass = models.IntegerField() # 'pass' is a reserved word! 2. A field name cannot contain more than one underscore in a row, due to the way Django's query lookup syntax works. For example:: class Example(models.Model): foo__bar = models.IntegerField() # 'foo__bar' has two underscores! These limitations can be worked around, though, because your field name doesn't necessarily have to match your database column name. See `db_column`_ below. SQL reserved words, such as ``join``, ``where`` or ``select``, *are* allowed as model field names, because Django escapes all database table names and column names in every underlying SQL query. It uses the quoting syntax of your particular database engine. Field types ----------- Each field in your model should be an instance of the appropriate ``Field`` class. Django uses the field class types to determine a few things: * The database column type (e.g. ``INTEGER``, ``VARCHAR``). * The widget to use in Django's admin interface, if you care to use it (e.g. ````, ```` (a single-line input). ``CharField`` has an extra required argument, ``maxlength``, the maximum length (in characters) of the field. The maxlength is enforced at the database level and in Django's validation. ``CommaSeparatedIntegerField`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A field of integers separated by commas. As in ``CharField``, the ``maxlength`` argument is required. ``DateField`` ~~~~~~~~~~~~~ A date field. Has a few extra optional arguments: ====================== =================================================== Argument Description ====================== =================================================== ``auto_now`` Automatically set the field to now every time the object is saved. Useful for "last-modified" timestamps. Note that the current date is *always* used; it's not just a default value that you can override. ``auto_now_add`` Automatically set the field to now when the object is first created. Useful for creation of timestamps. Note that the current date is *always* used; it's not just a default value that you can override. ====================== =================================================== The admin represents this as an ```` with a JavaScript calendar and a shortcut for "Today." ``DateTimeField`` ~~~~~~~~~~~~~~~~~ A date and time field. Takes the same extra options as ``DateField``. The admin represents this as two ```` fields, with JavaScript shortcuts. ``DecimalField`` ~~~~~~~~~~~~~~ A fixed-precision decimal number, represented in Python by a ``Decimal`` instance. Has two **required** arguments: ====================== =================================================== Argument Description ====================== =================================================== ``max_digits`` The maximum number of digits allowed in the number. ``decimal_places`` The number of decimal places to store with the number. ====================== =================================================== For example, to store numbers up to 999 with a resolution of 2 decimal places, you'd use:: models.DecimalField(..., max_digits=5, decimal_places=2) And to store numbers up to approximately one billion with a resolution of 10 decimal places:: models.DecimalField(..., max_digits=19, decimal_places=10) The admin represents this as an ```` (a single-line input). ``EmailField`` ~~~~~~~~~~~~~~ A ``CharField`` that checks that the value is a valid e-mail address. This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to 75. ``FileField`` ~~~~~~~~~~~~~ A file-upload field. Has one **required** argument: ====================== =================================================== Argument Description ====================== =================================================== ``upload_to`` A local filesystem path that will be appended to your ``MEDIA_ROOT`` setting to determine the output of the ``get__url()`` helper function. ====================== =================================================== This path may contain `strftime formatting`_, which will be replaced by the date/time of the file upload (so that uploaded files don't fill up the given directory). The admin represents this field as an ```` (a file-upload widget). Using a ``FileField`` or an ``ImageField`` (see below) in a model takes a few steps: 1. In your settings file, you'll need to define ``MEDIA_ROOT`` as the full path to a directory where you'd like Django to store uploaded files. (For performance, these files are not stored in the database.) Define ``MEDIA_URL`` as the base public URL of that directory. Make sure that this directory is writable by the Web server's user account. 2. Add the ``FileField`` or ``ImageField`` to your model, making sure to define the ``upload_to`` option to tell Django to which subdirectory of ``MEDIA_ROOT`` it should upload files. 3. All that will be stored in your database is a path to the file (relative to ``MEDIA_ROOT``). You'll most likely want to use the convenience ``get__url`` function provided by Django. For example, if your ``ImageField`` is called ``mug_shot``, you can get the absolute URL to your image in a template with ``{{ object.get_mug_shot_url }}``. For example, say your ``MEDIA_ROOT`` is set to ``'/home/media'``, and ``upload_to`` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of ``upload_to`` is strftime formatting; ``'%Y'`` is the four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is the two-digit day. If you upload a file on Jan. 15, 2007, it will be saved in the directory ``/home/media/photos/2007/01/15``. Note that whenever you deal with uploaded files, you should pay close attention to where you're uploading them and what type of files they are, to avoid security holes. *Validate all uploaded files* so that you're sure the files are what you think they are. For example, if you blindly let somebody upload files, without validation, to a directory that's within your Web server's document root, then somebody could upload a CGI or PHP script and execute that script by visiting its URL on your site. Don't allow that. .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 ``FilePathField`` ~~~~~~~~~~~~~~~~~ A field whose choices are limited to the filenames in a certain directory on the filesystem. Has three special arguments, of which the first is **required**: ====================== =================================================== Argument Description ====================== =================================================== ``path`` Required. The absolute filesystem path to a directory from which this ``FilePathField`` should get its choices. Example: ``"/home/images"``. ``match`` Optional. A regular expression, as a string, that ``FilePathField`` will use to filter filenames. Note that the regex will be applied to the base filename, not the full path. Example: ``"foo.*\.txt^"``, which will match a file called ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``. ``recursive`` Optional. Either ``True`` or ``False``. Default is ``False``. Specifies whether all subdirectories of ``path`` should be included. ====================== =================================================== Of course, these arguments can be used together. The one potential gotcha is that ``match`` applies to the base filename, not the full path. So, this example:: FilePathField(path="/home/images", match="foo.*", recursive=True) ...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif`` because the ``match`` applies to the base filename (``foo.gif`` and ``bar.gif``). ``FloatField`` ~~~~~~~~~~~~~~ A floating-point number represented in Python by a ``float`` instance. The admin represents this as an ```` (a single-line input). ``ImageField`` ~~~~~~~~~~~~~~ Like ``FileField``, but validates that the uploaded object is a valid image. Has two extra optional arguments, ``height_field`` and ``width_field``, which, if set, will be auto-populated with the height and width of the image each time a model instance is saved. Requires the `Python Imaging Library`_. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ ``IntegerField`` ~~~~~~~~~~~~~~~~ An integer. The admin represents this as an ```` (a single-line input). ``IPAddressField`` ~~~~~~~~~~~~~~~~~~ An IP address, in string format (i.e. "24.124.1.30"). The admin represents this as an ```` (a single-line input). ``NullBooleanField`` ~~~~~~~~~~~~~~~~~~~~ Like a ``BooleanField``, but allows ``NULL`` as one of the options. Use this instead of a ``BooleanField`` with ``null=True``. The admin represents this as a ```` (a single-line input). ``SmallIntegerField`` ~~~~~~~~~~~~~~~~~~~~~ Like an ``IntegerField``, but only allows values under a certain (database-dependent) point. ``TextField`` ~~~~~~~~~~~~~ A large text field. The admin represents this as a ``