queryset-refactor: Merged to [6300]

git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@6340 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/authentication.txt

@@ -244,6 +244,9 @@ Anonymous users
 the ``django.contrib.auth.models.User`` interface, with these differences:
 
     * ``id`` is always ``None``.
+    * ``is_staff`` and ``is_superuser`` are always False.
+    * ``is_active`` is always True.
+    * ``groups`` and ``user_permissions`` are always empty.
     * ``is_anonymous()`` returns ``True`` instead of ``False``.
     * ``is_authenticated()`` returns ``False`` instead of ``True``.
     * ``has_perm()`` always returns ``False``.
@@ -992,10 +995,10 @@ Writing an authentication backend
 ---------------------------------
 
 An authentication backend is a class that implements two methods:
-``get_user(id)`` and ``authenticate(**credentials)``.
+``get_user(user_id)`` and ``authenticate(**credentials)``.
 
-The ``get_user`` method takes an ``id`` -- which could be a username, database
-ID or whatever -- and returns a ``User`` object.
+The ``get_user`` method takes a ``user_id`` -- which could be a username,
+database ID or whatever -- and returns a ``User`` object.
 
 The  ``authenticate`` method takes credentials as keyword arguments. Most of
 the time, it'll just look like this::

docs/contributing.txt

@@ -654,10 +654,31 @@ info, with the ``DATABASE_ENGINE`` setting. You will also need a ``ROOT_URLCONF`
 setting (its value is ignored; it just needs to be present) and a ``SITE_ID``
 setting (any non-zero integer value will do) in order for all the tests to pass.
 
-The unit tests will not touch your existing databases; they create a new
-database, called ``django_test_db``, which is deleted when the tests are
-finished. This means your user account needs permission to execute ``CREATE
-DATABASE``.
+If you're using the ``sqlite3`` database backend, no further settings are
+needed. A temporary database will be created in memory when running the tests.
+
+If you're using another backend:
+
+    * Your ``DATABASE_USER`` setting needs to specify an existing user account
+      for the database engine.
+
+    * The ``DATABASE_NAME`` setting must be the name of an existing database to
+      which the given user has permission to connect. The unit tests will not
+      touch this database; the test runner creates a new database whose name is
+      ``DATABASE_NAME`` prefixed with ``test_``, and this test database is
+      deleted when the tests are finished. This means your user account needs
+      permission to execute ``CREATE DATABASE``.
+
+To run a subset of the unit tests, append the names of the test modules to the
+``runtests.py`` command line. See the list of directories in
+``tests/modeltests`` and ``tests/regressiontests`` for module names.
+
+As an example, if Django is not in your ``PYTHONPATH``, you placed
+``settings.py`` in the ``tests/`` directory, and you'd like to only run tests
+for generic relations and internationalization, type::
+
+    PYTHONPATH=..
+    ./runtests.py --settings=settings generic_relations i18n
 
 Requesting features
 ===================

docs/databases.txt

@@ -117,7 +117,7 @@ Here's a sample configuration which uses a MySQL option file::
   [client]
   database = DATABASE_NAME
   user = DATABASE_USER
-  passwd = DATABASE_PASSWORD
+  password = DATABASE_PASSWORD
   default-character-set = utf8
 
 Several other MySQLdb connection options may be useful, such as ``ssl``,

docs/db-api.txt

@@ -511,6 +511,9 @@ 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 table, add the other table's name and a dot,
 like so::
 

docs/fastcgi.txt

@@ -46,9 +46,8 @@ Prerequisite: flup
 ==================
 
 Before you can start using FastCGI with Django, you'll need to install flup_,
-which is a Python library for dealing with FastCGI. Make sure to use the latest
-Subversion snapshot of flup, as some users have reported stalled pages with
-older flup versions.
+which is a Python library for dealing with FastCGI. Version 0.5 or newer should
+work fine.
 
 .. _flup: http://www.saddi.com/software/flup/
 

docs/generic_views.txt

@@ -699,7 +699,10 @@ A page representing a list of objects.
       displayed per page. If this is given, the view will paginate objects with
       ``paginate_by`` objects per page. The view will expect either a ``page``
       query string parameter (via ``GET``) or a ``page`` variable specified in
-      the URLconf. See "Notes on pagination" below.
+      the URLconf. See `Notes on pagination`_ below.
+
+    * ``page``: The current page number, as an integer. This is 1-based. 
+      See `Notes on pagination`_ below.
 
     * ``template_name``: The full name of a template to use in rendering the
       page. This lets you override the default template name (see below).
@@ -775,7 +778,7 @@ If the results are paginated, the context will contain these extra variables:
       page.
 
     * **New in Django development version:** ``page_range``: A list of the 
-    page numbers that are available. This is 1-based.
+      page numbers that are available. This is 1-based.
 
 Notes on pagination
 ~~~~~~~~~~~~~~~~~~~

docs/i18n.txt

@@ -27,21 +27,8 @@ Essentially, Django does two things:
     * It uses these hooks to translate Web apps for particular users according
       to their language preferences.
 
-How to internationalize your app: in three steps
-------------------------------------------------
-
-    1. Embed translation strings in your Python code and templates.
-    2. Get translations for those strings, in whichever languages you want to
-       support.
-    3. Activate the locale middleware in your Django settings.
-
-.. admonition:: Behind the scenes
-
-    Django's translation machinery uses the standard ``gettext`` module that
-    comes with Python.
-
-If you don't need internationalization
-======================================
+If you don't need internationalization in your app
+==================================================
 
 Django's internationalization hooks are on by default, and that means there's a
 bit of i18n-related overhead in certain places of the framework. If you don't
@@ -55,8 +42,21 @@ from your ``TEMPLATE_CONTEXT_PROCESSORS`` setting.
 
 .. _documentation for USE_I18N: ../settings/#use-i18n
 
-How to specify translation strings
-==================================
+If you do need internationalization: three steps
+================================================
+
+    1. Embed translation strings in your Python code and templates.
+    2. Get translations for those strings, in whichever languages you want to
+       support.
+    3. Activate the locale middleware in your Django settings.
+
+.. admonition:: Behind the scenes
+
+    Django's translation machinery uses the standard ``gettext`` module that
+    comes with Python.
+
+1. How to specify translation strings
+=====================================
 
 Translation strings specify "This text should be translated." These strings can
 appear in your Python code and templates. It's your responsibility to mark
@@ -295,7 +295,7 @@ string, so they don't need to be aware of translations.
 .. _Django templates: ../templates_python/
 
 Working with lazy translation objects
-=====================================
+-------------------------------------
 
 Using ``ugettext_lazy()`` and ``ungettext_lazy()`` to mark strings in models
 and utility functions is a common operation. When you're working with these
@@ -305,7 +305,7 @@ convert them to strings, because they should be converted as late as possible
 couple of helper functions.
 
 Joining strings: string_concat()
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Standard Python string joins (``''.join([...])``) will not work on lists
 containing lazy translation objects. Instead, you can use
@@ -324,7 +324,7 @@ strings when ``result`` itself is used in a string (usually at template
 rendering time).
 
 The allow_lazy() decorator
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Django offers many utility functions (particularly in ``django.utils``) that
 take a string as their first argument and do something to that string. These
@@ -359,8 +359,8 @@ Using this decorator means you can write your function and assume that the
 input is a proper string, then add support for lazy translation objects at the
 end.
 
-How to create language files
-============================
+2. How to create language files
+===============================
 
 Once you've tagged your strings for later translation, you need to write (or
 obtain) the language translations themselves. Here's how that works.
@@ -393,7 +393,7 @@ To create or update a message file, run this command::
 
 ...where ``de`` is the language code for the message file you want to create.
 The language code, in this case, is in locale format. For example, it's
-``pt_BR`` for Brazilian Portugese and ``de_AT`` for Austrian German.
+``pt_BR`` for Brazilian Portuguese and ``de_AT`` for Austrian German.
 
 The script should be run from one of three places:
 
@@ -490,8 +490,8 @@ That's it. Your translations are ready for use.
 
     .. _Submitting and maintaining translations: ../contributing/
 
-How Django discovers language preference
-========================================
+3. How Django discovers language preference
+===========================================
 
 Once you've prepared your translations -- or, if you just want to use the
 translations that come with Django -- you'll just need to activate translation
@@ -546,7 +546,7 @@ following this algorithm:
 Notes:
 
     * In each of these places, the language preference is expected to be in the
-      standard language format, as a string. For example, Brazilian Portugese
+      standard language format, as a string. For example, Brazilian Portuguese
       is ``pt-br``.
     * If a base language is available but the sublanguage specified is not,
       Django uses the base language. For example, if a user specifies ``de-at``
@@ -629,44 +629,6 @@ in ``request.LANGUAGE_CODE``.
 .. _session: ../sessions/
 .. _request object: ../request_response/#httprequest-objects
 
-The ``set_language`` redirect view
-==================================
-
-As a convenience, Django comes with a view, ``django.views.i18n.set_language``,
-that sets a user's language preference and redirects back to the previous page.
-
-Activate this view by adding the following line to your URLconf::
-
-    (r'^i18n/', include('django.conf.urls.i18n')),
-
-(Note that this example makes the view available at ``/i18n/setlang/``.)
-
-The view expects to be called via the ``GET`` method, with a ``language``
-parameter set in the query string. If session support is enabled, the view
-saves the language choice in the user's session. Otherwise, it saves the
-language choice in a ``django_language`` cookie.
-
-After setting the language choice, Django redirects the user, following this
-algorithm:
-
-    * Django looks for a ``next`` parameter in the query string.
-    * If that doesn't exist, or is empty, Django tries the URL in the
-      ``Referer`` header.
-    * If that's empty -- say, if a user's browser suppresses that header --
-      then the user will be redirected to ``/`` (the site root) as a fallback.
-
-Here's example HTML template code::
-
-    <form action="/i18n/setlang/" method="get">
-    <input name="next" type="hidden" value="/next/page/" />
-    <select name="language">
-    {% for lang in LANGUAGES %}
-    <option value="{{ lang.0 }}">{{ lang.1 }}</option>
-    {% endfor %}
-    </select>
-    <input type="submit" value="Go" />
-    </form>
-
 Using translations in your own projects
 =======================================
 
@@ -728,6 +690,44 @@ The easiest way out is to store applications that are not part of the project
 connected to your explicit project and not strings that are distributed
 independently.
 
+The ``set_language`` redirect view
+==================================
+
+As a convenience, Django comes with a view, ``django.views.i18n.set_language``,
+that sets a user's language preference and redirects back to the previous page.
+
+Activate this view by adding the following line to your URLconf::
+
+    (r'^i18n/', include('django.conf.urls.i18n')),
+
+(Note that this example makes the view available at ``/i18n/setlang/``.)
+
+The view expects to be called via the ``POST`` method, with a ``language``
+parameter set in request. If session support is enabled, the view
+saves the language choice in the user's session. Otherwise, it saves the
+language choice in a ``django_language`` cookie.
+
+After setting the language choice, Django redirects the user, following this
+algorithm:
+
+    * Django looks for a ``next`` parameter in ``POST`` request.
+    * If that doesn't exist, or is empty, Django tries the URL in the
+      ``Referrer`` header.
+    * If that's empty -- say, if a user's browser suppresses that header --
+      then the user will be redirected to ``/`` (the site root) as a fallback.
+
+Here's example HTML template code::
+
+    <form action="/i18n/setlang/" method="post">
+    <input name="next" type="hidden" value="/next/page/" />
+    <select name="language">
+    {% for lang in LANGUAGES %}
+    <option value="{{ lang.0 }}">{{ lang.1 }}</option>
+    {% endfor %}
+    </select>
+    <input type="submit" value="Go" />
+    </form>
+
 Translations and JavaScript
 ===========================
 
@@ -752,7 +752,7 @@ The main solution to these problems is the ``javascript_catalog`` view, which
 sends out a JavaScript code library with functions that mimic the ``gettext``
 interface, plus an array of translation strings. Those translation strings are
 taken from the application, project or Django core, according to what you
-specify in either the {{{info_dict}}} or the URL.
+specify in either the info_dict or the URL.
 
 You hook it up like this::
 
@@ -817,8 +817,8 @@ pluralizations).
 Creating JavaScript translation catalogs
 ----------------------------------------
 
-You create and update the translation catalogs the same way as the other Django
-translation catalogs -- with the {{{make-messages.py}}} tool. The only
+You create and update the translation catalogs the same way as the other
+Django translation catalogs -- with the make-messages.py tool. The only
 difference is you need to provide a ``-d djangojs`` parameter, like this::
 
     make-messages.py -d djangojs -l de
@@ -827,13 +827,13 @@ This would create or update the translation catalog for JavaScript for German.
 After updating translation catalogs, just run ``compile-messages.py`` the same
 way as you do with normal Django translation catalogs.
 
-Specialities of Django translation
+Specialties of Django translation
 ==================================
 
-If you know ``gettext``, you might note these specialities in the way Django
+If you know ``gettext``, you might note these specialties in the way Django
 does translation:
 
-    * The string domain is ``django`` or ``djangojs``. The string domain is
+    * The string domain is ``django`` or ``djangojs``. This string domain is
       used to differentiate between different programs that store their data
       in a common message-file library (usually ``/usr/share/locale/``). The
       ``django`` domain is used for python and template translation strings
@@ -841,5 +841,5 @@ does translation:
       domain is only used for JavaScript translation catalogs to make sure
       that those are as small as possible.
     * Django doesn't use ``xgettext`` alone. It uses Python wrappers around
-      ``xgettext`` and ``msgfmt``. That's mostly for convenience.
+      ``xgettext`` and ``msgfmt``. This is mostly for convenience.
 

docs/install.txt

@@ -67,6 +67,16 @@ installed.
 
 * If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher.
 
+If you plan to use Django's ``manage.py syncdb`` command to
+automatically create database tables for your models, you'll need to
+ensure that Django has permission to create tables in the database
+you're using; if you plan to manually create the tables, you can
+simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and ``DELETE``
+permissions. Django does not issue ``ALTER TABLE`` statements, and so
+will not require permission to do so. If you will be using Django's
+`testing framework`_ with data fixtures, Django will need permission
+to create a temporary test database.
+
 .. _PostgreSQL: http://www.postgresql.org/
 .. _MySQL: http://www.mysql.com/
 .. _Django's ticket system: http://code.djangoproject.com/report/1
@@ -78,6 +88,7 @@ installed.
 .. _MySQL backend: ../databases/
 .. _cx_Oracle: http://www.python.net/crew/atuining/cx_Oracle/
 .. _Oracle: http://www.oracle.com/
+.. _testing framework: ../testing/
 
 Remove any old versions of Django
 =================================

docs/newforms.txt

@@ -776,6 +776,27 @@ form data *and* file data::
     # Unbound form with a image field
     >>> f = ContactFormWithMugshot()
 
+Testing for multipart forms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're writing reusable views or templates, you may not know ahead of time
+whether your form is a multipart form or not. The ``is_multipart()`` method
+tells you whether the form requires multipart encoding for submission::
+
+    >>> f = ContactFormWithMugshot()
+    >>> f.is_multipart()
+    True
+
+Here's an example of how you might use this in a template::
+
+    {% if form.is_multipart %}
+        <form enctype="multipart/form-data" method="post" action="/foo/">
+    {% else %}
+        <form method="post" action="/foo/">
+    {% endif %}
+    {% form %}
+    </form>
+
 Subclassing forms
 -----------------
 

docs/templates.txt

@@ -1419,6 +1419,12 @@ A collection of template filters that implement these common markup languages:
     * Markdown
     * ReST (ReStructured Text)
 
+See the `markup section`_ of the `add-ons documentation`_ for more
+information.
+
+.. _markup section: ../add_ons/#markup
+.. _add-ons documentation: ../add_ons/
+
 django.contrib.webdesign
 ------------------------
 

docs/testing.txt

@@ -137,12 +137,14 @@ When you `run your tests`_, the test runner will find this docstring, notice
 that portions of it look like an interactive Python session, and execute those
 lines while checking that the results match.
 
-In the case of model tests, note that the test runner takes care of creating
-its own test database. That is, any test that accesses a database -- by
-creating and saving model instances, for example -- will not affect your
-production database. Each doctest begins with a "blank slate" -- a fresh
-database containing an empty table for each model. (See the section on
-fixtures, below, for more on this.)
+In the case of model tests, note that the test runner takes care of
+creating its own test database. That is, any test that accesses a
+database -- by creating and saving model instances, for example --
+will not affect your production database. Each doctest begins with a
+"blank slate" -- a fresh database containing an empty table for each
+model. (See the section on fixtures, below, for more on this.) Note
+that to use this feature, the database user Django is connecting as
+must have ``CREATE DATABASE`` rights.
 
 For more details about how doctest works, see the `standard library
 documentation for doctest`_

docs/tutorial01.txt

@@ -46,7 +46,7 @@ will create a ``mysite`` directory in your current directory.
    If you're using Mac OS X, you may see the message "permission
    denied" when you try to run ``django-admin.py startproject``. This
    is because, on Unix-based systems like OS X, a file must be marked
-   as "exceutable" before it can be run as a program. To do this, open
+   as "executable" before it can be run as a program. To do this, open
    Terminal.app and navigate (using the `cd` command) to the directory
    where ``django-admin.py`` is installed, then run the command
    ``chmod +x django-admin.py``.