===================== Model field reference ===================== .. module:: django.db.models.fields :synopsis: Built-in field types. .. currentmodule:: django.db.models This document contains all the gory details about all the `field options`_ and `field types`_ Django's got to offer. .. seealso:: If the built-in fields don't do the trick, you can try :mod:`django.contrib.localflavor`, which contains assorted pieces of code that are useful for particular countries or cultures. Also, you can easily :doc:`write your own custom model fields `. .. note:: Technically, these models are defined in :mod:`django.db.models.fields`, but for convenience they're imported into :mod:`django.db.models`; the standard convention is to use ``from django.db import models`` and refer to fields as ``models.Field``. .. _common-model-field-options: Field options ============= The following arguments are available to all field types. All are optional. ``null`` -------- .. attribute:: Field.null If ``True``, Django will store empty values as ``NULL`` in the database. Default is ``False``. Note that empty string values will always get stored as empty strings, not as ``NULL``. Only use ``null=True`` for non-string fields such as integers, booleans and dates. For both types of fields, you will also need to set ``blank=True`` if you wish to permit empty values in forms, as the :attr:`~Field.null` parameter only affects database storage (see :attr:`~Field.blank`). Avoid using :attr:`~Field.null` on string-based fields such as :class:`CharField` and :class:`TextField` unless you have an excellent reason. If a string-based field has ``null=True``, that means it has two possible values for "no data": ``NULL``, and the empty string. In most cases, it's redundant to have two possible values for "no data;" Django convention is to use the empty string, not ``NULL``. .. note:: When using the Oracle database backend, the ``null=True`` option will be coerced for string-based fields that have the empty string as a possible value, and the value ``NULL`` will be stored to denote the empty string. If you want to accept :attr:`~Field.null` values with :class:`BooleanField`, use :class:`NullBooleanField` instead. ``blank`` --------- .. attribute:: 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 ``blank=True``, validation on Django's admin site will allow entry of an empty value. If a field has ``blank=False``, the field will be required. .. _field-choices: ``choices`` ----------- .. attribute:: 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'), ) The first element in each tuple is the actual value to be stored. The second element is the human-readable name for the option. The choices list can be defined either as part of your model class:: class Foo(models.Model): GENDER_CHOICES = ( ('M', 'Male'), ('F', 'Female'), ) gender = models.CharField(max_length=1, choices=GENDER_CHOICES) or outside your model class altogether:: GENDER_CHOICES = ( ('M', 'Male'), ('F', 'Female'), ) class Foo(models.Model): gender = models.CharField(max_length=1, choices=GENDER_CHOICES) You can also collect your available choices into named groups that can be used for organizational purposes:: MEDIA_CHOICES = ( ('Audio', ( ('vinyl', 'Vinyl'), ('cd', 'CD'), ) ), ('Video', ( ('vhs', 'VHS Tape'), ('dvd', 'DVD'), ) ), ('unknown', 'Unknown'), ) The first element in each tuple is the name to apply to the group. The second element is an iterable of 2-tuples, with each 2-tuple containing a value and a human-readable name for an option. Grouped options may be combined with ungrouped options within a single list (such as the `unknown` option in this example). For each model field that has :attr:`~Field.choices` set, Django will add a method to retrieve the human-readable name for the field's current value. See :meth:`~django.db.models.Model.get_FOO_display` in the database API documentation. Finally, note that choices can be any iterable object -- not necessarily a list or tuple. This lets you construct choices dynamically. But if you find yourself hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is meant for static data that doesn't change much, if ever. ``db_column`` ------------- .. attribute:: Field.db_column The name of the database column to use for this field. If this isn't given, Django will use the field's name. If your database column name is an SQL reserved word, or contains characters that aren't allowed in Python variable names -- notably, the hyphen -- that's OK. Django quotes column and table names behind the scenes. ``db_index`` ------------ .. attribute:: Field.db_index If ``True``, djadmin:`django-admin.py sqlindexes ` will output a ``CREATE INDEX`` statement for this field. ``db_tablespace`` ----------------- .. attribute:: Field.db_tablespace The name of the database tablespace to use for this field's index, if this field is indexed. The default is the project's :setting:`DEFAULT_INDEX_TABLESPACE` setting, if set, or the :attr:`~Field.db_tablespace` of the model, if any. If the backend doesn't support tablespaces, this option is ignored. ``default`` ----------- .. attribute:: 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. ``editable`` ------------ .. attribute:: Field.editable If ``False``, the field will not be editable in the admin or via forms automatically generated from the model class. Default is ``True``. ``error_messages`` ------------------ .. versionadded:: 1.2 .. attribute:: Field.error_messages The ``error_messages`` argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you want to override. Error message keys include ``null``, ``blank``, ``invalid``, ``invalid_choice``, and ``unique``. Additional error message keys are specified for each field in the `Field types`_ section below. ``help_text`` ------------- .. attribute:: 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. Note that this value is *not* HTML-escaped when it's displayed in the admin interface. This lets you include HTML in :attr:`~Field.help_text` if you so desire. For example:: help_text="Please use the following format: YYYY-MM-DD." Alternatively you can use plain text and ``django.utils.html.escape()`` to escape any HTML special characters. ``primary_key`` --------------- .. attribute:: Field.primary_key If ``True``, this field is the primary key for the model. If you don't specify ``primary_key=True`` 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 ``primary_key=True`` on any of your fields unless you want to override the default primary-key behavior. For more, see :ref:`automatic-primary-key-fields`. ``primary_key=True`` implies :attr:`null=False ` and :attr:`unique=True `. Only one primary key is allowed on an object. ``unique`` ---------- .. attribute:: Field.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. If you try to save a model with a duplicate value in a :attr:`~Field.unique` field, a :exc:`django.db.IntegrityError` will be raised by the model's :meth:`~django.db.models.Model.save` method. This option is valid on all field types except :class:`ManyToManyField` and :class:`FileField`. ``unique_for_date`` ------------------- .. attribute:: Field.unique_for_date Set this to the name of a :class:`DateField` or :class:`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 Django wouldn't allow the entry of two records with the same ``title`` and ``pub_date``. This is enforced at the Django admin-form level but not at the database level. ``unique_for_month`` -------------------- .. attribute:: Field.unique_for_month Like :attr:`~Field.unique_for_date`, but requires the field to be unique with respect to the month. ``unique_for_year`` ------------------- .. attribute:: Field.unique_for_year Like :attr:`~Field.unique_for_date` and :attr:`~Field.unique_for_month`. ``verbose_name`` ------------------- .. attribute:: Field.verbose_name A human-readable name for the field. If the verbose name isn't given, Django will automatically create it using the field's attribute name, converting underscores to spaces. See :ref:`Verbose field names `. ``validators`` ------------------- .. versionadded:: 1.2 .. attribute:: Field.validators A list of validators to run for this field.See the :doc:`validators documentation ` for more information. .. _model-field-types: Field types =========== .. currentmodule:: django.db.models ``AutoField`` ------------- .. class:: AutoField(**options) An :class:`IntegerField` that automatically increments according to available IDs. 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. See :ref:`automatic-primary-key-fields`. ``BigIntegerField`` ------------------- .. versionadded:: 1.2 .. class:: BigIntegerField([**options]) A 64 bit integer, much like an :class:`IntegerField` except that it is guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The admin represents this as an ```` (a single-line input). ``BooleanField`` ---------------- .. class:: BooleanField(**options) A true/false field. The admin represents this as a checkbox. If you need to accept :attr:`~Field.null` values then use :class:`NullBooleanField` instead. .. versionchanged:: 1.2 In previous versions of Django when running under MySQL ``BooleanFields`` would return their data as ``ints``, instead of true ``bools``. See the release notes for a complete description of the change. ``CharField`` ------------- .. class:: CharField(max_length=None, [**options]) A string field, for small- to large-sized strings. For large amounts of text, use :class:`~django.db.models.TextField`. The admin represents this as an ```` (a single-line input). :class:`CharField` has one extra required argument: .. attribute:: CharField.max_length The maximum length (in characters) of the field. The max_length is enforced at the database level and in Django's validation. .. note:: If you are writing an application that must be portable to multiple database backends, you should be aware that there are restrictions on ``max_length`` for some backends. Refer to the :doc:`database backend notes ` for details. .. admonition:: MySQL users If you are using this field with MySQLdb 1.2.2 and the ``utf8_bin`` collation (which is *not* the default), there are some issues to be aware of. Refer to the :ref:`MySQL database notes ` for details. ``CommaSeparatedIntegerField`` ------------------------------ .. class:: CommaSeparatedIntegerField(max_length=None, [**options]) A field of integers separated by commas. As in :class:`CharField`, the :attr:`~CharField.max_length` argument is required and the note about database portability mentioned there should be heeded. ``DateField`` ------------- .. class:: DateField([auto_now=False, auto_now_add=False, **options]) A date, represented in Python by a ``datetime.date`` instance. Has a few extra, optional arguments: .. attribute:: DateField.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. .. attribute:: DateField.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". Includes an additional ``invalid_date`` error message key. .. note:: As currently implemented, setting ``auto_now`` or ``auto_now_add`` to ``True`` will cause the field to have ``editable=False`` and ``blank=True`` set. ``DateTimeField`` ----------------- .. class:: DateTimeField([auto_now=False, auto_now_add=False, **options]) A date and time, represented in Python by a ``datetime.datetime`` instance. Takes the same extra arguments as :class:`DateField`. The admin represents this as two ```` fields, with JavaScript shortcuts. ``DecimalField`` ---------------- .. class:: DecimalField(max_digits=None, decimal_places=None, [**options]) A fixed-precision decimal number, represented in Python by a :class:`~decimal.Decimal` instance. Has two **required** arguments: .. attribute:: DecimalField.max_digits The maximum number of digits allowed in the number. Note that this number must be greater than ``decimal_places``, if it exists. .. attribute:: DecimalField.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). .. note:: For more information about the differences between the :class:`FloatField` and :class:`DecimalField` classes, please see :ref:`FloatField vs. DecimalField `. ``EmailField`` -------------- .. class:: EmailField([max_length=75, **options]) A :class:`CharField` that checks that the value is a valid email address. ``FileField`` ------------- .. class:: FileField(upload_to=None, [max_length=100, **options]) A file-upload field. .. note:: The ``primary_key`` and ``unique`` arguments are not supported, and will raise a ``TypeError`` if used. Has one **required** argument: .. attribute:: FileField.upload_to A local filesystem path that will be appended to your :setting:`MEDIA_ROOT` setting to determine the value of the :attr:`~django.core.files.File.url` attribute. 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). This may also be a callable, such as a function, which will be called to obtain the upload path, including the filename. This callable must be able to accept two arguments, and return a Unix-style path (with forward slashes) to be passed along to the storage system. The two arguments that will be passed are: ====================== =============================================== Argument Description ====================== =============================================== ``instance`` An instance of the model where the ``FileField`` is defined. More specifically, this is the particular instance where the current file is being attached. In most cases, this object will not have been saved to the database yet, so if it uses the default ``AutoField``, *it might not yet have a value for its primary key field*. ``filename`` The filename that was originally given to the file. This may or may not be taken into account when determining the final destination path. ====================== =============================================== Also has one optional argument: .. attribute:: FileField.storage Optional. A storage object, which handles the storage and retrieval of your files. See :doc:`/topics/files` for details on how to provide this object. The admin represents this field as an ```` (a file-upload widget). Using a :class:`FileField` or an :class:`ImageField` (see below) in a model takes a few steps: 1. In your settings file, you'll need to define :setting:`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 :setting:`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 :class:`FileField` or :class:`ImageField` to your model, making sure to define the :attr:`~FileField.upload_to` option to tell Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload files. 3. All that will be stored in your database is a path to the file (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the convenience :attr:`~django.core.files.File.url` function provided by Django. For example, if your :class:`ImageField` is called ``mug_shot``, you can get the absolute path to your image in a template with ``{{ object.mug_shot.url }}``. For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of :attr:`~FileField.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``. If you wanted to retrieve the uploaded file's on-disk filename, or the file's size, you could use the :attr:`~django.core.files.File.name` and :attr:`~django.core.files.File.size` attributes respectively; for more information on the available attributes and methods, see the :class:`~django.core.files.File` class reference and the :doc:`/topics/files` topic guide. The uploaded file's relative URL can be obtained using the :attr:`~django.db.models.fields.FileField.url` attribute. Internally, this calls the :meth:`~django.core.files.storage.Storage.url` method of the underlying :class:`~django.core.files.storage.Storage` class. 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. By default, :class:`FileField` instances are created as ``varchar(100)`` columns in your database. As with other fields, you can change the maximum length using the :attr:`~CharField.max_length` argument. .. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime FileField and FieldFile ~~~~~~~~~~~~~~~~~~~~~~~ When you access a :class:`FileField` on a model, you are given an instance of :class:`FieldFile` as a proxy for accessing the underlying file. This class has several methods that can be used to interact with file data: .. method:: FieldFile.open(mode='rb') Behaves like the standard Python ``open()`` method and opens the file associated with this instance in the mode specified by ``mode``. .. method:: FieldFile.close() Behaves like the standard Python ``file.close()`` method and closes the file associated with this instance. .. method:: FieldFile.save(name, content, save=True) This method takes a filename and file contents and passes them to the storage class for the field, then associates the stored file with the model field. If you want to manually associate file data with :class:`FileField` instances on your model, the ``save()`` method is used to persist that file data. Takes two required arguments: ``name`` which is the name of the file, and ``content`` which is an object containing the file's contents. The optional ``save`` argument controls whether or not the instance is saved after the file has been altered. Defaults to ``True``. Note that the ``content`` argument should be an instance of :class:`django.core.files.File`, not Python's built-in file object. You can construct a :class:`~django.core.files.File` from an existing Python file object like this:: from django.core.files import File # Open an existing file using Python's built-in open() f = open('/tmp/hello.world') myfile = File(f) Or you can construct one from a Python string like this:: from django.core.files.base import ContentFile myfile = ContentFile("hello world") For more information, see :doc:`/topics/files`. .. method:: FieldFile.delete(save=True) Deletes the file associated with this instance and clears all attributes on the field. Note: This method will close the file if it happens to be open when ``delete()`` is called. The optional ``save`` argument controls whether or not the instance is saved after the file has been deleted. Defaults to ``True``. ``FilePathField`` ----------------- .. class:: FilePathField(path=None, [match=None, recursive=False, max_length=100, **options]) A :class:`CharField` whose choices are limited to the filenames in a certain directory on the filesystem. Has three special arguments, of which the first is **required**: .. attribute:: FilePathField.path Required. The absolute filesystem path to a directory from which this :class:`FilePathField` should get its choices. Example: ``"/home/images"``. .. attribute:: FilePathField.match Optional. A regular expression, as a string, that :class:`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``. .. attribute:: FilePathField.recursive Optional. Either ``True`` or ``False``. Default is ``False``. Specifies whether all subdirectories of :attr:`~FilePathField.path` should be included Of course, these arguments can be used together. The one potential gotcha is that :attr:`~FilePathField.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 :attr:`~FilePathField.match` applies to the base filename (``foo.gif`` and ``bar.gif``). By default, :class:`FilePathField` instances are created as ``varchar(100)`` columns in your database. As with other fields, you can change the maximum length using the :attr:`~CharField.max_length` argument. ``FloatField`` -------------- .. class:: FloatField([**options]) A floating-point number represented in Python by a ``float`` instance. The admin represents this as an ```` (a single-line input). .. _floatfield_vs_decimalfield: .. admonition:: ``FloatField`` vs. ``DecimalField`` The :class:`FloatField` class is sometimes mixed up with the :class:`DecimalField` class. Although they both represent real numbers, they represent those numbers differently. ``FloatField`` uses Python's ``float`` type internally, while ``DecimalField`` uses Python's ``Decimal`` type. For information on the difference between the two, see Python's documentation on `Decimal fixed point and floating point arithmetic`_. .. _Decimal fixed point and floating point arithmetic: http://docs.python.org/library/decimal.html ``ImageField`` -------------- .. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options]) Inherits all attributes and methods from :class:`FileField`, but also validates that the uploaded object is a valid image. In addition to the special attributes that are available for :class:`FileField`, an :class:`ImageField` also has :attr:`~django.core.files.File.height` and :attr:`~django.core.files.File.width` attributes. To facilitate querying on those attributes, :class:`ImageField` has two extra optional arguments: .. attribute:: ImageField.height_field Name of a model field which will be auto-populated with the height of the image each time the model instance is saved. .. attribute:: ImageField.width_field Name of a model field which will be auto-populated with the width of the image each time the model instance is saved. Requires the `Python Imaging Library`_. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ By default, :class:`ImageField` instances are created as ``varchar(100)`` columns in your database. As with other fields, you can change the maximum length using the :attr:`~CharField.max_length` argument. ``IntegerField`` ---------------- .. class:: IntegerField([**options]) An integer. The admin represents this as an ```` (a single-line input). ``IPAddressField`` ------------------ .. class:: IPAddressField([**options]) An IP address, in string format (e.g. "192.0.2.30"). The admin represents this as an ```` (a single-line input). ``NullBooleanField`` -------------------- .. class:: NullBooleanField([**options]) Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use this instead of a :class:`BooleanField` with ``null=True``. The admin represents this as a ``