diff options
Diffstat (limited to 'parts/django/docs/ref/models')
| -rw-r--r-- | parts/django/docs/ref/models/fields.txt | 1063 | ||||
| -rw-r--r-- | parts/django/docs/ref/models/index.txt | 14 | ||||
| -rw-r--r-- | parts/django/docs/ref/models/instances.txt | 570 | ||||
| -rw-r--r-- | parts/django/docs/ref/models/options.txt | 269 | ||||
| -rw-r--r-- | parts/django/docs/ref/models/querysets.txt | 1888 | ||||
| -rw-r--r-- | parts/django/docs/ref/models/relations.txt | 105 |
6 files changed, 3909 insertions, 0 deletions
diff --git a/parts/django/docs/ref/models/fields.txt b/parts/django/docs/ref/models/fields.txt new file mode 100644 index 0000000..146ca43 --- /dev/null +++ b/parts/django/docs/ref/models/fields.txt @@ -0,0 +1,1063 @@ +===================== +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 easily :doc:`write your + own custom model fields </howto/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.<Foo>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. + +``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 <sqlindexes>` will output a +``CREATE INDEX`` statement for this field. + +``db_tablespace`` +----------------- + +.. attribute:: Field.db_tablespace + +.. versionadded:: 1.0 + +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. + +``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: <em>YYYY-MM-DD</em>." + +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 <Field.null>` and :attr:`unique=True <Field.unique>`. +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 <verbose-field-names>`. + +``validators`` +------------------- + +.. versionadded:: 1.2 + +.. attribute:: Field.validators + +A list of validators to run for this field.See the :doc:`validators +documentation </ref/validators>` 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 ``<input type="text">`` (a single-line input). + + +``BooleanField`` +---------------- + +.. class:: BooleanField(**options) + +A true/false field. + +The admin represents this as a checkbox. + +.. 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 ``<input type="text">`` (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 </ref/databases>` 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 <mysql-collation>` 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 ``<input type="text">`` with a JavaScript +calendar, and a shortcut for "Today". The JavaScript calendar will always +start the week on a Sunday. + +.. note:: + As currently implemented, setting ``auto_now`` or ``auto_add_now`` 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 ``<input type="text">`` fields, with +JavaScript shortcuts. + +``DecimalField`` +---------------- + +.. versionadded:: 1.0 + +.. 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 + +.. 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 ``<input type="text">`` (a single-line input). + +``EmailField`` +-------------- + +.. class:: EmailField([max_length=75, **options]) + +A :class:`CharField` that checks that the value is a valid e-mail 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). + + .. versionchanged:: 1.0 + + 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 + + .. versionadded:: 1.0 + + 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 ``<input type="file">`` (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 want to retrieve the upload file's on-disk filename, or a URL that refers +to that file, or the file's size, you can use the +:attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url` +and :attr:`~django.core.files.File.size` attributes; see :doc:`/topics/files`. + +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. + +.. versionadded:: 1.0 + The ``max_length`` argument was added in this version. + +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 a file-like 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``. + +.. 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``). + +.. versionadded:: 1.0 + The ``max_length`` argument was added in this version. + +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]) + +.. versionchanged:: 1.0 + +A floating-point number represented in Python by a ``float`` instance. + +The admin represents this as an ``<input type="text">`` (a single-line input). + +``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/ + +.. versionadded:: 1.0 + The ``max_length`` argument was added in this version. + +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 ``<input type="text">`` (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 ``<input type="text">`` (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 ``<select>`` box with "Unknown", "Yes" and "No" choices. + +``PositiveIntegerField`` +------------------------ + +.. class:: PositiveIntegerField([**options]) + +Like an :class:`IntegerField`, but must be positive. + +``PositiveSmallIntegerField`` +----------------------------- + +.. class:: PositiveSmallIntegerField([**options]) + +Like a :class:`PositiveIntegerField`, but only allows values under a certain +(database-dependent) point. + +``SlugField`` +------------- + +.. class:: SlugField([max_length=50, **options]) + +:term:`Slug` is a newspaper term. A slug is a short label for something, +containing only letters, numbers, underscores or hyphens. They're generally used +in URLs. + +Like a CharField, you can specify :attr:`~CharField.max_length` (read the note +about database portability and :attr:`~CharField.max_length` in that section, +too). If :attr:`~CharField.max_length` is not specified, Django will use a +default length of 50. + +Implies setting :attr:`Field.db_index` to ``True``. + +It is often useful to automatically prepopulate a SlugField based on the value +of some other value. You can do this automatically in the admin using +:attr:`~django.contrib.admin.ModelAdmin.prepopulated_fields`. + +``SmallIntegerField`` +--------------------- + +.. class:: SmallIntegerField([**options]) + +Like an :class:`IntegerField`, but only allows values under a certain +(database-dependent) point. + +``TextField`` +------------- + +.. class:: TextField([**options]) + +A large text field. The admin represents this as a ``<textarea>`` (a multi-line +input). + +.. admonition:: MySQL users + + If you are using this field with MySQLdb 1.2.1p2 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 <mysql-collation>` for + details. + +``TimeField`` +------------- + +.. class:: TimeField([auto_now=False, auto_now_add=False, **options]) + +A time, represented in Python by a ``datetime.time`` instance. Accepts the same +auto-population options as :class:`DateField`. + +The admin represents this as an ``<input type="text">`` with some JavaScript +shortcuts. + +``URLField`` +------------ + +.. class:: URLField([verify_exists=True, max_length=200, **options]) + +A :class:`CharField` for a URL. Has one extra optional argument: + +.. attribute:: URLField.verify_exists + + If ``True`` (the default), the URL given will be checked for existence + (i.e., the URL actually loads and doesn't give a 404 response). + + Note that when you're using the single-threaded development server, + validating a URL being served by the same server will hang. This should not + be a problem for multithreaded servers. + +The admin represents this as an ``<input type="text">`` (a single-line input). + +Like all :class:`CharField` subclasses, :class:`URLField` takes the optional +:attr:`~CharField.max_length`argument. If you don't specify +:attr:`~CharField.max_length`, a default of 200 is used. + +``XMLField`` +------------ + +.. class:: XMLField(schema_path=None, [**options]) + +A :class:`TextField` that checks that the value is valid XML that matches a +given schema. Takes one required argument: + +.. attribute:: schema_path + + The filesystem path to a RelaxNG_ schema against which to validate the + field. + +.. _RelaxNG: http://www.relaxng.org/ + +Relationship fields +=================== + +.. module:: django.db.models.fields.related + :synopsis: Related field types + +.. currentmodule:: django.db.models + +Django also defines a set of fields that represent relations. + +.. _ref-foreignkey: + +``ForeignKey`` +-------------- + +.. class:: ForeignKey(othermodel, [**options]) + +A many-to-one relationship. Requires a positional argument: the class to which +the model is related. + +.. _recursive-relationships: + +To create a recursive relationship -- an object that has a many-to-one +relationship with itself -- use ``models.ForeignKey('self')``. + +.. _lazy-relationships: + +If you need to create a relationship on a model that has not yet been defined, +you can use the name of the model, rather than the model object itself:: + + class Car(models.Model): + manufacturer = models.ForeignKey('Manufacturer') + # ... + + class Manufacturer(models.Model): + # ... + +.. versionadded:: 1.0 + +To refer to models defined in another application, you can explicitly specify +a model with the full application label. For example, if the ``Manufacturer`` +model above is defined in another application called ``production``, you'd +need to use:: + + class Car(models.Model): + manufacturer = models.ForeignKey('production.Manufacturer') + +This sort of reference can be useful when resolving circular import +dependencies between two applications. + +Database Representation +~~~~~~~~~~~~~~~~~~~~~~~ + +Behind the scenes, Django appends ``"_id"`` to the field name to create its +database column name. In the above example, the database table for the ``Car`` +model will have a ``manufacturer_id`` column. (You can change this explicitly by +specifying :attr:`~Field.db_column`) However, your code should never have to +deal with the database column name, unless you write custom SQL. You'll always +deal with the field names of your model object. + +.. _foreign-key-arguments: + +Arguments +~~~~~~~~~ + +:class:`ForeignKey` accepts an extra set of arguments -- all optional -- that +define the details of how the relation works. + +.. attribute:: ForeignKey.limit_choices_to + + A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`) + that limit the available admin choices for this object. Use this with + functions from the Python ``datetime`` module to limit choices of objects by + date. For example:: + + limit_choices_to = {'pub_date__lte': datetime.now} + + only allows the choice of related objects with a ``pub_date`` before the + current date/time to be chosen. + + Instead of a dictionary this can also be a :class:`~django.db.models.Q` + object for more :ref:`complex queries <complex-lookups-with-q>`. However, + if ``limit_choices_to`` is a :class:`~django.db.models.Q` object then it + will only have an effect on the choices available in the admin when the + field is not listed in ``raw_id_fields`` in the ``ModelAdmin`` for the model. + +.. attribute:: ForeignKey.related_name + + The name to use for the relation from the related object back to this one. + See the :ref:`related objects documentation <backwards-related-objects>` for + a full explanation and example. Note that you must set this value + when defining relations on :ref:`abstract models + <abstract-base-classes>`; and when you do so + :ref:`some special syntax <abstract-related-name>` is available. + + If you wish to suppress the provision of a backwards relation, you may + simply provide a ``related_name`` which ends with a ``'+'`` character. + For example:: + + user = models.ForeignKey(User, related_name='+') + + will ensure that no backwards relation to this model is provided on the + ``User`` model. + +.. attribute:: ForeignKey.to_field + + The field on the related object that the relation is to. By default, Django + uses the primary key of the related object. + +.. _ref-manytomany: + +``ManyToManyField`` +------------------- + +.. class:: ManyToManyField(othermodel, [**options]) + +A many-to-many relationship. Requires a positional argument: the class to which +the model is related. This works exactly the same as it does for +:class:`ForeignKey`, including all the options regarding :ref:`recursive +<recursive-relationships>` and :ref:`lazy <lazy-relationships>` relationships. + +Database Representation +~~~~~~~~~~~~~~~~~~~~~~~ + +Behind the scenes, Django creates an intermediary join table to +represent the many-to-many relationship. By default, this table name +is generated using the name of the many-to-many field and the model +that contains it. Since some databases don't support table names above +a certain length, these table names will be automatically truncated to +64 characters and a uniqueness hash will be used. This means you might +see table names like ``author_books_9cdf4``; this is perfectly normal. +You can manually provide the name of the join table using the +:attr:`~ManyToManyField.db_table` option. + +.. _manytomany-arguments: + +Arguments +~~~~~~~~~ + +:class:`ManyToManyField` accepts an extra set of arguments -- all optional -- +that control how the relationship functions. + +.. attribute:: ManyToManyField.related_name + + Same as :attr:`ForeignKey.related_name`. + +.. attribute:: ManyToManyField.limit_choices_to + + Same as :attr:`ForeignKey.limit_choices_to`. + + ``limit_choices_to`` has no effect when used on a ``ManyToManyField`` with a + custom intermediate table specified using the + :attr:`~ManyToManyField.through` parameter. + +.. attribute:: ManyToManyField.symmetrical + + Only used in the definition of ManyToManyFields on self. Consider the + following model:: + + class Person(models.Model): + friends = models.ManyToManyField("self") + + When Django processes this model, it identifies that it has a + :class:`ManyToManyField` on itself, and as a result, it doesn't add a + ``person_set`` attribute to the ``Person`` class. Instead, the + :class:`ManyToManyField` is assumed to be symmetrical -- that is, if I am + your friend, then you are my friend. + + If you do not want symmetry in many-to-many relationships with ``self``, set + :attr:`~ManyToManyField.symmetrical` to ``False``. This will force Django to + add the descriptor for the reverse relationship, allowing + :class:`ManyToManyField` relationships to be non-symmetrical. + +.. attribute:: ManyToManyField.through + + Django will automatically generate a table to manage many-to-many + relationships. However, if you want to manually specify the intermediary + table, you can use the :attr:`~ManyToManyField.through` option to specify + the Django model that represents the intermediate table that you want to + use. + + The most common use for this option is when you want to associate + :ref:`extra data with a many-to-many relationship + <intermediary-manytomany>`. + +.. attribute:: ManyToManyField.db_table + + The name of the table to create for storing the many-to-many data. If this + is not provided, Django will assume a default name based upon the names of + the two tables being joined. + +.. _ref-onetoone: + +``OneToOneField`` +----------------- + +.. class:: OneToOneField(othermodel, [parent_link=False, **options]) + +A one-to-one relationship. Conceptually, this is similar to a +:class:`ForeignKey` with :attr:`unique=True <Field.unique>`, but the +"reverse" side of the relation will directly return a single object. + +This is most useful as the primary key of a model which "extends" +another model in some way; :ref:`multi-table-inheritance` is +implemented by adding an implicit one-to-one relation from the child +model to the parent model, for example. + +One positional argument is required: the class to which the model will be +related. This works exactly the same as it does for :class:`ForeignKey`, +including all the options regarding :ref:`recursive <recursive-relationships>` +and :ref:`lazy <lazy-relationships>` relationships. + +.. _onetoone-arguments: + +Additionally, ``OneToOneField`` accepts all of the extra arguments +accepted by :class:`ForeignKey`, plus one extra argument: + +.. attribute:: OneToOneField.parent_link + + When ``True`` and used in a model which inherits from another + (concrete) model, indicates that this field should be used as the + link back to the parent class, rather than the extra + ``OneToOneField`` which would normally be implicitly created by + subclassing. diff --git a/parts/django/docs/ref/models/index.txt b/parts/django/docs/ref/models/index.txt new file mode 100644 index 0000000..b5896c3 --- /dev/null +++ b/parts/django/docs/ref/models/index.txt @@ -0,0 +1,14 @@ +====== +Models +====== + +Model API reference. For introductory material, see :doc:`/topics/db/models`. + +.. toctree:: + :maxdepth: 1 + + fields + relations + options + instances + querysets diff --git a/parts/django/docs/ref/models/instances.txt b/parts/django/docs/ref/models/instances.txt new file mode 100644 index 0000000..1730ec6 --- /dev/null +++ b/parts/django/docs/ref/models/instances.txt @@ -0,0 +1,570 @@ +======================== +Model instance reference +======================== + +.. currentmodule:: django.db.models + +This document describes the details of the ``Model`` API. It builds on the +material presented in the :doc:`model </topics/db/models>` and :doc:`database +query </topics/db/queries>` guides, so you'll probably want to read and +understand those documents before reading this one. + +Throughout this reference we'll use the :ref:`example Weblog models +<queryset-model-example>` presented in the :doc:`database query guide +</topics/db/queries>`. + +Creating objects +================ + +To create a new instance of a model, just instantiate it like any other Python +class: + +.. class:: Model(**kwargs) + +The keyword arguments are simply the names of the fields you've defined on your +model. Note that instantiating a model in no way touches your database; for +that, you need to ``save()``. + +.. _validating-objects: + +Validating objects +================== + +.. versionadded:: 1.2 + +There are three steps involved in validating a model: + + 1. Validate the model fields + 2. Validate the model as a whole + 3. Validate the field uniqueness + +All three steps are performed when you call by a model's +``full_clean()`` method. + +When you use a ``ModelForm``, the call to ``is_valid()`` will perform +these validation steps for all the fields that are included on the +form. (See the :doc:`ModelForm documentation +</topics/forms/modelforms>` for more information.) You should only need +to call a model's ``full_clean()`` method if you plan to handle +validation errors yourself, or if you have excluded fields from the +ModelForm that require validation. + +.. method:: Model.full_clean(exclude=None) + +This method calls ``Model.clean_fields()``, ``Model.clean()``, and +``Model.validate_unique()``, in that order and raises a ``ValidationError`` +that has a ``message_dict`` attribute containing errors from all three stages. + +The optional ``exclude`` argument can be used to provide a list of field names +that can be excluded from validation and cleaning. ``ModelForm`` uses this +argument to exclude fields that aren't present on your form from being +validated since any errors raised could not be corrected by the user. + +Note that ``full_clean()`` will *not* be called automatically when you +call your model's ``save()`` method, nor as a result of ``ModelForm`` +validation. You'll need to call it manually when you want to run model +validation outside of a ``ModelForm``. + +Example:: + + try: + article.full_clean() + except ValidationError, e: + # Do something based on the errors contained in e.message_dict. + # Display them to a user, or handle them programatically. + +The first step ``full_clean()`` performs is to clean each individual field. + +.. method:: Model.clean_fields(exclude=None) + +This method will validate all fields on your model. The optional ``exclude`` +argument lets you provide a list of field names to exclude from validation. It +will raise a ``ValidationError`` if any fields fail validation. + +The second step ``full_clean()`` performs is to call ``Model.clean()``. +This method should be overridden to perform custom validation on your model. + +.. method:: Model.clean() + +This method should be used to provide custom model validation, and to modify +attributes on your model if desired. For instance, you could use it to +automatically provide a value for a field, or to do validation that requires +access to more than a single field:: + + def clean(self): + from django.core.exceptions import ValidationError + # Don't allow draft entries to have a pub_date. + if self.status == 'draft' and self.pub_date is not None: + raise ValidationError('Draft entries may not have a publication date.') + # Set the pub_date for published items if it hasn't been set already. + if self.status == 'published' and self.pub_date is None: + self.pub_date = datetime.datetime.now() + +Any ``ValidationError`` raised by ``Model.clean()`` will be stored under a +special key that is used for errors that are tied to the entire model instead +of to a specific field. You can access these errors with ``NON_FIELD_ERRORS``:: + + + from django.core.exceptions import ValidationError, NON_FIELD_ERRORS + try: + article.full_clean() + except ValidationError, e: + non_field_errors = e.message_dict[NON_FIELD_ERRORS] + +Finally, ``full_clean()`` will check any unique constraints on your model. + +.. method:: Model.validate_unique(exclude=None) + +This method is similar to ``clean_fields``, but validates all uniqueness +constraints on your model instead of individual field values. The optional +``exclude`` argument allows you to provide a list of field names to exclude +from validation. It will raise a ``ValidationError`` if any fields fail +validation. + +Note that if you provide an ``exclude`` argument to ``validate_unique``, any +``unique_together`` constraint that contains one of the fields you provided +will not be checked. + + +Saving objects +============== + +To save an object back to the database, call ``save()``: + +.. method:: Model.save([force_insert=False, force_update=False, using=DEFAULT_DB_ALIAS]) + +.. versionadded:: 1.0 + The ``force_insert`` and ``force_update`` arguments were added. + +.. versionadded:: 1.2 + The ``using`` argument was added. + +If you want customized saving behavior, you can override this +``save()`` method. See :ref:`overriding-model-methods` for more +details. + +The model save process also has some subtleties; see the sections +below. + +Auto-incrementing primary keys +------------------------------ + +If a model has an ``AutoField`` -- an auto-incrementing primary key -- then +that auto-incremented value will be calculated and saved as an attribute on +your object the first time you call ``save()``:: + + >>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.') + >>> b2.id # Returns None, because b doesn't have an ID yet. + >>> b2.save() + >>> b2.id # Returns the ID of your new object. + +There's no way to tell what the value of an ID will be before you call +``save()``, because that value is calculated by your database, not by Django. + +(For convenience, each model has an ``AutoField`` named ``id`` by default +unless you explicitly specify ``primary_key=True`` on a field. See the +documentation for ``AutoField`` for more details. + +The ``pk`` property +~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +.. attribute:: Model.pk + +Regardless of whether you define a primary key field yourself, or let Django +supply one for you, each model will have a property called ``pk``. It behaves +like a normal attribute on the model, but is actually an alias for whichever +attribute is the primary key field for the model. You can read and set this +value, just as you would for any other attribute, and it will update the +correct field in the model. + +Explicitly specifying auto-primary-key values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a model has an ``AutoField`` but you want to define a new object's ID +explicitly when saving, just define it explicitly before saving, rather than +relying on the auto-assignment of the ID:: + + >>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.') + >>> b3.id # Returns 3. + >>> b3.save() + >>> b3.id # Returns 3. + +If you assign auto-primary-key values manually, make sure not to use an +already-existing primary-key value! If you create a new object with an explicit +primary-key value that already exists in the database, Django will assume you're +changing the existing record rather than creating a new one. + +Given the above ``'Cheddar Talk'`` blog example, this example would override the +previous record in the database:: + + b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.') + b4.save() # Overrides the previous blog with ID=3! + +See `How Django knows to UPDATE vs. INSERT`_, below, for the reason this +happens. + +Explicitly specifying auto-primary-key values is mostly useful for bulk-saving +objects, when you're confident you won't have primary-key collision. + +What happens when you save? +--------------------------- + +When you save an object, Django performs the following steps: + + 1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>` + :attr:`django.db.models.signals.pre_save` is sent, allowing any + functions listening for that signal to take some customized + action. + + 2. **Pre-process the data.** Each field on the object is asked to + perform any automated data modification that the field may need + to perform. + + Most fields do *no* pre-processing -- the field data is kept as-is. + Pre-processing is only used on fields that have special behavior. + For example, if your model has a ``DateField`` with ``auto_now=True``, + the pre-save phase will alter the data in the object to ensure that + the date field contains the current date stamp. (Our documentation + doesn't yet include a list of all the fields with this "special + behavior.") + + 3. **Prepare the data for the database.** Each field is asked to provide + its current value in a data type that can be written to the database. + + Most fields require *no* data preparation. Simple data types, such as + integers and strings, are 'ready to write' as a Python object. However, + more complex data types often require some modification. + + For example, ``DateFields`` use a Python ``datetime`` object to store + data. Databases don't store ``datetime`` objects, so the field value + must be converted into an ISO-compliant date string for insertion + into the database. + + 4. **Insert the data into the database.** The pre-processed, prepared + data is then composed into an SQL statement for insertion into the + database. + + 5. **Emit a post-save signal.** The signal + :attr:`django.db.models.signals.post_save` is sent, allowing + any functions listening for that signal to take some customized + action. + +How Django knows to UPDATE vs. INSERT +------------------------------------- + +You may have noticed Django database objects use the same ``save()`` method +for creating and changing objects. Django abstracts the need to use ``INSERT`` +or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django +follows this algorithm: + + * If the object's primary key attribute is set to a value that evaluates to + ``True`` (i.e., a value other than ``None`` or the empty string), Django + executes a ``SELECT`` query to determine whether a record with the given + primary key already exists. + * If the record with the given primary key does already exist, Django + executes an ``UPDATE`` query. + * If the object's primary key attribute is *not* set, or if it's set but a + record doesn't exist, Django executes an ``INSERT``. + +The one gotcha here is that you should be careful not to specify a primary-key +value explicitly when saving new objects, if you cannot guarantee the +primary-key value is unused. For more on this nuance, see `Explicitly specifying +auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below. + +.. _ref-models-force-insert: + +Forcing an INSERT or UPDATE +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 1.0 + +In some rare circumstances, it's necessary to be able to force the ``save()`` +method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``. +Or vice-versa: update, if possible, but not insert a new row. In these cases +you can pass the ``force_insert=True`` or ``force_update=True`` parameters to +the ``save()`` method. Passing both parameters is an error, since you cannot +both insert *and* update at the same time. + +It should be very rare that you'll need to use these parameters. Django will +almost always do the right thing and trying to override that will lead to +errors that are difficult to track down. This feature is for advanced use +only. + +Updating attributes based on existing fields +-------------------------------------------- + +Sometimes you'll need to perform a simple arithmetic task on a field, such +as incrementing or decrementing the current value. The obvious way to +achieve this is to do something like:: + + >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') + >>> product.number_sold += 1 + >>> product.save() + +If the old ``number_sold`` value retrieved from the database was 10, then +the value of 11 will be written back to the database. + +This can be optimized slightly by expressing the update relative to the +original field value, rather than as an explicit assignment of a new value. +Django provides :ref:`F() expressions <query-expressions>` as a way of +performing this kind of relative update. Using ``F()`` expressions, the +previous example would be expressed as:: + + >>> from django.db.models import F + >>> product = Product.objects.get(name='Venezuelan Beaver Cheese') + >>> product.number_sold = F('number_sold') + 1 + >>> product.save() + +This approach doesn't use the initial value from the database. Instead, it +makes the database do the update based on whatever value is current at the +time that the save() is executed. + +Once the object has been saved, you must reload the object in order to access +the actual value that was applied to the updated field:: + + >>> product = Products.objects.get(pk=product.pk) + >>> print product.number_sold + 42 + +For more details, see the documentation on :ref:`F() expressions +<query-expressions>` and their :ref:`use in update queries +<topics-db-queries-update>`. + +Deleting objects +================ + +.. method:: Model.delete([using=DEFAULT_DB_ALIAS]) + +.. versionadded:: 1.2 + The ``using`` argument was added. + +Issues a SQL ``DELETE`` for the object. This only deletes the object +in the database; the Python instance will still be around, and will +still have data in its fields. + +For more details, including how to delete objects in bulk, see +:ref:`topics-db-queries-delete`. + +If you want customized deletion behavior, you can override this +``delete()`` method. See :ref:`overriding-model-methods` for more +details. + +.. _model-instance-methods: + +Other model instance methods +============================ + +A few object methods have special purposes. + +``__str__`` +----------- + +.. method:: Model.__str__() + +``__str__()`` is a Python "magic method" that defines what should be returned +if you call ``str()`` on the object. Django uses ``str(obj)`` (or the related +function, ``unicode(obj)`` -- see below) in a number of places, most notably +as the value displayed to render an object in the Django admin site and as the +value inserted into a template when it displays an object. Thus, you should +always return a nice, human-readable string for the object's ``__str__``. +Although this isn't required, it's strongly encouraged (see the description of +``__unicode__``, below, before putting ``__str__`` methods everywhere). + +For example:: + + class Person(models.Model): + first_name = models.CharField(max_length=50) + last_name = models.CharField(max_length=50) + + def __str__(self): + # Note use of django.utils.encoding.smart_str() here because + # first_name and last_name will be unicode strings. + return smart_str('%s %s' % (self.first_name, self.last_name)) + +``__unicode__`` +--------------- + +.. method:: Model.__unicode__() + +The ``__unicode__()`` method is called whenever you call ``unicode()`` on an +object. Since Django's database backends will return Unicode strings in your +model's attributes, you would normally want to write a ``__unicode__()`` +method for your model. The example in the previous section could be written +more simply as:: + + class Person(models.Model): + first_name = models.CharField(max_length=50) + last_name = models.CharField(max_length=50) + + def __unicode__(self): + return u'%s %s' % (self.first_name, self.last_name) + +If you define a ``__unicode__()`` method on your model and not a ``__str__()`` +method, Django will automatically provide you with a ``__str__()`` that calls +``__unicode__()`` and then converts the result correctly to a UTF-8 encoded +string object. This is recommended development practice: define only +``__unicode__()`` and let Django take care of the conversion to string objects +when required. + +``get_absolute_url`` +-------------------- + +.. method:: Model.get_absolute_url() + +Define a ``get_absolute_url()`` method to tell Django how to calculate the +URL for an object. For example:: + + def get_absolute_url(self): + return "/people/%i/" % self.id + +Django uses this in its admin interface. If an object defines +``get_absolute_url()``, the object-editing page will have a "View on site" +link that will jump you directly to the object's public view, according to +``get_absolute_url()``. + +Also, a couple of other bits of Django, such as the :doc:`syndication feed +framework </ref/contrib/syndication>`, use ``get_absolute_url()`` as a +convenience to reward people who've defined the method. + +It's good practice to use ``get_absolute_url()`` in templates, instead of +hard-coding your objects' URLs. For example, this template code is bad:: + + <a href="/people/{{ object.id }}/">{{ object.name }}</a> + +But this template code is good:: + + <a href="{{ object.get_absolute_url }}">{{ object.name }}</a> + +.. note:: + The string you return from ``get_absolute_url()`` must contain only ASCII + characters (required by the URI spec, `RFC 2396`_) that have been + URL-encoded, if necessary. Code and templates using ``get_absolute_url()`` + should be able to use the result directly without needing to do any + further processing. You may wish to use the + ``django.utils.encoding.iri_to_uri()`` function to help with this if you + are using unicode strings a lot. + +.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt + +The ``permalink`` decorator +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The problem with the way we wrote ``get_absolute_url()`` above is that it +slightly violates the DRY principle: the URL for this object is defined both +in the URLconf file and in the model. + +You can further decouple your models from the URLconf using the ``permalink`` +decorator: + +.. function:: permalink() + +This decorator is passed the view function, a list of positional parameters and +(optionally) a dictionary of named parameters. Django then works out the correct +full URL path using the URLconf, substituting the parameters you have given into +the URL. For example, if your URLconf contained a line such as:: + + (r'^people/(\d+)/$', 'people.views.details'), + +...your model could have a ``get_absolute_url`` method that looked like this:: + + from django.db import models + + @models.permalink + def get_absolute_url(self): + return ('people.views.details', [str(self.id)]) + +Similarly, if you had a URLconf entry that looked like:: + + (r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$', archive_view) + +...you could reference this using ``permalink()`` as follows:: + + @models.permalink + def get_absolute_url(self): + return ('archive_view', (), { + 'year': self.created.year, + 'month': self.created.month, + 'day': self.created.day}) + +Notice that we specify an empty sequence for the second parameter in this case, +because we only want to pass keyword parameters, not positional ones. + +In this way, you're tying the model's absolute path to the view that is used +to display it, without repeating the URL information anywhere. You can still +use the ``get_absolute_url`` method in templates, as before. + +In some cases, such as the use of generic views or the re-use of +custom views for multiple models, specifying the view function may +confuse the reverse URL matcher (because multiple patterns point to +the same view). + +For that problem, Django has **named URL patterns**. Using a named +URL pattern, it's possible to give a name to a pattern, and then +reference the name rather than the view function. A named URL +pattern is defined by replacing the pattern tuple by a call to +the ``url`` function):: + + from django.conf.urls.defaults import * + + url(r'^people/(\d+)/$', + 'django.views.generic.list_detail.object_detail', + name='people_view'), + +...and then using that name to perform the reverse URL resolution instead +of the view name:: + + from django.db import models + + @models.permalink + def get_absolute_url(self): + return ('people_view', [str(self.id)]) + +More details on named URL patterns are in the :doc:`URL dispatch documentation +</topics/http/urls>`. + +Extra instance methods +====================== + +In addition to ``save()``, ``delete()``, a model object might get any or all +of the following methods: + +.. method:: Model.get_FOO_display() + +For every field that has ``choices`` set, the object will have a +``get_FOO_display()`` method, where ``FOO`` is the name of the field. This +method returns the "human-readable" value of the field. For example, in the +following model:: + + GENDER_CHOICES = ( + ('M', 'Male'), + ('F', 'Female'), + ) + class Person(models.Model): + name = models.CharField(max_length=20) + gender = models.CharField(max_length=1, choices=GENDER_CHOICES) + +...each ``Person`` instance will have a ``get_gender_display()`` method. Example:: + + >>> p = Person(name='John', gender='M') + >>> p.save() + >>> p.gender + 'M' + >>> p.get_gender_display() + 'Male' + +.. method:: Model.get_next_by_FOO(\**kwargs) +.. method:: Model.get_previous_by_FOO(\**kwargs) + +For every ``DateField`` and ``DateTimeField`` that does not have ``null=True``, +the object will have ``get_next_by_FOO()`` and ``get_previous_by_FOO()`` +methods, where ``FOO`` is the name of the field. This returns the next and +previous object with respect to the date field, raising the appropriate +``DoesNotExist`` exception when appropriate. + +Both methods accept optional keyword arguments, which should be in the format +described in :ref:`Field lookups <field-lookups>`. + +Note that in the case of identical date values, these methods will use the ID +as a fallback check. This guarantees that no records are skipped or duplicated. diff --git a/parts/django/docs/ref/models/options.txt b/parts/django/docs/ref/models/options.txt new file mode 100644 index 0000000..1b04c46 --- /dev/null +++ b/parts/django/docs/ref/models/options.txt @@ -0,0 +1,269 @@ +====================== +Model ``Meta`` options +====================== + +This document explains all the possible :ref:`metadata options +<meta-options>` that you can give your model in its internal ``class +Meta``. + +Available ``Meta`` options +========================== + +.. currentmodule:: django.db.models + +``abstract`` +------------ + +.. attribute:: Options.abstract + +If ``True``, this model will be an :ref:`abstract base class <abstract-base-classes>`. + +``app_label`` +------------- + +.. attribute:: Options.app_label + +If a model exists outside of the standard :file:`models.py` (for instance, if +the app's models are in submodules of ``myapp.models``), the model must define +which app it is part of:: + + app_label = 'myapp' + +``db_table`` +------------ + +.. attribute:: Options.db_table + +The name of the database table to use for the model:: + + db_table = 'music_album' + +.. _table-names: + +Table names +~~~~~~~~~~~ + +To save you time, Django automatically derives the name of the database table +from the name of your model class and the app that contains it. A model's +database table name is constructed by joining the model's "app label" -- the +name you used in ``manage.py startapp`` -- to the model's class name, with an +underscore between them. + +For example, if you have an app ``bookstore`` (as created by +``manage.py startapp bookstore``), a model defined as ``class Book`` will have +a database table named ``bookstore_book``. + +To override the database table name, use the ``db_table`` parameter in +``class Meta``. + +If your database table 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_tablespace`` +----------------- + +.. attribute:: Options.db_tablespace + +.. versionadded:: 1.0 + +The name of the database tablespace to use for the model. If the backend doesn't +support tablespaces, this option is ignored. + +``get_latest_by`` +----------------- + +.. attribute:: Options.get_latest_by + +The name of a :class:`DateField` or :class:`DateTimeField` in the model. This +specifies the default field to use in your model :class:`Manager`'s +:class:`~QuerySet.latest` method. + +Example:: + + get_latest_by = "order_date" + +See the docs for :meth:`~django.db.models.QuerySet.latest` for more. + +``managed`` +----------------------- + +.. attribute:: Options.managed + +.. versionadded:: 1.1 + +Defaults to ``True``, meaning Django will create the appropriate database +tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`reset` +management command. That is, Django *manages* the database tables' lifecycles. + +If ``False``, no database table creation or deletion operations will be +performed for this model. This is useful if the model represents an existing +table or a database view that has been created by some other means. This is +the *only* difference when ``managed`` is ``False``. All other aspects of +model handling are exactly the same as normal. This includes + + 1. Adding an automatic primary key field to the model if you don't declare + it. To avoid confusion for later code readers, it's recommended to + specify all the columns from the database table you are modeling when + using unmanaged models. + + 2. If a model with ``managed=False`` contains a + :class:`~django.db.models.ManyToManyField` that points to another + unmanaged model, then the intermediate table for the many-to-many join + will also not be created. However, a the intermediary table between one + managed and one unmanaged model *will* be created. + + If you need to change this default behavior, create the intermediary + table as an explicit model (with ``managed`` set as needed) and use the + :attr:`ManyToManyField.through` attribute to make the relation use your + custom model. + +For tests involving models with ``managed=False``, it's up to you to ensure +the correct tables are created as part of the test setup. + +If you're interested in changing the Python-level behavior of a model class, +you *could* use ``managed=False`` and create a copy of an existing model. +However, there's a better approach for that situation: :ref:`proxy-models`. + +``order_with_respect_to`` +------------------------- + +.. attribute:: Options.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 an ``Answer`` relates to a ``Question`` object, +and a question has more than one answer, and the order of answers matters, you'd +do this:: + + class Answer(models.Model): + question = models.ForeignKey(Question) + # ... + + class Meta: + order_with_respect_to = 'question' + +When ``order_with_respect_to`` is set, two additional methods are provided to +retrieve and to set the order of the related objects: ``get_RELATED_order()`` +and ``set_RELATED_order()``, where ``RELATED`` is the lowercased model name. For +example, assuming that a ``Question`` object has multiple related ``Answer`` +objects, the list returned contains the primary keys of the related ``Answer`` +objects:: + + >>> question = Question.objects.get(id=1) + >>> question.get_answer_order() + [1, 2, 3] + +The order of a ``Question`` object's related ``Answer`` objects can be set by +passing in a list of ``Answer`` primary keys:: + + >>> question.set_answer_order([3, 1, 2]) + +The related objects also get two methods, ``get_next_in_order()`` and +``get_previous_in_order()``, which can be used to access those objects in their +proper order. Assuming the ``Answer`` objects are ordered by ``id``:: + + >>> answer = Answer.objects.get(id=2) + >>> answer.get_next_in_order() + <Answer: 3> + >>> answer.get_previous_in_order() + <Answer: 1> + +``ordering`` +------------ + +.. attribute:: Options.ordering + +The default ordering for the object, for use when obtaining lists of objects:: + + ordering = ['-order_date'] + +This is a tuple or list of strings. Each string is a field name with an optional +"-" prefix, which indicates descending order. Fields without a leading "-" will +be ordered ascending. Use the string "?" to order randomly. + +.. note:: + + Regardless of how many fields are in :attr:`~Options.ordering`, the admin + site uses only the first field. + +For example, to order by a ``pub_date`` field ascending, use this:: + + ordering = ['pub_date'] + +To order by ``pub_date`` descending, use this:: + + ordering = ['-pub_date'] + +To order by ``pub_date`` descending, then by ``author`` ascending, use this:: + + ordering = ['-pub_date', 'author'] + +``permissions`` +--------------- + +.. attribute:: Options.permissions + +Extra permissions to enter into the permissions table when creating this object. +Add, delete and change permissions are automatically created for each object +that has ``admin`` set. This example specifies an extra permission, +``can_deliver_pizzas``:: + + permissions = (("can_deliver_pizzas", "Can deliver pizzas"),) + +This is a list or tuple of 2-tuples in the format ``(permission_code, +human_readable_permission_name)``. + +``proxy`` +--------- + +.. attribute:: Options.proxy + +.. versionadded:: 1.1 + +If set to ``True``, a model which subclasses another model will be treated as +a :ref:`proxy model <proxy-models>`. + +``unique_together`` +------------------- + +.. attribute:: Options.unique_together + +Sets of field names that, taken together, must be unique:: + + unique_together = (("driver", "restaurant"),) + +This is a list of lists of fields that must be unique when considered together. +It's used in the Django admin and is enforced at the database level (i.e., the +appropriate ``UNIQUE`` statements are included in the ``CREATE TABLE`` +statement). + +.. versionadded:: 1.0 + +For convenience, unique_together can be a single list when dealing with a single +set of fields:: + + unique_together = ("driver", "restaurant") + +``verbose_name`` +---------------- + +.. attribute:: Options.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`` +----------------------- + +.. attribute:: Options.verbose_name_plural + +The plural name for the object:: + + verbose_name_plural = "stories" + +If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``. diff --git a/parts/django/docs/ref/models/querysets.txt b/parts/django/docs/ref/models/querysets.txt new file mode 100644 index 0000000..9f0de1f --- /dev/null +++ b/parts/django/docs/ref/models/querysets.txt @@ -0,0 +1,1888 @@ +====================== +QuerySet API reference +====================== + +.. currentmodule:: django.db.models.QuerySet + +This document describes the details of the ``QuerySet`` API. It builds on the +material presented in the :doc:`model </topics/db/models>` and :doc:`database +query </topics/db/queries>` guides, so you'll probably want to read and +understand those documents before reading this one. + +Throughout this reference we'll use the :ref:`example Weblog models +<queryset-model-example>` presented in the :doc:`database query guide +</topics/db/queries>`. + +.. _when-querysets-are-evaluated: + +When QuerySets are evaluated +============================ + +Internally, a ``QuerySet`` can be constructed, filtered, sliced, and generally +passed around without actually hitting the database. No database activity +actually occurs until you do something to evaluate the queryset. + +You can evaluate a ``QuerySet`` in the following ways: + + * **Iteration.** A ``QuerySet`` is iterable, and it executes its database + query the first time you iterate over it. For example, this will print + the headline of all entries in the database:: + + for e in Entry.objects.all(): + print e.headline + + * **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can + be sliced, using Python's array-slicing syntax. Usually slicing a + ``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will + execute the database query if you use the "step" parameter of slice + syntax. + + * **Pickling/Caching.** See the following section for details of what + is involved when `pickling QuerySets`_. The important thing for the + purposes of this section is that the results are read from the database. + + * **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it. + This is for convenience in the Python interactive interpreter, so you can + immediately see your results when using the API interactively. + + * **len().** A ``QuerySet`` is evaluated when you call ``len()`` on it. + This, as you might expect, returns the length of the result list. + + Note: *Don't* use ``len()`` on ``QuerySet``\s if all you want to do is + determine the number of records in the set. It's much more efficient to + handle a count at the database level, using SQL's ``SELECT COUNT(*)``, + and Django provides a ``count()`` method for precisely this reason. See + ``count()`` below. + + * **list().** Force evaluation of a ``QuerySet`` by calling ``list()`` on + it. For example:: + + entry_list = list(Entry.objects.all()) + + Be warned, though, that this could have a large memory overhead, because + Django will load each element of the list into memory. In contrast, + iterating over a ``QuerySet`` will take advantage of your database to + load data and instantiate objects only as you need them. + + * **bool().** Testing a ``QuerySet`` in a boolean context, such as using + ``bool()``, ``or``, ``and`` or an ``if`` statement, will cause the query + to be executed. If there is at least one result, the ``QuerySet`` is + ``True``, otherwise ``False``. For example:: + + if Entry.objects.filter(headline="Test"): + print "There is at least one Entry with the headline Test" + + Note: *Don't* use this if all you want to do is determine if at least one + result exists, and don't need the actual objects. It's more efficient to + use ``exists()`` (see below). + +.. _pickling QuerySets: + +Pickling QuerySets +------------------ + +If you pickle_ a ``QuerySet``, this will force all the results to be loaded +into memory prior to pickling. Pickling is usually used as a precursor to +caching and when the cached queryset is reloaded, you want the results to +already be present and ready for use (reading from the database can take some +time, defeating the purpose of caching). This means that when you unpickle a +``QuerySet``, it contains the results at the moment it was pickled, rather +than the results that are currently in the database. + +If you only want to pickle the necessary information to recreate the +``QuerySet`` from the database at a later time, pickle the ``query`` attribute +of the ``QuerySet``. You can then recreate the original ``QuerySet`` (without +any results loaded) using some code like this:: + + >>> import pickle + >>> query = pickle.loads(s) # Assuming 's' is the pickled string. + >>> qs = MyModel.objects.all() + >>> qs.query = query # Restore the original 'query'. + +The ``query`` attribute is an opaque object. It represents the internals of +the query construction and is not part of the public API. However, it is safe +(and fully supported) to pickle and unpickle the attribute's contents as +described here. + +.. admonition:: You can't share pickles between versions + + Pickles of QuerySets are only valid for the version of Django that + was used to generate them. If you generate a pickle using Django + version N, there is no guarantee that pickle will be readable with + Django version N+1. Pickles should not be used as part of a long-term + archival strategy. + +.. _pickle: http://docs.python.org/library/pickle.html + +.. _queryset-api: + +QuerySet API +============ + +Though you usually won't create one manually -- you'll go through a +:class:`Manager` -- here's the formal declaration of a ``QuerySet``: + +.. class:: QuerySet([model=None]) + +Usually when you'll interact with a ``QuerySet`` you'll use it by :ref:`chaining +filters <chaining-filters>`. To make this work, most ``QuerySet`` methods return new querysets. + +Methods that return new QuerySets +--------------------------------- + +Django provides a range of ``QuerySet`` refinement methods that modify either +the types of results returned by the ``QuerySet`` or the way its SQL query is +executed. + +filter +~~~~~~ + +.. method:: filter(**kwargs) + +Returns a new ``QuerySet`` containing objects that match the given lookup +parameters. + +The lookup parameters (``**kwargs``) should be in the format described in +`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the +underlying SQL statement. + +exclude +~~~~~~~ + +.. method:: exclude(**kwargs) + +Returns a new ``QuerySet`` containing objects that do *not* match the given +lookup parameters. + +The lookup parameters (``**kwargs``) should be in the format described in +`Field lookups`_ below. Multiple parameters are joined via ``AND`` in the +underlying SQL statement, and the whole thing is enclosed in a ``NOT()``. + +This example excludes all entries whose ``pub_date`` is later than 2005-1-3 +AND whose ``headline`` is "Hello":: + + Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello') + +In SQL terms, that evaluates to:: + + SELECT ... + WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello') + +This example excludes all entries whose ``pub_date`` is later than 2005-1-3 +OR whose headline is "Hello":: + + Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello') + +In SQL terms, that evaluates to:: + + SELECT ... + WHERE NOT pub_date > '2005-1-3' + AND NOT headline = 'Hello' + +Note the second example is more restrictive. + +annotate +~~~~~~~~ + +.. method:: annotate(*args, **kwargs) + +.. versionadded:: 1.1 + +Annotates each object in the ``QuerySet`` with the provided list of +aggregate values (averages, sums, etc) that have been computed over +the objects that are related to the objects in the ``QuerySet``. +Each argument to ``annotate()`` is an annotation that will be added +to each object in the ``QuerySet`` that is returned. + +The aggregation functions that are provided by Django are described +in `Aggregation Functions`_ below. + +Annotations specified using keyword arguments will use the keyword as +the alias for the annotation. Anonymous arguments will have an alias +generated for them based upon the name of the aggregate function and +the model field that is being aggregated. + +For example, if you were manipulating a list of blogs, you may want +to determine how many entries have been made in each blog:: + + >>> q = Blog.objects.annotate(Count('entry')) + # The name of the first blog + >>> q[0].name + 'Blogasaurus' + # The number of entries on the first blog + >>> q[0].entry__count + 42 + +The ``Blog`` model doesn't define an ``entry__count`` attribute by itself, +but by using a keyword argument to specify the aggregate function, you can +control the name of the annotation:: + + >>> q = Blog.objects.annotate(number_of_entries=Count('entry')) + # The number of entries on the first blog, using the name provided + >>> q[0].number_of_entries + 42 + +For an in-depth discussion of aggregation, see :doc:`the topic guide on +Aggregation </topics/db/aggregation>`. + +order_by +~~~~~~~~ + +.. method:: order_by(*fields) + +By default, results returned by a ``QuerySet`` are ordered by the ordering +tuple given by the ``ordering`` option in the model's ``Meta``. You can +override this on a per-``QuerySet`` basis by using the ``order_by`` method. + +Example:: + + Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline') + +The result above will be ordered by ``pub_date`` descending, then by +``headline`` ascending. The negative sign in front of ``"-pub_date"`` indicates +*descending* order. Ascending order is implied. To order randomly, use ``"?"``, +like so:: + + Entry.objects.order_by('?') + +Note: ``order_by('?')`` queries may be expensive and slow, depending on the +database backend you're using. + +To order by a field in a different model, use the same syntax as when you are +querying across model relations. That is, the name of the field, followed by a +double underscore (``__``), followed by the name of the field in the new model, +and so on for as many models as you want to join. For example:: + + Entry.objects.order_by('blog__name', 'headline') + +If you try to order by a field that is a relation to another model, Django will +use the default ordering on the related model (or order by the related model's +primary key if there is no ``Meta.ordering`` specified. For example:: + + Entry.objects.order_by('blog') + +...is identical to:: + + Entry.objects.order_by('blog__id') + +...since the ``Blog`` model has no default ordering specified. + +Be cautious when ordering by fields in related models if you are also using +``distinct()``. See the note in :meth:`distinct` for an explanation of how +related model ordering can change the expected results. + +It is permissible to specify a multi-valued field to order the results by (for +example, a ``ManyToMany`` field). Normally this won't be a sensible thing to +do and it's really an advanced usage feature. However, if you know that your +queryset's filtering or available data implies that there will only be one +ordering piece of data for each of the main items you are selecting, the +ordering may well be exactly what you want to do. Use ordering on multi-valued +fields with care and make sure the results are what you expect. + +.. versionadded:: 1.0 + +The syntax for ordering across related models has changed. See the `Django 0.96 +documentation`_ for the old behaviour. + +.. _Django 0.96 documentation: http://www.djangoproject.com/documentation/0.96/model-api/#floatfield + +There's no way to specify whether ordering should be case sensitive. With +respect to case-sensitivity, Django will order results however your database +backend normally orders them. + +If you don't want any ordering to be applied to a query, not even the default +ordering, call ``order_by()`` with no parameters. + +.. versionadded:: 1.1 + +You can tell if a query is ordered or not by checking the +:attr:`QuerySet.ordered` attribute, which will be ``True`` if the +``QuerySet`` has been ordered in any way. + +reverse +~~~~~~~ + +.. method:: reverse() + +.. versionadded:: 1.0 + +Use the ``reverse()`` method to reverse the order in which a queryset's +elements are returned. Calling ``reverse()`` a second time restores the +ordering back to the normal direction. + +To retrieve the ''last'' five items in a queryset, you could do this:: + + my_queryset.reverse()[:5] + +Note that this is not quite the same as slicing from the end of a sequence in +Python. The above example will return the last item first, then the +penultimate item and so on. If we had a Python sequence and looked at +``seq[-5:]``, we would see the fifth-last item first. Django doesn't support +that mode of access (slicing from the end), because it's not possible to do it +efficiently in SQL. + +Also, note that ``reverse()`` should generally only be called on a +``QuerySet`` which has a defined ordering (e.g., when querying against +a model which defines a default ordering, or when using +``order_by()``). If no such ordering is defined for a given +``QuerySet``, calling ``reverse()`` on it has no real effect (the +ordering was undefined prior to calling ``reverse()``, and will remain +undefined afterward). + +distinct +~~~~~~~~ + +.. method:: distinct() + +Returns a new ``QuerySet`` that uses ``SELECT DISTINCT`` in its SQL query. This +eliminates duplicate rows from the query results. + +By default, a ``QuerySet`` will not eliminate duplicate rows. In practice, this +is rarely a problem, because simple queries such as ``Blog.objects.all()`` +don't introduce the possibility of duplicate result rows. However, if your +query spans multiple tables, it's possible to get duplicate results when a +``QuerySet`` is evaluated. That's when you'd use ``distinct()``. + +.. note:: + Any fields used in an :meth:`order_by` call are included in the SQL + ``SELECT`` columns. This can sometimes lead to unexpected results when + used in conjunction with ``distinct()``. If you order by fields from a + related model, those fields will be added to the selected columns and they + may make otherwise duplicate rows appear to be distinct. Since the extra + columns don't appear in the returned results (they are only there to + support ordering), it sometimes looks like non-distinct results are being + returned. + + Similarly, if you use a ``values()`` query to restrict the columns + selected, the columns used in any ``order_by()`` (or default model + ordering) will still be involved and may affect uniqueness of the results. + + The moral here is that if you are using ``distinct()`` be careful about + ordering by related models. Similarly, when using ``distinct()`` and + ``values()`` together, be careful when ordering by fields not in the + ``values()`` call. + +values +~~~~~~ + +.. method:: values(*fields) + +Returns a ``ValuesQuerySet`` -- a ``QuerySet`` that returns dictionaries when +used as an iterable, rather than model-instance objects. + +Each of those dictionaries represents an object, with the keys corresponding to +the attribute names of model objects. + +This example compares the dictionaries of ``values()`` with the normal model +objects:: + + # This list contains a Blog object. + >>> Blog.objects.filter(name__startswith='Beatles') + [<Blog: Beatles Blog>] + + # This list contains a dictionary. + >>> Blog.objects.filter(name__startswith='Beatles').values() + [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}] + +``values()`` takes optional positional arguments, ``*fields``, which specify +field names to which the ``SELECT`` should be limited. If you specify the +fields, each dictionary will contain only the field keys/values for the fields +you specify. If you don't specify the fields, each dictionary will contain a +key and value for every field in the database table. + +Example:: + + >>> Blog.objects.values() + [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}], + >>> Blog.objects.values('id', 'name') + [{'id': 1, 'name': 'Beatles Blog'}] + +A couple of subtleties that are worth mentioning: + + * The ``values()`` method does not return anything for + :class:`~django.db.models.ManyToManyField` attributes and will raise an + error if you try to pass in this type of field to it. + * If you have a field called ``foo`` that is a + :class:`~django.db.models.ForeignKey`, the default ``values()`` call + will return a dictionary key called ``foo_id``, since this is the name + of the hidden model attribute that stores the actual value (the ``foo`` + attribute refers to the related model). When you are calling + ``values()`` and passing in field names, you can pass in either ``foo`` + or ``foo_id`` and you will get back the same thing (the dictionary key + will match the field name you passed in). + + For example:: + + >>> Entry.objects.values() + [{'blog_id': 1, 'headline': u'First Entry', ...}, ...] + + >>> Entry.objects.values('blog') + [{'blog': 1}, ...] + + >>> Entry.objects.values('blog_id') + [{'blog_id': 1}, ...] + + * When using ``values()`` together with ``distinct()``, be aware that + ordering can affect the results. See the note in :meth:`distinct` for + details. + + * If you use a ``values()`` clause after an ``extra()`` clause, + any fields defined by a ``select`` argument in the ``extra()`` + must be explicitly included in the ``values()`` clause. However, + if the ``extra()`` clause is used after the ``values()``, the + fields added by the select will be included automatically. + +.. versionadded:: 1.0 + +Previously, it was not possible to pass ``blog_id`` to ``values()`` in the above +example, only ``blog``. + +A ``ValuesQuerySet`` is useful when you know you're only going to need values +from a small number of the available fields and you won't need the +functionality of a model instance object. It's more efficient to select only +the fields you need to use. + +Finally, note a ``ValuesQuerySet`` is a subclass of ``QuerySet``, so it has all +methods of ``QuerySet``. You can call ``filter()`` on it, or ``order_by()``, or +whatever. Yes, that means these two calls are identical:: + + Blog.objects.values().order_by('id') + Blog.objects.order_by('id').values() + +The people who made Django prefer to put all the SQL-affecting methods first, +followed (optionally) by any output-affecting methods (such as ``values()``), +but it doesn't really matter. This is your chance to really flaunt your +individualism. + +values_list +~~~~~~~~~~~ + +.. method:: values_list(*fields) + +.. versionadded:: 1.0 + +This is similar to ``values()`` except that instead of returning dictionaries, +it returns tuples when iterated over. Each tuple contains the value from the +respective field passed into the ``values_list()`` call -- so the first item is +the first field, etc. For example:: + + >>> Entry.objects.values_list('id', 'headline') + [(1, u'First entry'), ...] + +If you only pass in a single field, you can also pass in the ``flat`` +parameter. If ``True``, this will mean the returned results are single values, +rather than one-tuples. An example should make the difference clearer:: + + >>> Entry.objects.values_list('id').order_by('id') + [(1,), (2,), (3,), ...] + + >>> Entry.objects.values_list('id', flat=True).order_by('id') + [1, 2, 3, ...] + +It is an error to pass in ``flat`` when there is more than one field. + +If you don't pass any values to ``values_list()``, it will return all the +fields in the model, in the order they were declared. + +dates +~~~~~ + +.. method:: dates(field, kind, order='ASC') + +Returns a ``DateQuerySet`` -- a ``QuerySet`` that evaluates to a list of +``datetime.datetime`` objects representing all available dates of a particular +kind within the contents of the ``QuerySet``. + +``field`` should be the name of a ``DateField`` or ``DateTimeField`` of your +model. + +``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each +``datetime.datetime`` object in the result list is "truncated" to the given +``type``. + + * ``"year"`` returns a list of all distinct year values for the field. + * ``"month"`` returns a list of all distinct year/month values for the field. + * ``"day"`` returns a list of all distinct year/month/day values for the field. + +``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or +``'DESC'``. This specifies how to order the results. + +Examples:: + + >>> Entry.objects.dates('pub_date', 'year') + [datetime.datetime(2005, 1, 1)] + >>> Entry.objects.dates('pub_date', 'month') + [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)] + >>> Entry.objects.dates('pub_date', 'day') + [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)] + >>> Entry.objects.dates('pub_date', 'day', order='DESC') + [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] + >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') + [datetime.datetime(2005, 3, 20)] + +none +~~~~ + +.. method:: none() + +.. versionadded:: 1.0 + +Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to +an empty list. This can be used in cases where you know that you should +return an empty result set and your caller is expecting a ``QuerySet`` +object (instead of returning an empty list, for example.) + +Examples:: + + >>> Entry.objects.none() + [] + +all +~~~ + +.. method:: all() + +.. versionadded:: 1.0 + +Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass you +pass in). This can be useful in some situations where you might want to pass +in either a model manager or a ``QuerySet`` and do further filtering on the +result. You can safely call ``all()`` on either object and then you'll +definitely have a ``QuerySet`` to work with. + +.. _select-related: + +select_related +~~~~~~~~~~~~~~ + +.. method:: select_related() + +Returns a ``QuerySet`` that will automatically "follow" foreign-key +relationships, selecting that additional related-object data when it executes +its query. This is a performance booster which results in (sometimes much) +larger queries but means later use of foreign-key relationships won't require +database queries. + +The following examples illustrate the difference between plain lookups and +``select_related()`` lookups. Here's standard lookup:: + + # Hits the database. + e = Entry.objects.get(id=5) + + # Hits the database again to get the related Blog object. + b = e.blog + +And here's ``select_related`` lookup:: + + # Hits the database. + e = Entry.objects.select_related().get(id=5) + + # Doesn't hit the database, because e.blog has been prepopulated + # in the previous query. + b = e.blog + +``select_related()`` follows foreign keys as far as possible. If you have the +following models:: + + class City(models.Model): + # ... + + class Person(models.Model): + # ... + hometown = models.ForeignKey(City) + + class Book(models.Model): + # ... + author = models.ForeignKey(Person) + +...then a call to ``Book.objects.select_related().get(id=4)`` will cache the +related ``Person`` *and* the related ``City``:: + + b = Book.objects.select_related().get(id=4) + p = b.author # Doesn't hit the database. + c = p.hometown # Doesn't hit the database. + + b = Book.objects.get(id=4) # No select_related() in this example. + p = b.author # Hits the database. + c = p.hometown # Hits the database. + +Note that, by default, ``select_related()`` does not follow foreign keys that +have ``null=True``. + +Usually, using ``select_related()`` can vastly improve performance because your +app can avoid many database calls. However, in situations with deeply nested +sets of relationships ``select_related()`` can sometimes end up following "too +many" relations, and can generate queries so large that they end up being slow. + +In these situations, you can use the ``depth`` argument to ``select_related()`` +to control how many "levels" of relations ``select_related()`` will actually +follow:: + + b = Book.objects.select_related(depth=1).get(id=4) + p = b.author # Doesn't hit the database. + c = p.hometown # Requires a database call. + +Sometimes you only want to access specific models that are related to your root +model, not all of the related models. In these cases, you can pass the related +field names to ``select_related()`` and it will only follow those relations. +You can even do this for models that are more than one relation away by +separating the field names with double underscores, just as for filters. For +example, if you have this model:: + + class Room(models.Model): + # ... + building = models.ForeignKey(...) + + class Group(models.Model): + # ... + teacher = models.ForeignKey(...) + room = models.ForeignKey(Room) + subject = models.ForeignKey(...) + +...and you only needed to work with the ``room`` and ``subject`` attributes, +you could write this:: + + g = Group.objects.select_related('room', 'subject') + +This is also valid:: + + g = Group.objects.select_related('room__building', 'subject') + +...and would also pull in the ``building`` relation. + +You can refer to any ``ForeignKey`` or ``OneToOneField`` relation in +the list of fields passed to ``select_related``. Ths includes foreign +keys that have ``null=True`` (unlike the default ``select_related()`` +call). It's an error to use both a list of fields and the ``depth`` +parameter in the same ``select_related()`` call, since they are +conflicting options. + +.. versionadded:: 1.0 + +Both the ``depth`` argument and the ability to specify field names in the call +to ``select_related()`` are new in Django version 1.0. + +.. versionchanged:: 1.2 + +You can also refer to the reverse direction of a ``OneToOneFields`` in +the list of fields passed to ``select_related`` -- that is, you can traverse +a ``OneToOneField`` back to the object on which the field is defined. Instead +of specifying the field name, use the ``related_name`` for the field on the +related object. + +``OneToOneFields`` will not be traversed in the reverse direction if you +are performing a depth-based ``select_related``. + +extra +~~~~~ + +.. method:: extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None) + +Sometimes, the Django query syntax by itself can't easily express a complex +``WHERE`` clause. For these edge cases, Django provides the ``extra()`` +``QuerySet`` modifier -- a hook for injecting specific clauses into the SQL +generated by a ``QuerySet``. + +By definition, these extra lookups may not be portable to different database +engines (because you're explicitly writing SQL code) and violate the DRY +principle, so you should avoid them if possible. + +Specify one or more of ``params``, ``select``, ``where`` or ``tables``. None +of the arguments is required, but you should use at least one of them. + + * ``select`` + The ``select`` argument lets you put extra fields in the ``SELECT`` clause. + It should be a dictionary mapping attribute names to SQL clauses to use to + calculate that attribute. + + Example:: + + Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"}) + + As a result, each ``Entry`` object will have an extra attribute, + ``is_recent``, a boolean representing whether the entry's ``pub_date`` is + greater than Jan. 1, 2006. + + Django inserts the given SQL snippet directly into the ``SELECT`` + statement, so the resulting SQL of the above example would be something + like:: + + SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent + FROM blog_entry; + + + The next example is more advanced; it does a subquery to give each + resulting ``Blog`` object an ``entry_count`` attribute, an integer count + of associated ``Entry`` objects:: + + Blog.objects.extra( + select={ + 'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id' + }, + ) + + (In this particular case, we're exploiting the fact that the query will + already contain the ``blog_blog`` table in its ``FROM`` clause.) + + The resulting SQL of the above example would be:: + + SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count + FROM blog_blog; + + Note that the parenthesis required by most database engines around + subqueries are not required in Django's ``select`` clauses. Also note that + some database backends, such as some MySQL versions, don't support + subqueries. + + .. versionadded:: 1.0 + + In some rare cases, you might wish to pass parameters to the SQL fragments + in ``extra(select=...)``. For this purpose, use the ``select_params`` + parameter. Since ``select_params`` is a sequence and the ``select`` + attribute is a dictionary, some care is required so that the parameters + are matched up correctly with the extra select pieces. In this situation, + you should use a ``django.utils.datastructures.SortedDict`` for the + ``select`` value, not just a normal Python dictionary. + + This will work, for example:: + + Blog.objects.extra( + select=SortedDict([('a', '%s'), ('b', '%s')]), + select_params=('one', 'two')) + + The only thing to be careful about when using select parameters in + ``extra()`` is to avoid using the substring ``"%%s"`` (that's *two* + percent characters before the ``s``) in the select strings. Django's + tracking of parameters looks for ``%s`` and an escaped ``%`` character + like this isn't detected. That will lead to incorrect results. + + * ``where`` / ``tables`` + You can define explicit SQL ``WHERE`` clauses -- perhaps to perform + non-explicit joins -- by using ``where``. You can manually add tables to + the SQL ``FROM`` clause by using ``tables``. + + ``where`` and ``tables`` both take a list of strings. All ``where`` + parameters are "AND"ed to any other search criteria. + + Example:: + + Entry.objects.extra(where=['id IN (3, 4, 5, 20)']) + + ...translates (roughly) into the following SQL:: + + SELECT * FROM blog_entry WHERE id IN (3, 4, 5, 20); + + Be careful when using the ``tables`` parameter if you're specifying + tables that are already used in the query. When you add extra tables + via the ``tables`` parameter, Django assumes you want that table included + an extra time, if it is already included. That creates a problem, + since the table name will then be given an alias. If a table appears + multiple times in an SQL statement, the second and subsequent occurrences + must use aliases so the database can tell them apart. If you're + referring to the extra table you added in the extra ``where`` parameter + this is going to cause errors. + + Normally you'll only be adding extra tables that don't already appear in + the query. However, if the case outlined above does occur, there are a few + solutions. First, see if you can get by without including the extra table + and use the one already in the query. If that isn't possible, put your + ``extra()`` call at the front of the queryset construction so that your + table is the first use of that table. Finally, if all else fails, look at + the query produced and rewrite your ``where`` addition to use the alias + given to your extra table. The alias will be the same each time you + construct the queryset in the same way, so you can rely upon the alias + name to not change. + + * ``order_by`` + If you need to order the resulting queryset using some of the new fields + or tables you have included via ``extra()`` use the ``order_by`` parameter + to ``extra()`` and pass in a sequence of strings. These strings should + either be model fields (as in the normal ``order_by()`` method on + querysets), of the form ``table_name.column_name`` or an alias for a column + that you specified in the ``select`` parameter to ``extra()``. + + For example:: + + q = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"}) + q = q.extra(order_by = ['-is_recent']) + + This would sort all the items for which ``is_recent`` is true to the front + of the result set (``True`` sorts before ``False`` in a descending + ordering). + + This shows, by the way, that you can make multiple calls to + ``extra()`` and it will behave as you expect (adding new constraints each + time). + + * ``params`` + The ``where`` parameter described above may use standard Python database + string placeholders -- ``'%s'`` to indicate parameters the database engine + should automatically quote. The ``params`` argument is a list of any extra + parameters to be substituted. + + Example:: + + Entry.objects.extra(where=['headline=%s'], params=['Lennon']) + + Always use ``params`` instead of embedding values directly into ``where`` + because ``params`` will ensure values are quoted correctly according to + your particular backend. (For example, quotes will be escaped correctly.) + + Bad:: + + Entry.objects.extra(where=["headline='Lennon'"]) + + Good:: + + Entry.objects.extra(where=['headline=%s'], params=['Lennon']) + +defer +~~~~~ + +.. method:: defer(*fields) + +.. versionadded:: 1.1 + +In some complex data-modeling situations, your models might contain a lot of +fields, some of which could contain a lot of data (for example, text fields), +or require expensive processing to convert them to Python objects. If you are +using the results of a queryset in some situation where you know you don't +need those particular fields, you can tell Django not to retrieve them from +the database. + +This is done by passing the names of the fields to not load to ``defer()``:: + + Entry.objects.defer("headline", "body") + +A queryset that has deferred fields will still return model instances. Each +deferred field will be retrieved from the database if you access that field +(one at a time, not all the deferred fields at once). + +You can make multiple calls to ``defer()``. Each call adds new fields to the +deferred set:: + + # Defers both the body and headline fields. + Entry.objects.defer("body").filter(rating=5).defer("headline") + +The order in which fields are added to the deferred set does not matter. +Calling ``defer()`` with a field name that has already been deferred is +harmless (the field will still be deferred). + +You can defer loading of fields in related models (if the related models are +loading via ``select_related()``) by using the standard double-underscore +notation to separate related fields:: + + Blog.objects.select_related().defer("entry__headline", "entry__body") + +If you want to clear the set of deferred fields, pass ``None`` as a parameter +to ``defer()``:: + + # Load all fields immediately. + my_queryset.defer(None) + +Some fields in a model won't be deferred, even if you ask for them. You can +never defer the loading of the primary key. If you are using +``select_related()`` to retrieve other models at the same time you shouldn't +defer the loading of the field that connects from the primary model to the +related one (at the moment, that doesn't raise an error, but it will +eventually). + +.. note:: + + The ``defer()`` method (and its cousin, ``only()``, below) are only for + advanced use-cases. They provide an optimization for when you have + analyzed your queries closely and understand *exactly* what information + you need and have measured that the difference between returning the + fields you need and the full set of fields for the model will be + significant. When you are initially developing your applications, don't + bother using ``defer()``; leave it until your query construction has + settled down and you understand where the hot-points are. + +only +~~~~ + +.. method:: only(*fields) + +.. versionadded:: 1.1 + +The ``only()`` method is more or less the opposite of ``defer()``. You +call it with the fields that should *not* be deferred when retrieving a model. +If you have a model where almost all the fields need to be deferred, using +``only()`` to specify the complementary set of fields could result in simpler +code. + +If you have a model with fields ``name``, ``age`` and ``biography``, the +following two querysets are the same, in terms of deferred fields:: + + Person.objects.defer("age", "biography") + Person.objects.only("name") + +Whenever you call ``only()`` it *replaces* the set of fields to load +immediately. The method's name is mnemonic: **only** those fields are loaded +immediately; the remainder are deferred. Thus, successive calls to ``only()`` +result in only the final fields being considered:: + + # This will defer all fields except the headline. + Entry.objects.only("body", "rating").only("headline") + +Since ``defer()`` acts incrementally (adding fields to the deferred list), you +can combine calls to ``only()`` and ``defer()`` and things will behave +logically:: + + # Final result is that everything except "headline" is deferred. + Entry.objects.only("headline", "body").defer("body") + + # Final result loads headline and body immediately (only() replaces any + # existing set of fields). + Entry.objects.defer("body").only("headline", "body") + +using +~~~~~ + +.. method:: using(alias) + +.. versionadded:: 1.2 + +This method is for controlling which database the ``QuerySet`` will be +evaluated against if you are using more than one database. The only argument +this method takes is the alias of a database, as defined in +:setting:`DATABASES`. + +For example:: + + # queries the database with the 'default' alias. + >>> Entry.objects.all() + + # queries the database with the 'backup' alias + >>> Entry.objects.using('backup') + + +Methods that do not return QuerySets +------------------------------------ + +The following ``QuerySet`` methods evaluate the ``QuerySet`` and return +something *other than* a ``QuerySet``. + +These methods do not use a cache (see :ref:`caching-and-querysets`). Rather, +they query the database each time they're called. + +get +~~~ + +.. method:: get(**kwargs) + +Returns the object matching the given lookup parameters, which should be in +the format described in `Field lookups`_. + +``get()`` raises ``MultipleObjectsReturned`` if more than one object was +found. The ``MultipleObjectsReturned`` exception is an attribute of the model +class. + +``get()`` raises a ``DoesNotExist`` exception if an object wasn't found for +the given parameters. This exception is also an attribute of the model class. +Example:: + + Entry.objects.get(id='foo') # raises Entry.DoesNotExist + +The ``DoesNotExist`` exception inherits from +``django.core.exceptions.ObjectDoesNotExist``, so you can target multiple +``DoesNotExist`` exceptions. Example:: + + from django.core.exceptions import ObjectDoesNotExist + try: + e = Entry.objects.get(id=3) + b = Blog.objects.get(id=1) + except ObjectDoesNotExist: + print "Either the entry or blog doesn't exist." + +create +~~~~~~ + +.. method:: create(**kwargs) + +A convenience method for creating an object and saving it all in one step. Thus:: + + p = Person.objects.create(first_name="Bruce", last_name="Springsteen") + +and:: + + p = Person(first_name="Bruce", last_name="Springsteen") + p.save(force_insert=True) + +are equivalent. + +The :ref:`force_insert <ref-models-force-insert>` parameter is documented +elsewhere, but all it means is that a new object will always be created. +Normally you won't need to worry about this. However, if your model contains a +manual primary key value that you set and if that value already exists in the +database, a call to ``create()`` will fail with an :exc:`IntegrityError` since +primary keys must be unique. So remember to be prepared to handle the exception +if you are using manual primary keys. + +get_or_create +~~~~~~~~~~~~~ + +.. method:: get_or_create(**kwargs) + +A convenience method for looking up an object with the given kwargs, creating +one if necessary. + +Returns a tuple of ``(object, created)``, where ``object`` is the retrieved or +created object and ``created`` is a boolean specifying whether a new object was +created. + +This is meant as a shortcut to boilerplatish code and is mostly useful for +data-import scripts. For example:: + + try: + obj = Person.objects.get(first_name='John', last_name='Lennon') + except Person.DoesNotExist: + obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9)) + obj.save() + +This pattern gets quite unwieldy as the number of fields in a model goes up. +The above example can be rewritten using ``get_or_create()`` like so:: + + obj, created = Person.objects.get_or_create(first_name='John', last_name='Lennon', + defaults={'birthday': date(1940, 10, 9)}) + +Any keyword arguments passed to ``get_or_create()`` -- *except* an optional one +called ``defaults`` -- will be used in a ``get()`` call. If an object is found, +``get_or_create()`` returns a tuple of that object and ``False``. If an object +is *not* found, ``get_or_create()`` will instantiate and save a new object, +returning a tuple of the new object and ``True``. The new object will be +created roughly according to this algorithm:: + + defaults = kwargs.pop('defaults', {}) + params = dict([(k, v) for k, v in kwargs.items() if '__' not in k]) + params.update(defaults) + obj = self.model(**params) + obj.save() + +In English, that means start with any non-``'defaults'`` keyword argument that +doesn't contain a double underscore (which would indicate a non-exact lookup). +Then add the contents of ``defaults``, overriding any keys if necessary, and +use the result as the keyword arguments to the model class. As hinted at +above, this is a simplification of the algorithm that is used, but it contains +all the pertinent details. The internal implementation has some more +error-checking than this and handles some extra edge-conditions; if you're +interested, read the code. + +If you have a field named ``defaults`` and want to use it as an exact lookup in +``get_or_create()``, just use ``'defaults__exact'``, like so:: + + Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'}) + + +The ``get_or_create()`` method has similar error behaviour to ``create()`` +when you are using manually specified primary keys. If an object needs to be +created and the key already exists in the database, an ``IntegrityError`` will +be raised. + +Finally, a word on using ``get_or_create()`` in Django views. As mentioned +earlier, ``get_or_create()`` is mostly useful in scripts that need to parse +data and create new records if existing ones aren't available. But if you need +to use ``get_or_create()`` in a view, please make sure to use it only in +``POST`` requests unless you have a good reason not to. ``GET`` requests +shouldn't have any effect on data; use ``POST`` whenever a request to a page +has a side effect on your data. For more, see `Safe methods`_ in the HTTP spec. + +.. _Safe methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1 + +count +~~~~~ + +.. method:: count() + +Returns an integer representing the number of objects in the database matching +the ``QuerySet``. ``count()`` never raises exceptions. + +Example:: + + # Returns the total number of entries in the database. + Entry.objects.count() + + # Returns the number of entries whose headline contains 'Lennon' + Entry.objects.filter(headline__contains='Lennon').count() + +``count()`` performs a ``SELECT COUNT(*)`` behind the scenes, so you should +always use ``count()`` rather than loading all of the record into Python +objects and calling ``len()`` on the result (unless you need to load the +objects into memory anyway, in which case ``len()`` will be faster). + +Depending on which database you're using (e.g. PostgreSQL vs. MySQL), +``count()`` may return a long integer instead of a normal Python integer. This +is an underlying implementation quirk that shouldn't pose any real-world +problems. + +in_bulk +~~~~~~~ + +.. method:: in_bulk(id_list) + +Takes a list of primary-key values and returns a dictionary mapping each +primary-key value to an instance of the object with the given ID. + +Example:: + + >>> Blog.objects.in_bulk([1]) + {1: <Blog: Beatles Blog>} + >>> Blog.objects.in_bulk([1, 2]) + {1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>} + >>> Blog.objects.in_bulk([]) + {} + +If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. + +iterator +~~~~~~~~ + +.. method:: iterator() + +Evaluates the ``QuerySet`` (by performing the query) and returns an +`iterator`_ over the results. A ``QuerySet`` typically caches its +results internally so that repeated evaluations do not result in +additional queries; ``iterator()`` will instead read results directly, +without doing any caching at the ``QuerySet`` level. For a +``QuerySet`` which returns a large number of objects, this often +results in better performance and a significant reduction in memory + +Note that using ``iterator()`` on a ``QuerySet`` which has already +been evaluated will force it to evaluate again, repeating the query. + +.. _iterator: http://www.python.org/dev/peps/pep-0234/ + +latest +~~~~~~ + +.. method:: latest(field_name=None) + +Returns the latest object in the table, by date, using the ``field_name`` +provided as the date field. + +This example returns the latest ``Entry`` in the table, according to the +``pub_date`` field:: + + Entry.objects.latest('pub_date') + +If your model's ``Meta`` specifies ``get_latest_by``, you can leave off the +``field_name`` argument to ``latest()``. Django will use the field specified in +``get_latest_by`` by default. + +Like ``get()``, ``latest()`` raises ``DoesNotExist`` if an object doesn't +exist with the given parameters. + +Note ``latest()`` exists purely for convenience and readability. + +aggregate +~~~~~~~~~ + +.. method:: aggregate(*args, **kwargs) + +.. versionadded:: 1.1 + +Returns a dictionary of aggregate values (averages, sums, etc) calculated +over the ``QuerySet``. Each argument to ``aggregate()`` specifies +a value that will be included in the dictionary that is returned. + +The aggregation functions that are provided by Django are described +in `Aggregation Functions`_ below. + +Aggregates specified using keyword arguments will use the keyword as +the name for the annotation. Anonymous arguments will have an name +generated for them based upon the name of the aggregate function and +the model field that is being aggregated. + +For example, if you were manipulating blog entries, you may want to know +the number of authors that have contributed blog entries:: + + >>> q = Blog.objects.aggregate(Count('entry')) + {'entry__count': 16} + +By using a keyword argument to specify the aggregate function, you can +control the name of the aggregation value that is returned:: + + >>> q = Blog.objects.aggregate(number_of_entries=Count('entry')) + {'number_of_entries': 16} + +For an in-depth discussion of aggregation, see :doc:`the topic guide on +Aggregation </topics/db/aggregation>`. + +exists +~~~~~~ + +.. method:: exists() + +.. versionadded:: 1.2 + +Returns ``True`` if the :class:`QuerySet` contains any results, and ``False`` +if not. This tries to perform the query in the simplest and fastest way +possible, but it *does* execute nearly the same query. This means that calling +:meth:`QuerySet.exists()` is faster than ``bool(some_query_set)``, but not by +a large degree. If ``some_query_set`` has not yet been evaluated, but you know +that it will be at some point, then using ``some_query_set.exists()`` will do +more overall work (an additional query) than simply using +``bool(some_query_set)``. + +update +~~~~~~ + +.. method:: update(**kwargs) + +Performs an SQL update query for the specified fields, and returns +the number of rows affected. The ``update()`` method is applied instantly and +the only restriction on the :class:`QuerySet` that is updated is that it can +only update columns in the model's main table. Filtering based on related +fields is still possible. You cannot call ``update()`` on a +:class:`QuerySet` that has had a slice taken or can otherwise no longer be +filtered. + +For example, if you wanted to update all the entries in a particular blog +to use the same headline:: + + >>> b = Blog.objects.get(pk=1) + + # Update all the headlines belonging to this Blog. + >>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same') + +The ``update()`` method does a bulk update and does not call any ``save()`` +methods on your models, nor does it emit the ``pre_save`` or ``post_save`` +signals (which are a consequence of calling ``save()``). + +delete +~~~~~~ + +.. method:: delete() + +Performs an SQL delete query on all rows in the :class:`QuerySet`. The +``delete()`` is applied instantly. You cannot call ``delete()`` on a +:class:`QuerySet` that has had a slice taken or can otherwise no longer be +filtered. + +For example, to delete all the entries in a particular blog:: + + >>> b = Blog.objects.get(pk=1) + + # Delete all the entries belonging to this Blog. + >>> Entry.objects.filter(blog=b).delete() + +Django emulates the SQL constraint ``ON DELETE CASCADE`` -- in other words, any +objects with foreign keys pointing at the objects to be deleted will be deleted +along with them. For example:: + + blogs = Blog.objects.all() + # This will delete all Blogs and all of their Entry objects. + blogs.delete() + +The ``delete()`` method does a bulk delete and does not call any ``delete()`` +methods on your models. It does, however, emit the +:data:`~django.db.models.signals.pre_delete` and +:data:`~django.db.models.signals.post_delete` signals for all deleted objects +(including cascaded deletions). + +.. _field-lookups: + +Field lookups +------------- + +Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're +specified as keyword arguments to the ``QuerySet`` methods ``filter()``, +``exclude()`` and ``get()``. + +For an introduction, see :ref:`field-lookups-intro`. + +.. fieldlookup:: exact + +exact +~~~~~ + +Exact match. If the value provided for comparison is ``None``, it will +be interpreted as an SQL ``NULL`` (See isnull_ for more details). + +Examples:: + + Entry.objects.get(id__exact=14) + Entry.objects.get(id__exact=None) + +SQL equivalents:: + + SELECT ... WHERE id = 14; + SELECT ... WHERE id IS NULL; + +.. versionchanged:: 1.0 + The semantics of ``id__exact=None`` have changed in Django 1.0. Previously, + it was (intentionally) converted to ``WHERE id = NULL`` at the SQL level, + which would never match anything. It has now been changed to behave the + same as ``id__isnull=True``. + +.. admonition:: MySQL comparisons + + In MySQL, a database table's "collation" setting determines whether + ``exact`` comparisons are case-sensitive. This is a database setting, *not* + a Django setting. It's possible to configure your MySQL tables to use + case-sensitive comparisons, but some trade-offs are involved. For more + information about this, see the :ref:`collation section <mysql-collation>` + in the :doc:`databases </ref/databases>` documentation. + +.. fieldlookup:: iexact + +iexact +~~~~~~ + +Case-insensitive exact match. + +Example:: + + Blog.objects.get(name__iexact='beatles blog') + +SQL equivalent:: + + SELECT ... WHERE name ILIKE 'beatles blog'; + +Note this will match ``'Beatles Blog'``, ``'beatles blog'``, ``'BeAtLes +BLoG'``, etc. + +.. admonition:: SQLite users + + When using the SQLite backend and Unicode (non-ASCII) strings, bear in + mind the :ref:`database note <sqlite-string-matching>` about string + comparisons. SQLite does not do case-insensitive matching for Unicode + strings. + +.. fieldlookup:: contains + +contains +~~~~~~~~ + +Case-sensitive containment test. + +Example:: + + Entry.objects.get(headline__contains='Lennon') + +SQL equivalent:: + + SELECT ... WHERE headline LIKE '%Lennon%'; + +Note this will match the headline ``'Today Lennon honored'`` but not +``'today lennon honored'``. + +SQLite doesn't support case-sensitive ``LIKE`` statements; ``contains`` acts +like ``icontains`` for SQLite. + +.. fieldlookup:: icontains + +icontains +~~~~~~~~~ + +Case-insensitive containment test. + +Example:: + + Entry.objects.get(headline__icontains='Lennon') + +SQL equivalent:: + + SELECT ... WHERE headline ILIKE '%Lennon%'; + +.. admonition:: SQLite users + + When using the SQLite backend and Unicode (non-ASCII) strings, bear in + mind the :ref:`database note <sqlite-string-matching>` about string + comparisons. + +.. fieldlookup:: in + +in +~~ + +In a given list. + +Example:: + + Entry.objects.filter(id__in=[1, 3, 4]) + +SQL equivalent:: + + SELECT ... WHERE id IN (1, 3, 4); + +You can also use a queryset to dynamically evaluate the list of values +instead of providing a list of literal values:: + + inner_qs = Blog.objects.filter(name__contains='Cheddar') + entries = Entry.objects.filter(blog__in=inner_qs) + +This queryset will be evaluated as subselect statement:: + + SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%') + +The above code fragment could also be written as follows:: + + inner_q = Blog.objects.filter(name__contains='Cheddar').values('pk').query + entries = Entry.objects.filter(blog__in=inner_q) + + +.. versionchanged:: 1.1 + In Django 1.0, only the latter piece of code is valid. + +This second form is a bit less readable and unnatural to write, since it +accesses the internal ``query`` attribute and requires a ``ValuesQuerySet``. +If your code doesn't require compatibility with Django 1.0, use the first +form, passing in a queryset directly. + +If you pass in a ``ValuesQuerySet`` or ``ValuesListQuerySet`` (the result of +calling ``values()`` or ``values_list()`` on a queryset) as the value to an +``__in`` lookup, you need to ensure you are only extracting one field in the +result. For example, this will work (filtering on the blog names):: + + inner_qs = Blog.objects.filter(name__contains='Ch').values('name') + entries = Entry.objects.filter(blog__name__in=inner_qs) + +This example will raise an exception, since the inner query is trying to +extract two field values, where only one is expected:: + + # Bad code! Will raise a TypeError. + inner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id') + entries = Entry.objects.filter(blog__name__in=inner_qs) + +.. warning:: + + This ``query`` attribute should be considered an opaque internal attribute. + It's fine to use it like above, but its API may change between Django + versions. + +.. admonition:: Performance considerations + + Be cautious about using nested queries and understand your database + server's performance characteristics (if in doubt, benchmark!). Some + database backends, most notably MySQL, don't optimize nested queries very + well. It is more efficient, in those cases, to extract a list of values + and then pass that into the second query. That is, execute two queries + instead of one:: + + values = Blog.objects.filter( + name__contains='Cheddar').values_list('pk', flat=True) + entries = Entry.objects.filter(blog__in=list(values)) + + Note the ``list()`` call around the Blog ``QuerySet`` to force execution of + the first query. Without it, a nested query would be executed, because + :ref:`querysets-are-lazy`. + +.. fieldlookup:: gt + +gt +~~ + +Greater than. + +Example:: + + Entry.objects.filter(id__gt=4) + +SQL equivalent:: + + SELECT ... WHERE id > 4; + +.. fieldlookup:: gte + +gte +~~~ + +Greater than or equal to. + +.. fieldlookup:: lt + +lt +~~ + +Less than. + +.. fieldlookup:: lte + +lte +~~~ + +Less than or equal to. + +.. fieldlookup:: startswith + +startswith +~~~~~~~~~~ + +Case-sensitive starts-with. + +Example:: + + Entry.objects.filter(headline__startswith='Will') + +SQL equivalent:: + + SELECT ... WHERE headline LIKE 'Will%'; + +SQLite doesn't support case-sensitive ``LIKE`` statements; ``startswith`` acts +like ``istartswith`` for SQLite. + +.. fieldlookup:: istartswith + +istartswith +~~~~~~~~~~~ + +Case-insensitive starts-with. + +Example:: + + Entry.objects.filter(headline__istartswith='will') + +SQL equivalent:: + + SELECT ... WHERE headline ILIKE 'Will%'; + +.. admonition:: SQLite users + + When using the SQLite backend and Unicode (non-ASCII) strings, bear in + mind the :ref:`database note <sqlite-string-matching>` about string + comparisons. + +.. fieldlookup:: endswith + +endswith +~~~~~~~~ + +Case-sensitive ends-with. + +Example:: + + Entry.objects.filter(headline__endswith='cats') + +SQL equivalent:: + + SELECT ... WHERE headline LIKE '%cats'; + +SQLite doesn't support case-sensitive ``LIKE`` statements; ``endswith`` acts +like ``iendswith`` for SQLite. + +.. fieldlookup:: iendswith + +iendswith +~~~~~~~~~ + +Case-insensitive ends-with. + +Example:: + + Entry.objects.filter(headline__iendswith='will') + +SQL equivalent:: + + SELECT ... WHERE headline ILIKE '%will' + +.. admonition:: SQLite users + + When using the SQLite backend and Unicode (non-ASCII) strings, bear in + mind the :ref:`database note <sqlite-string-matching>` about string + comparisons. + +.. fieldlookup:: range + +range +~~~~~ + +Range test (inclusive). + +Example:: + + start_date = datetime.date(2005, 1, 1) + end_date = datetime.date(2005, 3, 31) + Entry.objects.filter(pub_date__range=(start_date, end_date)) + +SQL equivalent:: + + SELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31'; + +You can use ``range`` anywhere you can use ``BETWEEN`` in SQL -- for dates, +numbers and even characters. + +.. fieldlookup:: year + +year +~~~~ + +For date/datetime fields, exact year match. Takes a four-digit year. + +Example:: + + Entry.objects.filter(pub_date__year=2005) + +SQL equivalent:: + + SELECT ... WHERE EXTRACT('year' FROM pub_date) = '2005'; + +(The exact SQL syntax varies for each database engine.) + +.. fieldlookup:: month + +month +~~~~~ + +For date/datetime fields, exact month match. Takes an integer 1 (January) +through 12 (December). + +Example:: + + Entry.objects.filter(pub_date__month=12) + +SQL equivalent:: + + SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12'; + +(The exact SQL syntax varies for each database engine.) + +.. fieldlookup:: day + +day +~~~ + +For date/datetime fields, exact day match. + +Example:: + + Entry.objects.filter(pub_date__day=3) + +SQL equivalent:: + + SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3'; + +(The exact SQL syntax varies for each database engine.) + +Note this will match any record with a pub_date on the third day of the month, +such as January 3, July 3, etc. + +.. fieldlookup:: week_day + +week_day +~~~~~~~~ + +.. versionadded:: 1.1 + +For date/datetime fields, a 'day of the week' match. + +Takes an integer value representing the day of week from 1 (Sunday) to 7 +(Saturday). + +Example:: + + Entry.objects.filter(pub_date__week_day=2) + +(No equivalent SQL code fragment is included for this lookup because +implementation of the relevant query varies among different database engines.) + +Note this will match any record with a pub_date that falls on a Monday (day 2 +of the week), regardless of the month or year in which it occurs. Week days +are indexed with day 1 being Sunday and day 7 being Saturday. + +.. fieldlookup:: isnull + +isnull +~~~~~~ + +Takes either ``True`` or ``False``, which correspond to SQL queries of +``IS NULL`` and ``IS NOT NULL``, respectively. + +Example:: + + Entry.objects.filter(pub_date__isnull=True) + +SQL equivalent:: + + SELECT ... WHERE pub_date IS NULL; + +.. fieldlookup:: search + +search +~~~~~~ + +A boolean full-text search, taking advantage of full-text indexing. This is +like ``contains`` but is significantly faster due to full-text indexing. + +Example:: + + Entry.objects.filter(headline__search="+Django -jazz Python") + +SQL equivalent:: + + SELECT ... WHERE MATCH(tablename, headline) AGAINST (+Django -jazz Python IN BOOLEAN MODE); + +Note this is only available in MySQL and requires direct manipulation of the +database to add the full-text index. By default Django uses BOOLEAN MODE for +full text searches. `See the MySQL documentation for additional details. +<http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html>`_ + + +.. fieldlookup:: regex + +regex +~~~~~ + +.. versionadded:: 1.0 + +Case-sensitive regular expression match. + +The regular expression syntax is that of the database backend in use. +In the case of SQLite, which has no built in regular expression support, +this feature is provided by a (Python) user-defined REGEXP function, and +the regular expression syntax is therefore that of Python's ``re`` module. + +Example:: + + Entry.objects.get(title__regex=r'^(An?|The) +') + +SQL equivalents:: + + SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL + + SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'c'); -- Oracle + + SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL + + SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite + +Using raw strings (e.g., ``r'foo'`` instead of ``'foo'``) for passing in the +regular expression syntax is recommended. + +.. fieldlookup:: iregex + +iregex +~~~~~~ + +.. versionadded:: 1.0 + +Case-insensitive regular expression match. + +Example:: + + Entry.objects.get(title__iregex=r'^(an?|the) +') + +SQL equivalents:: + + SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL + + SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle + + SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL + + SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite + +.. _aggregation-functions: + +Aggregation Functions +--------------------- + +.. versionadded:: 1.1 + +Django provides the following aggregation functions in the +``django.db.models`` module. For details on how to use these +aggregate functions, see +:doc:`the topic guide on aggregation </topics/db/aggregation>`. + +Avg +~~~ + +.. class:: Avg(field) + +Returns the mean value of the given field. + + * Default alias: ``<field>__avg`` + * Return type: float + +Count +~~~~~ + +.. class:: Count(field, distinct=False) + +Returns the number of objects that are related through the provided field. + + * Default alias: ``<field>__count`` + * Return type: integer + +Has one optional argument: + +.. attribute:: distinct + + If distinct=True, the count will only include unique instances. This has + the SQL equivalent of ``COUNT(DISTINCT field)``. Default value is ``False``. + +Max +~~~ + +.. class:: Max(field) + +Returns the maximum value of the given field. + + * Default alias: ``<field>__max`` + * Return type: same as input field + +Min +~~~ + +.. class:: Min(field) + +Returns the minimum value of the given field. + + * Default alias: ``<field>__min`` + * Return type: same as input field + +StdDev +~~~~~~ + +.. class:: StdDev(field, sample=False) + +Returns the standard deviation of the data in the provided field. + + * Default alias: ``<field>__stddev`` + * Return type: float + +Has one optional argument: + +.. attribute:: sample + + By default, ``StdDev`` returns the population standard deviation. However, + if ``sample=True``, the return value will be the sample standard deviation. + +.. admonition:: SQLite + + SQLite doesn't provide ``StdDev`` out of the box. An implementation is + available as an extension module for SQLite. Consult the SQlite + documentation for instructions on obtaining and installing this extension. + +Sum +~~~ + +.. class:: Sum(field) + +Computes the sum of all values of the given field. + + * Default alias: ``<field>__sum`` + * Return type: same as input field + +Variance +~~~~~~~~ + +.. class:: Variance(field, sample=False) + +Returns the variance of the data in the provided field. + + * Default alias: ``<field>__variance`` + * Return type: float + +Has one optional argument: + +.. attribute:: sample + + By default, ``Variance`` returns the population variance. However, + if ``sample=True``, the return value will be the sample variance. + +.. admonition:: SQLite + + SQLite doesn't provide ``Variance`` out of the box. An implementation is + available as an extension module for SQLite. Consult the SQlite + documentation for instructions on obtaining and installing this extension. diff --git a/parts/django/docs/ref/models/relations.txt b/parts/django/docs/ref/models/relations.txt new file mode 100644 index 0000000..ee6bcdd --- /dev/null +++ b/parts/django/docs/ref/models/relations.txt @@ -0,0 +1,105 @@ +========================= +Related objects reference +========================= + +.. currentmodule:: django.db.models.fields.related + +.. class:: RelatedManager + + A "related manager" is a manager used in a one-to-many or many-to-many + related context. This happens in two cases: + + * The "other side" of a :class:`~django.db.models.ForeignKey` relation. + That is:: + + class Reporter(models.Model): + ... + + class Article(models.Model): + reporter = models.ForeignKey(Reporter) + + In the above example, the methods below will be available on + the manager ``reporter.article_set``. + + * Both sides of a :class:`~django.db.models.ManyToManyField` relation:: + + class Topping(models.Model): + ... + + class Pizza(models.Model): + toppings = models.ManyToManyField(Topping) + + In this example, the methods below will be available both on + ``topping.pizza_set`` and on ``pizza.toppings``. + + These related managers have some extra methods: + + .. method:: add(obj1, [obj2, ...]) + + Adds the specified model objects to the related object set. + + Example:: + + >>> b = Blog.objects.get(id=1) + >>> e = Entry.objects.get(id=234) + >>> b.entry_set.add(e) # Associates Entry e with Blog b. + + .. method:: create(**kwargs) + + Creates a new object, saves it and puts it in the related object set. + Returns the newly created object:: + + >>> b = Blog.objects.get(id=1) + >>> e = b.entry_set.create( + ... headline='Hello', + ... body_text='Hi', + ... pub_date=datetime.date(2005, 1, 1) + ... ) + + # No need to call e.save() at this point -- it's already been saved. + + This is equivalent to (but much simpler than):: + + >>> b = Blog.objects.get(id=1) + >>> e = Entry( + ... blog=b, + ... headline='Hello', + ... body_text='Hi', + ... pub_date=datetime.date(2005, 1, 1) + ... ) + >>> e.save(force_insert=True) + + Note that there's no need to specify the keyword argument of the model + that defines the relationship. In the above example, we don't pass the + parameter ``blog`` to ``create()``. Django figures out that the new + ``Entry`` object's ``blog`` field should be set to ``b``. + + .. method:: remove(obj1, [obj2, ...]) + + Removes the specified model objects from the related object set:: + + >>> b = Blog.objects.get(id=1) + >>> e = Entry.objects.get(id=234) + >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. + + In order to prevent database inconsistency, this method only exists on + :class:`~django.db.models.ForeignKey` objects where ``null=True``. If + the related field can't be set to ``None`` (``NULL``), then an object + can't be removed from a relation without being added to another. In the + above example, removing ``e`` from ``b.entry_set()`` is equivalent to + doing ``e.blog = None``, and because the ``blog`` + :class:`~django.db.models.ForeignKey` doesn't have ``null=True``, this + is invalid. + + .. method:: clear() + + Removes all objects from the related object set:: + + >>> b = Blog.objects.get(id=1) + >>> b.entry_set.clear() + + Note this doesn't delete the related objects -- it just disassociates + them. + + Just like ``remove()``, ``clear()`` is only available on + :class:`~django.db.models.ForeignKey`\s where ``null=True``. |