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, 0 insertions, 3909 deletions
diff --git a/parts/django/docs/ref/models/fields.txt b/parts/django/docs/ref/models/fields.txt deleted file mode 100644 index 146ca43..0000000 --- a/parts/django/docs/ref/models/fields.txt +++ /dev/null @@ -1,1063 +0,0 @@ -===================== -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 deleted file mode 100644 index b5896c3..0000000 --- a/parts/django/docs/ref/models/index.txt +++ /dev/null @@ -1,14 +0,0 @@ -====== -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 deleted file mode 100644 index 1730ec6..0000000 --- a/parts/django/docs/ref/models/instances.txt +++ /dev/null @@ -1,570 +0,0 @@ -======================== -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 deleted file mode 100644 index 1b04c46..0000000 --- a/parts/django/docs/ref/models/options.txt +++ /dev/null @@ -1,269 +0,0 @@ -====================== -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 deleted file mode 100644 index 9f0de1f..0000000 --- a/parts/django/docs/ref/models/querysets.txt +++ /dev/null @@ -1,1888 +0,0 @@ -====================== -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 deleted file mode 100644 index ee6bcdd..0000000 --- a/parts/django/docs/ref/models/relations.txt +++ /dev/null @@ -1,105 +0,0 @@ -========================= -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``. |