diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index ca3b8aa31c..c0aa840b61 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -74,7 +74,7 @@ You can evaluate a ``QuerySet`` in the following ways: 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). + use :meth:`exists() ` (see below). .. _pickling QuerySets: @@ -119,8 +119,8 @@ described here. QuerySet API ============ -Though you usually won't create one manually -- you'll go through a -:class:`~django.db.models.Manager` -- here's the formal declaration of a +Though you usually won't create one manually — you'll go through a +:class:`~django.db.models.Manager` — here's the formal declaration of a ``QuerySet``: .. class:: QuerySet([model=None, query=None, using=None]) @@ -135,8 +135,9 @@ Though you usually won't create one manually -- you'll go through a .. attribute:: ordered - ``True`` if the ``QuerySet`` is ordered -- i.e. has an order_by() - clause or a default ordering on the model. ``False`` otherwise. + ``True`` if the ``QuerySet`` is ordered — i.e. has an + :meth:`order_by()` clause or a default ordering on the model. + ``False`` otherwise. .. attribute:: db @@ -281,7 +282,8 @@ and so on for as many models as you want to join. For example:: 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:: +primary key if there is no :attr:`Meta.ordering +` specified. For example:: Entry.objects.order_by('blog') @@ -292,23 +294,24 @@ primary key if there is no ``Meta.ordering`` specified. For example:: ...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 +:meth:`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. +example, a :class:`~django.db.models.ManyToManyField` 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. 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. +ordering, call :meth:`order_by()` with no parameters. You can tell if a query is ordered or not by checking the :attr:`.QuerySet.ordered` attribute, which will be ``True`` if the @@ -334,13 +337,12 @@ penultimate item and so on. If we had a Python sequence and looked at 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). +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 :meth:`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 ~~~~~~~~ @@ -358,30 +360,29 @@ query spans multiple tables, it's possible to get duplicate results when a .. 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. + ``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 + Similarly, if you use a :meth:`values()` query to restrict the columns + selected, the columns used in any :meth:`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. + :meth:`values()` together, be careful when ordering by fields not in the + :meth:`values()` call. values ~~~~~~ .. method:: values(*fields) -Returns a ``ValuesQuerySet`` -- a ``QuerySet`` that returns dictionaries when -used as an iterable, rather than model-instance objects. +Returns a ``ValuesQuerySet`` — a ``QuerySet`` subclass 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. @@ -397,11 +398,11 @@ objects:: >>> 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. +The ``values()`` method 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:: @@ -432,15 +433,15 @@ A few subtleties that are worth mentioning: >>> Entry.objects.values('blog_id') [{'blog_id': 1}, ...] - * When using ``values()`` together with ``distinct()``, be aware that + * When using ``values()`` together with :meth:`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 :py:meth:`extra()` call, - any fields defined by a ``select`` argument in the :py:meth:`extra()` - must be explicitly included in the ``values()`` call. Any - :py:meth:`extra()` call made after a ``values()`` call will have its - extra selected fields ignored. + * If you use a ``values()`` clause after an :meth:`extra()` call, + any fields defined by a ``select`` argument in the :meth:`extra()` must + be explicitly included in the ``values()`` call. Any :meth:`extra()` call + made after a ``values()`` call will have its extra selected fields + ignored. 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 @@ -488,7 +489,7 @@ values_list 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 +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') @@ -514,7 +515,7 @@ dates .. method:: dates(field, kind, order='ASC') -Returns a ``DateQuerySet`` -- a ``QuerySet`` that evaluates to a list of +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``. @@ -526,8 +527,10 @@ model. ``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. + * ``"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. @@ -550,10 +553,10 @@ none .. method:: none() -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.) +Returns an ``EmptyQuerySet`` — a ``QuerySet`` subclass 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:: @@ -565,11 +568,10 @@ all .. method:: all() -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. +Returns a *copy* of the current ``QuerySet`` (or ``QuerySet`` subclass). This +can be useful in situations where you might want to pass in either a model +manager or a ``QuerySet`` and do further filtering on the result. After calling +``all()`` on either object, you'll definitely have a ``QuerySet`` to work with. .. _select-related: @@ -671,23 +673,24 @@ This is also valid:: ...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``. This 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. +You can refer to any :class:`~django.db.models.ForeignKey` or +:class:`~django.db.models.OneToOneField` relation in the list of fields +passed to ``select_related()``. This includes foreign keys that have +``null=True`` (which are omitted in a no-parameter ``select_related()`` call). +It's an error to use both a list of fields and the ``depth`` parameter in the +same ``select_related()`` call; they are conflicting options. .. 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. +You can also refer to the reverse direction of a +:class:`~django.db.models.OneToOneField`` in the list of fields passed to +``select_related`` — that is, you can traverse a +:class:`~django.db.models.OneToOneField` back to the object on which the field +is defined. Instead of specifying the field name, use the :attr:`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``. +A :class:`~django.db.models.OneToOneField` is not traversed in the reverse +direction if you are performing a depth-based ``select_related()`` call. extra ~~~~~ @@ -696,7 +699,7 @@ extra 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 +``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 @@ -707,17 +710,17 @@ 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. + 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. + ``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 @@ -737,26 +740,27 @@ of the arguments is required, but you should use at least one of them. }, ) - (In this particular case, we're exploiting the fact that the query will - already contain the ``blog_blog`` table in its ``FROM`` clause.) + 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 + Note that the parentheses 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. - 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. + 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 + :class:`django.utils.datastructures.SortedDict` for the ``select`` + value, not just a normal Python dictionary. This will work, for example:: @@ -771,8 +775,8 @@ of the arguments is required, but you should use at least one of them. 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 + 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`` @@ -786,61 +790,62 @@ of the arguments is required, but you should use at least one of them. 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. + 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. + 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()``. + 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 + :meth:`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 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). + 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. + 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.) + 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:: @@ -858,9 +863,9 @@ defer 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. +using the results of a queryset in some situation where you know you don't know +if you need those particular fields when you initially fetch the data, 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()``:: @@ -881,7 +886,7 @@ 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 +loading via :meth:`select_related()`) by using the standard double-underscore notation to separate related fields:: Blog.objects.select_related().defer("entry__headline", "entry__body") @@ -894,19 +899,17 @@ to ``defer()``:: 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). +:meth:`select_related()` to retrieve related models, 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. + The ``defer()`` method (and its cousin, :meth:`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. Even if you think you are in the advanced use-case situation, **only use defer() when you cannot, at queryset load time, determine if you will need @@ -915,11 +918,11 @@ eventually). normalize your models and put the non-loaded data into a separate model (and database table). If the columns *must* stay in the one table for some reason, create a model with ``Meta.managed = False`` (see the - :py:attr:`managed attribute ` - documentation) containing just the fields you normally need to load and use - that where you might otherwise call ``defer()``. This makes your code more - explicit to the reader, is slightly faster and consumes a little less - memory in the Python process. + :attr:`managed attribute ` documentation) + containing just the fields you normally need to load and use that where you + might otherwise call ``defer()``. This makes your code more explicit to the + reader, is slightly faster and consumes a little less memory in the Python + process. only @@ -927,13 +930,13 @@ only .. method:: only(*fields) -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 +The ``only()`` method is more or less the opposite of :meth:`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 can result in simpler code. -If you have a model with fields ``name``, ``age`` and ``biography``, the +Suppose 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") @@ -958,7 +961,7 @@ logically:: # existing set of fields). Entry.objects.defer("body").only("headline", "body") -All of the cautions in the note for the :py:meth:`defer` documentation apply to +All of the cautions in the note for the :meth:`defer` documentation apply to ``only()`` as well. Use it cautiously and only after exhausting your other options. @@ -1004,21 +1007,23 @@ Usually, if another transaction has already acquired a lock on one of the selected rows, the query will block until the lock is released. If this is not the behavior you want, call ``select_for_update(nowait=True)``. This will make the call non-blocking. If a conflicting lock is already acquired by -another transaction, ``django.db.utils.DatabaseError`` will be raised when -the queryset is evaluated. +another transaction, :exc:`~django.db.DatabaseError` will be raised when the +queryset is evaluated. -Note that using ``select_for_update`` will cause the current transaction to be -set dirty, if under transaction management. This is to ensure that Django issues -a ``COMMIT`` or ``ROLLBACK``, releasing any locks held by the ``SELECT FOR -UPDATE``. +Note that using ``select_for_update()`` will cause the current transaction to be +considered dirty, if under transaction management. This is to ensure that +Django issues a ``COMMIT`` or ``ROLLBACK``, releasing any locks held by the +``SELECT FOR UPDATE``. -Currently, the ``postgresql_psycopg2``, ``oracle``, and ``mysql`` -database backends support ``select_for_update()``. However, MySQL has no -support for the ``nowait`` argument. +Currently, the ``postgresql_psycopg2``, ``oracle``, and ``mysql`` database +backends support ``select_for_update()``. However, MySQL has no support for the +``nowait`` argument. Obviously, users of external third-party backends should +check with their backend's documentation for specifics in those cases. Passing ``nowait=True`` to ``select_for_update`` using database backends that -do not support ``nowait``, such as MySQL, will cause a ``DatabaseError`` to be -raised. This is in order to prevent code unexpectedly blocking. +do not support ``nowait``, such as MySQL, will cause a +:exc:`~django.db.DatabaseError` to be raised. This is in order to prevent code +unexpectedly blocking. Using ``select_for_update`` on backends which do not support ``SELECT ... FOR UPDATE`` (such as SQLite) will have no effect. @@ -1040,19 +1045,20 @@ get 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 :exc:`~django.core.exceptions.MultipleObjectsReturned` if more +than one object was found. The +:exc:`~django.core.excpetions.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:: +``get()`` raises a :exc:`~django.core.exceptions.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:: +The :exc:`~django.core.exceptions.DoesNotExist` exception inherits from +:exc:`django.core.exceptions.ObjectDoesNotExist`, so you can target multiple +:exc:`~django.core.exceptions.DoesNotExist` exceptions. Example:: from django.core.exceptions import ObjectDoesNotExist try: @@ -1082,8 +1088,8 @@ 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:`~django.db.IntegrityError` since primary keys must be unique. So remember -to be prepared to handle the exception if you are using manual primary keys. +:exc:`~django.db.IntegrityError` since primary keys must be unique. Be +prepared to handle the exception if you are using manual primary keys. get_or_create ~~~~~~~~~~~~~ @@ -1112,12 +1118,12 @@ 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:: +Any keyword arguments passed to ``get_or_create()`` — *except* an optional one +called ``defaults`` — will be used in a :meth:`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]) @@ -1139,11 +1145,10 @@ If you have a field named ``defaults`` and want to use it as an exact lookup in Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'}) - -The ``get_or_create()`` method has similar error behavior 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. +The ``get_or_create()`` method has similar error behavior to :meth:`create()` +when you're using manually specified primary keys. If an object needs to be +created and the key already exists in the database, an +:exc:`~django.db.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 @@ -1161,7 +1166,7 @@ count .. method:: count() Returns an integer representing the number of objects in the database matching -the ``QuerySet``. ``count()`` never raises exceptions. +the ``QuerySet``. The ``count()`` method never raises exceptions. Example:: @@ -1171,8 +1176,8 @@ Example:: # 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 +A ``count()`` call 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). @@ -1205,16 +1210,17 @@ 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 +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. In contrast, +``iterator()`` will read results directly, without doing any caching at the +``QuerySet`` level (internally, the default iterator calls ``iterator()`` and +caches the return value). For a ``QuerySet`` which returns a large number of +objects that you only need to access once, this can 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. +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/ @@ -1231,12 +1237,14 @@ This example returns the latest ``Entry`` in the table, according to the 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. +If your model's :ref:`Meta ` specifies +:attr:`~django.db.models.Options.get_latest_by`, you can leave off the +``field_name`` argument to ``latest()``. Django will use the field specified +in :attr:`~django.db.models.Options.get_latest_by` by default. -Like ``get()``, ``latest()`` raises ``DoesNotExist`` if an object doesn't -exist with the given parameters. +Like :meth:`get()`, ``latest()`` raises +:exc:`~django.core.exceptions.DoesNotExist` if there is no object with the given +parameters. Note ``latest()`` exists purely for convenience and readability. @@ -1245,20 +1253,20 @@ aggregate .. method:: aggregate(*args, **kwargs) -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. +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. +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. +Aggregates specified using keyword arguments will use the keyword as the name +for the annotation. Anonymous arguments will have a 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:: +For example, when you are working with 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} @@ -1283,10 +1291,11 @@ 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 +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)``. +more overall work (one query for the existence check plus an extra one to later +retrieve the results) than simply using ``bool(some_query_set)``, which +retrieves the results and then checks if any were returned. update ~~~~~~ @@ -1303,7 +1312,7 @@ you could do this:: (This assumes your ``Entry`` model has fields ``pub_date`` and ``comments_on``.) -You can update multiple fields -- there's no limit on how many. For example, +You can update multiple fields — there's no limit on how many. For example, here we update the ``comments_on`` and ``headline`` fields:: >>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old') @@ -1333,8 +1342,8 @@ The ``update()`` method returns the number of affected rows:: 132 If you're just updating a record and don't need to do anything with the model -object, you should use ``update()`` rather than loading the model object into -memory. The former is more efficient. For example, instead of doing this:: +object, the most efficient approach is to call ``update()``, rather than +loading the model object into memory. For example, instead of doing this:: e = Entry.objects.get(id=10) e.comments_on = False @@ -1344,15 +1353,18 @@ memory. The former is more efficient. For example, instead of doing this:: Entry.objects.filter(id=10).update(comments_on=False) -Using ``update()`` instead of loading the object into memory also prevents a -race condition where something might change in your database in the short -period of time between loading the object and calling ``save()``. +Using ``update()`` also prevents a race condition wherein something might +change in your database in the short period of time between loading the object +and calling ``save()``. -Finally, note that the ``update()`` method does an update at the SQL level and, -thus, 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()``). If you want to update a bunch of records for a model that has a -custom ``save()`` method, loop over them and call ``save()``, like this:: +Finally, realize that ``update()`` does an update at the SQL level and, thus, +does not call any ``save()`` methods on your models, nor does it emit the +:attr:`~django.db.models.signals.pre_save` or +:attr:`~django.db.models.signals.post_save` signals (which are a consequence of +calling :meth:`Model.save() <~django.db.models.Model.save()>`). If you want to +update a bunch of records for a model that has a custom +:meth:`~django.db.models.Model.save()`` method, loop over them and call +:meth:`~django.db.models.Model.save()`, like this:: for e in Entry.objects.filter(pub_date__year=2010): e.comments_on = False @@ -1376,7 +1388,7 @@ For example, to delete all the entries in a particular blog:: >>> Entry.objects.filter(blog=b).delete() By default, Django's :class:`~django.db.models.ForeignKey` emulates the SQL -constraint ``ON DELETE CASCADE`` -- in other words, any objects with foreign +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:: @@ -1401,18 +1413,19 @@ 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()``. +specified as keyword arguments to the ``QuerySet`` methods :meth:`filter()`, +:meth:`exclude()` and :meth:`get()`. -For an introduction, see :ref:`field-lookups-intro`. +For an introduction, see :ref:`models and database queries documentation +`. .. 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). +Exact match. If the value provided for comparison is ``None``, it will be +interpreted as an SQL ``NULL`` (see :lookup:`isnull` for more details). Examples:: @@ -1473,8 +1486,8 @@ SQL equivalent:: SELECT ... WHERE headline LIKE '%Lennon%'; -Note this will match the headline ``'Today Lennon honored'`` but not -``'today lennon honored'``. +Note this will match the headline ``'Lennon honored today'`` but not ``'lennon +honored today'``. .. admonition:: SQLite users @@ -1667,8 +1680,11 @@ SQL equivalent:: SELECT ... WHERE headline LIKE '%cats'; -SQLite doesn't support case-sensitive ``LIKE`` statements; ``endswith`` acts -like ``iendswith`` for SQLite. +.. admonition:: SQLite users + + SQLite doesn't support case-sensitive ``LIKE`` statements; ``endswith`` + acts like ``iendswith`` for SQLite. Refer to the :ref:`database note + ` documentation for more. .. fieldlookup:: iendswith @@ -1708,7 +1724,7 @@ 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, +You can use ``range`` anywhere you can use ``BETWEEN`` in SQL — for dates, numbers and even characters. .. fieldlookup:: year @@ -1733,8 +1749,8 @@ SQL equivalent:: month ~~~~~ -For date/datetime fields, exact month match. Takes an integer 1 (January) -through 12 (December). +For date and datetime fields, an exact month match. Takes an integer 1 +(January) through 12 (December). Example:: @@ -1751,7 +1767,7 @@ SQL equivalent:: day ~~~ -For date/datetime fields, exact day match. +For date and datetime fields, an exact day match. Example:: @@ -1771,7 +1787,7 @@ such as January 3, July 3, etc. week_day ~~~~~~~~ -For date/datetime fields, a 'day of the week' match. +For date and datetime fields, a 'day of the week' match. Takes an integer value representing the day of week from 1 (Sunday) to 7 (Saturday). @@ -1783,8 +1799,8 @@ Example:: (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 +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 @@ -1809,7 +1825,7 @@ 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. +like :lookup:`contains` but is significantly faster due to full-text indexing. Example:: @@ -1821,8 +1837,9 @@ SQL equivalent:: 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. -`_ +full text searches. See the `MySQL documentation`_ for additional details. + +.. _MySQL documentation: http://dev.mysql.com/doc/refman/5.1/en/fulltext-boolean.html> .. fieldlookup:: regex @@ -1986,6 +2003,10 @@ 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. + 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. + +.. _SQLite documentation: http://www.sqlite.org/contrib +