From 2dc2ed87e5bbf993b2189f33cc0310521dbc8801 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sat, 7 Aug 2010 14:26:07 +0000 Subject: [PATCH] Fixed #11800 -- Updated Sphinx metadata in queryset docs. Thanks to timo for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@13548 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/admin/index.txt | 15 +++++++-------- docs/ref/models/querysets.txt | 11 ----------- docs/releases/1.1-beta-1.txt | 23 ++++++++++++----------- docs/releases/1.1.txt | 5 +++-- docs/topics/db/aggregation.txt | 2 +- docs/topics/db/optimization.txt | 13 +++++++------ docs/topics/db/sql.txt | 6 +++--- 7 files changed, 33 insertions(+), 42 deletions(-) diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index d527b30ced..9a4a12af87 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -474,17 +474,16 @@ change list page. By default, this is set to ``100``. .. attribute:: ModelAdmin.list_select_related -Set ``list_select_related`` to tell Django to use ``select_related()`` in -retrieving the list of objects on the admin change list page. This can save you -a bunch of database queries. +Set ``list_select_related`` to tell Django to use +:meth:`~django.db.models.QuerySet.select_related` in retrieving the list of +objects on the admin change list page. This can save you a bunch of database +queries. The value should be either ``True`` or ``False``. Default is ``False``. -Note that Django will use ``select_related()``, regardless of this setting, -if one of the ``list_display`` fields is a ``ForeignKey``. - -For more on ``select_related()``, see -:ref:`the select_related() docs `. +Note that Django will use :meth:`~django.db.models.QuerySet.select_related`, +regardless of this setting, if one of the ``list_display`` fields is a +``ForeignKey``. .. attribute:: ModelAdmin.inlines diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 56ff6444e4..91d1415043 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -332,8 +332,6 @@ a model which defines a default ordering, or when using ordering was undefined prior to calling ``reverse()``, and will remain undefined afterward). -.. _queryset-distinct: - ``distinct()`` ~~~~~~~~~~~~~~ @@ -367,9 +365,6 @@ query spans multiple tables, it's possible to get duplicate results when a ``values()`` together, be careful when ordering by fields not in the ``values()`` call. - -.. _queryset-values: - ``values(*fields)`` ~~~~~~~~~~~~~~~~~~~ @@ -679,8 +674,6 @@ related object. ``OneToOneFields`` will not be traversed in the reverse direction if you are performing a depth-based ``select_related``. -.. _queryset-extra: - ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -843,8 +836,6 @@ of the arguments is required, but you should use at least one of them. Entry.objects.extra(where=['headline=%s'], params=['Lennon']) -.. _queryset-defer: - ``defer(*fields)`` ~~~~~~~~~~~~~~~~~~ @@ -1143,8 +1134,6 @@ Example:: If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. -.. _queryset-iterator: - ``iterator()`` ~~~~~~~~~~~~~~ diff --git a/docs/releases/1.1-beta-1.txt b/docs/releases/1.1-beta-1.txt index a433efc33c..e7dcb4633d 100644 --- a/docs/releases/1.1-beta-1.txt +++ b/docs/releases/1.1-beta-1.txt @@ -71,8 +71,9 @@ processing to convert them to Python objects. If you know you don't need those particular fields, you can now tell Django not to retrieve them from the database. -You'll do this with the :ref:`new queryset methods ` -``defer()`` and ``only()``. +You'll do this with the new queryset methods +:meth:`~django.db.models.QuerySet.defer` and +:meth:`~django.db.models.QuerySet.only`. New admin features ------------------ @@ -108,13 +109,13 @@ A couple of small but very useful improvements have been made to the * The test :class:`Client` now can automatically follow redirects with the ``follow`` argument to :meth:`Client.get` and :meth:`Client.post`. This makes testing views that issue redirects simpler. - + * It's now easier to get at the template context in the response returned the test client: you'll simply access the context as ``request.context[key]``. The old way, which treats ``request.context`` as a list of contexts, one for each rendered template, is still available if you need it. - + Conditional view processing --------------------------- @@ -133,23 +134,23 @@ release, including: * The :djadmin:`dumpdata` management command now accepts individual model names as arguments, allowing you to export the data just from particular models. - + * There's a new :tfilter:`safeseq` template filter which works just like :tfilter:`safe` for lists, marking each item in the list as safe. - + * :ref:`Cache backends ` now support ``incr()`` and ``decr()`` commands to increment and decrement the value of a cache key. On cache backends that support atomic increment/decrement -- most notably, the memcached backend -- these operations will be atomic, and quite fast. - + * Django now can :ref:`easily delegate authentication to the web server ` via a new authentication backend that supports the standard ``REMOTE_USER`` environment variable used for this purpose. - + * There's a new :func:`django.shortcuts.redirect` function that makes it easier to issue redirects given an object, a view name, or a URL. - + * The ``postgresql_psycopg2`` backend now supports :ref:`native PostgreSQL autocommit `. This is an advanced, PostgreSQL-specific feature, that can make certain read-heavy applications a good deal @@ -183,7 +184,7 @@ central place to search for open issues: * http://code.djangoproject.com/timeline Please open new tickets if no existing ticket corresponds to a problem you're -running into. +running into. Additionally, discussion of Django development, including progress toward the 1.1 release, takes place daily on the django-developers mailing list: @@ -195,7 +196,7 @@ interested in helping out with Django's development, feel free to join the discussions there. Django's online documentation also includes pointers on how to contribute to -Django: +Django: * :ref:`How to contribute to Django ` diff --git a/docs/releases/1.1.txt b/docs/releases/1.1.txt index edb7cf1af2..30ef9197c7 100644 --- a/docs/releases/1.1.txt +++ b/docs/releases/1.1.txt @@ -258,8 +258,9 @@ processing to convert them to Python objects. If you know you don't need those particular fields, you can now tell Django not to retrieve them from the database. -You'll do this with the :ref:`new queryset methods ` -``defer()`` and ``only()``. +You'll do this with the new queryset methods +:meth:`~django.db.models.QuerySet.defer` and +:meth:`~django.db.models.QuerySet.only`. Testing improvements -------------------- diff --git a/docs/topics/db/aggregation.txt b/docs/topics/db/aggregation.txt index 087c1bf239..41580c94b6 100644 --- a/docs/topics/db/aggregation.txt +++ b/docs/topics/db/aggregation.txt @@ -353,7 +353,7 @@ without any harmful effects, since that is already playing a role in the query. This behavior is the same as that noted in the queryset documentation for -:ref:`distinct() ` and the general rule is the same: +:meth:`~django.db.models.QuerySet.distinct` and the general rule is the same: normally you won't want extra columns playing a part in the result, so clear out the ordering, or at least make sure it's restricted only to those fields you also select in a ``values()`` call. diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 5d74fc9ce9..bb40139f23 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -101,7 +101,7 @@ Use ``iterator()`` When you have a lot of objects, the caching behaviour of the ``QuerySet`` can cause a large amount of memory to be used. In this case, -:ref:`QuerySet.iterator() ` may help. +:meth:`~django.db.models.QuerySet.iterator()` may help. Do database work in the database rather than in Python ====================================================== @@ -121,9 +121,9 @@ If these aren't enough to generate the SQL you need: Use ``QuerySet.extra()`` ------------------------ -A less portable but more powerful method is :ref:`QuerySet.extra() -`, which allows some SQL to be explicitly added to the query. -If that still isn't powerful enough: +A less portable but more powerful method is +:meth:`~django.db.models.QuerySet.extra()`, which allows some SQL to be +explicitly added to the query. If that still isn't powerful enough: Use raw SQL ----------- @@ -159,7 +159,7 @@ Use ``QuerySet.values()`` and ``values_list()`` ----------------------------------------------- When you just want a dict/list of values, and don't need ORM model objects, make -appropriate usage of :ref:`QuerySet.values() `. +appropriate usage of :meth:`~django.db.models.QuerySet.values()`. These can be useful for replacing model objects in template code - as long as the dicts you supply have the same attributes as those used in the template, you are fine. @@ -167,7 +167,8 @@ are fine. Use ``QuerySet.defer()`` and ``only()`` --------------------------------------- -Use :ref:`defer() and only() ` if there are database columns you +Use :meth:`~django.db.models.QuerySet.defer()` and +:meth:`~django.db.models.QuerySet.only()` if there are database columns you know that you won't need (or won't need in most cases) to avoid loading them. Note that if you *do* use them, the ORM will have to go and get them in a separate query, making this a pessimization if you use it inappropriately. diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index f55a164373..c3272da757 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -116,9 +116,9 @@ Fields may also be left out:: >>> people = Person.objects.raw('SELECT id, first_name FROM myapp_person') -The ``Person`` objects returned by this query will be :ref:`deferred -` model instances. This means that the fields that are omitted -from the query will be loaded on demand. For example:: +The ``Person`` objects returned by this query will be deferred model instances +(see :meth:`~django.db.models.QuerySet.defer()`). This means that the fields +that are omitted from the query will be loaded on demand. For example:: >>> for p in Person.objects.raw('SELECT id, first_name FROM myapp_person'): ... print p.first_name, # This will be retrieved by the original query