From 5e309eb6e4e140590fb4567b138325bbab7eca71 Mon Sep 17 00:00:00 2001 From: Adrian Holovaty Date: Sun, 17 Jul 2005 04:20:57 +0000 Subject: [PATCH] Copy-edited model-API docs git-svn-id: http://code.djangoproject.com/svn/django/trunk@136 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/model-api.txt | 767 +++++++++++++++++++++++---------------------- 1 file changed, 390 insertions(+), 377 deletions(-) diff --git a/docs/model-api.txt b/docs/model-api.txt index e4d059d1c14..1d54135fdb6 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -2,123 +2,124 @@ 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 all of them. +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 possible options, only ``fields`` is required. +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 not given, this will use ``app_label + '_' + module_name``. - + + 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:: - + A list of field objects. See `Field objects`_. For example:: + fields = ( meta.CharField('customer_name', 'customer name', maxlength=15), meta.BooleanField('use_extra_cheese', 'use extra cheese'), meta.IntegerField('customer_type', 'customer type', choices=CUSTOMER_TYPE_CHOICES), ... ) - + ``get_latest_by`` - The name of a date or datetime field; if given, the module will have a - ``get_latest()`` function which fetches the "latest" object in terms of - that field:: - + 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 dict of name/values to use as extra module-level 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 not given this will use a lowercased version of the class name. - + + 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 tho object:: - + The default ordering for the object, for use by ``get_list`` and the admin:: + ordering = (('order_date', 'DESC'),) - - This is a tuple of 2-tuples; each 2-tuple is ``(field_name, ordering_type)`` - where ordering_type is either ``"ASC"`` or ``"DESC"``. You may also use the - magic ``(None, "RANDOM")`` ordering tuple for random ordering. - + + This is a tuple of 2-tuples. Each 2-tuple is ``(field_name, ordering_type)`` + where ordering_type is either ``"ASC"`` or ``"DESC"``. You can also use the + ``(None, "RANDOM")`` for random ordering. + ``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 = (("may_delivier_pizzas", "Can deliver pizzas"),) - - This is a list of 2-tuples of + object. A add, delete, and change permission is automatically created for + each object. This option specifies extra permissions:: + + permissions = (("can_delivier_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. - + together. It's used in the Django admin. + ``verbose_name`` A human-readable name for the object, singular:: - + verbose_name = "pizza" - - If not given, this will use a munged version of the class name: + + 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 not given, ``verbose_name + "s"`` will automatically be used. - + + 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 +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 @@ -130,24 +131,25 @@ contain spaces, punctuation, etc. General field options --------------------- -Each type of field takes a different set of options, but there are some -options that are common to all field types. These options are: +Each type of field takes a different set of options, but some options are +common to all field types. These options are: ====================== =================================================== Option Description ====================== =================================================== - ``blank`` If ``True``, the field is allowed to be blank. + ``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 + ``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, instead of the standard - field a option menu will be used, limiting choices - to the choices given. A choices list looks like:: - + 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'), @@ -155,317 +157,322 @@ options that are common to all field types. These options are: ('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. - + 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 set to ``False`` the field - will not be editable in the admin. - - ``help_text`` Extra "help" text to be displayed with the field. - - ``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 + + ``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 each 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 options - menu interface. - - ``unique`` If ``True`` this field must be unique throughout - the table. - - ``unique_for_date`` Set this to the name of a ``DateField`` or + ``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. That - is, if you have a field, ``title`` that has + 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`` - but, well, you get the idea. - - ``validator_list`` A list of extra validators to apply to the field. - See the `Form fields guide`_ for information about - validators. - ====================== =================================================== -.. _`Form fields guide`: http://www.djangoproject.com/FIXME/ + ``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:: - + 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', '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. - + 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. - + ``DateField`` - A, um, date field. Has a few extra optional options: - + A date field. Has a few extra optional options: + ====================== =================================================== Option Description ====================== =================================================== ``auto_now`` Automatically set the field to now every time the - object is saved. Useful for "last-modified" + 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 timestamps. + 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 email address. Because - validating email addresses can be tricky, this is a pretty loose test. - + 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 on additional option, ``upload_to`` which is - a 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). - + 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 additional required options: - + A floating-point number. Has two additional required options: + ====================== =================================================== Option 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 + 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) - + ``ForeignKey`` fields take a large number of extra options for defining how the relationship should work: - + ======================= ============================================================ Option Description ======================= ============================================================ - ``edit_inline`` If ``True``, this related object is edited - "inline" on the related object's page. This means - that the object will not have its own admin - interface. - - ``edit_inline_type`` This is either ``meta.TABULAR`` or - ``meta.STACKED`` and controls weather the inline + ``edit_inline`` If ``True``, this related object is edited + "inline" on the related object's page. This means + that the object will not have its own admin + interface. + + ``edit_inline_type`` This is either ``meta.TABULAR`` or + ``meta.STACKED`` and controls whether the inline editable objects are displayed as a table or as - a "stack" of fieldsets. Defaults to + a "stack" of fieldsets. Defaults to ``meta.STACKED``. - + ``limit_choices_to`` A dictionary of lookup arguments and values (see - the `Database API reference`_) to limit choices - of this object to. Use this along with - ``meta.LazyDate`` to limit choices of objects - by date, for example:: - + 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 + 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. - + 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 + the admin. Normally, at the creation stage, ``num_in_admin`` inline objects are shown, and at - the edit stage ``num_extra_on_change`` objects are - shown in addition to all pre-existing related - objects. However, no fewer than + 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 + + ``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 + instead of a drop-down menu. This is useful when related to an object type that will have too many - rows to make a menu practical. - + 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 + + ``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 + 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()``. - + 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`` + ``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 + + 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 - PK on the other object is named something + 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/ - +.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/ + ``ImageField`` - Like a ``FieldField``, but validates that the uploaded object is a valid - image. Has two extra optional arguments, ``height_field`` and ``width_field`` + Like a ``FieldField``, 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, surprisingly. - + 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 since they use a intermediary join table. - Second, they don't take any of the same options as the rest of the fields, - the only options taken are: - + aren't actually a field per se, because they use a intermediary join table. + Second, they don't take any of the same options as the rest of the fields. + The only options taken are: + ======================= ============================================================ Option Description ======================= ============================================================ - ``related_name`` See the description of ``related_name`` in + ``related_name`` See the description of ``related_name`` in ``ManyToOneField``, above. - - ``filter_interface`` Use a nifty unobtrusive Javascript "filter" interface - instead of the usability-challenged ```` + in the admin form for this object. The value should be + ``meta.HORIZONTAL`` or ``meta.VERTICAL`` (i.e. + should the interface be stacked horizontally or vertically). - + ``limit_choices_to`` See the description under ``ManyToOneField``, above. ======================= ============================================================ ``NullBooleanField`` Like a ``BooleanField``, but allows ``NULL`` as one of the options. Use this - instead of a ``BooleanField`` with ``null=True`` . - + instead of a ``BooleanField`` with ``null=True``. + ``OneToOneField`` Signifies a one-to-one relationship. This is most useful on the primary key - of an object when that object "extends" another object in some way. - + of an object when that object "extends" another object in some way. + For example, if you are building a database of "places", you would build pretty standard stuff like address, phone number, etc. in the database. If you then wanted to build a database of restaurants on top of the places, instead of @@ -474,237 +481,246 @@ Field Types a restaurant "is-a" place). This ``OneToOneField`` will actually replace the primary key ``id`` field (since one-to-one relations share the same primary key), and has a few in the admin interface: - + * No selection interface is displayed on ``Restaurant`` pages; there will be one (and only one) ``Restaurant`` for each place. - + * On the ``Restaurant`` change list, every single ``Place`` -- weather it - has an associated ``Restaurant`` or not -- will be displayed. Adding + has an associated ``Restaurant`` or not -- will be displayed. Adding a ``Restaurant`` to a ``Place`` just means filling out the required ``Restaurant`` fields. ``PhoneNumberField`` Validates that the value is a valid phone number. - + ``PositiveIntegerField`` Like an ``IntegerField``, but must be positive. - + ``PositiveSmallIntegerField`` - Like a ``PositiveIntegerField``, but only allows values below 32767. - + Like a ``PositiveIntegerField``, but only allows values under a certain + (database-dependent) point. + ``SlugField`` - A "slug" suitable for parts of a URL; only allows alpha-numeric characters and - underscores. - + A "slug," suitable for parts of a URL. Only allows alphanumeric characters + and underscores. + Implies ``maxlength=50`` and ``db_index=True``. - - Accepts an extra option, ``prepopulate_from`` which is a list of fields from - which to auto-populate the slug. - + + Accepts an extra option, ``prepopulate_from``, which is a list of fields + from which to auto-populate the slug, via JavaScript, in the object's admin + form. + ``SmallIntegerField`` - Like an ``IntegerField``, but must be between -32768 and 32767. - + Like an ``IntegerField``, but only allows values under a certain + (database-dependent) point. + ``TextField`` A large text field (``