[multi-db] Merge trunk to [3257]

git-svn-id: http://code.djangoproject.com/svn/django/branches/multiple-db-support@3258 bcc190cf-cafb-0310-a4f2-bffc1f526a37

6 files changed, 212 insertions, 84 deletions

diff --git a/docs/add_ons.txt b/docs/add_ons.txt
index d72e92b018..90c98b7176 100644
--- a/docs/add_ons.txt
+++ b/docs/add_ons.txt
@@ -128,6 +128,8 @@ A collection of template filters that implement these common markup languages:
     * Markdown
     * ReST (ReStructured Text)
 
+For documentation, read the source code in django/contrib/markup/templatetags/markup.py.
+
 redirects
 =========
 
diff --git a/docs/authentication.txt b/docs/authentication.txt
index 3edbc21f7a..68b9024a90 100644
--- a/docs/authentication.txt
+++ b/docs/authentication.txt
@@ -267,25 +267,54 @@ previous section). You can tell them apart with ``is_anonymous()``, like so::
 How to log a user in
 --------------------
 
-Depending on your task, you'll probably want to make sure to validate the 
-user's username and password before you log them in. The easiest way to do so 
-is to use the built-in ``authenticate`` and ``login`` functions from within a 
-view::
+Django provides two functions in ``django.contrib.auth``: ``authenticate()``
+and ``login()``.
 
-    from django.contrib.auth import authenticate, login
-    username = request.POST['username']
-    password = request.POST['password']
-    user = authenticate(username=username, password=password)
+To authenticate a given username and password, use ``authenticate()``. It
+takes two keyword arguments, ``username`` and ``password``, and it returns
+a ``User`` object if the password is valid for the given username. If the
+password is invalid, ``authenticate()`` returns ``None``. Example::
+
+    from django.contrib.auth import authenticate
+    user = authenticate(username='john', password='secret')
     if user is not None:
-        login(request, user)
+        print "You provided a correct username and password!"
+    else:
+        print "Your username and password were incorrect."
+
+To log a user in, in a view, use ``login()``. It takes an ``HttpRequest``
+object and a ``User`` object. ``login()`` saves the user's ID in the session,
+using Django's session framework, so, as mentioned above, you'll need to make
+sure to have the session middleware installed.
+
+This example shows how you might use both ``authenticate()`` and ``login()``::
+
+    from django.contrib.auth import authenticate, login
+
+    def my_view(request):
+        username = request.POST['username']
+        password = request.POST['password']
+        user = authenticate(username=username, password=password)
+        if user is not None:
+            login(request, user)
+            # Redirect to a success page.
+        else:
+            # Return an error message.
+
+How to log a user out
+---------------------
+
+To log out a user who has been logged in via ``django.contrib.auth.login()``,
+use ``django.contrib.auth.logout()`` within your view. It takes an
+``HttpRequest`` object and has no return value. Example::
+
+    from django.contrib.auth import logout
 
-``authenticate`` checks the username and password. If they are valid it 
-returns a user object, otherwise it returns ``None``. ``login`` makes it so 
-your users don't have send a username and password for every request. Because 
-the ``login`` function uses sessions, you'll need to make sure you have 
-``SessionMiddleware`` enabled. See the `session documentation`_ for 
-more information.
+    def logout_view(request):
+        logout(request)
+        # Redirect to a success page.
 
+Note that ``logout()`` doesn't throw any errors if the user wasn't logged in.
 
 Limiting access to logged-in users
 ----------------------------------
@@ -568,7 +597,7 @@ The currently logged-in user and his/her permissions are made available in the
    setting contains ``"django.core.context_processors.auth"``, which is default.
    For more, see the `RequestContext docs`_.
 
-   .. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext
+   .. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-requestcontext
 
 Users
 -----
@@ -681,61 +710,93 @@ database. To send messages to anonymous users, use the `session framework`_.
 
 .. _session framework: http://www.djangoproject.com/documentation/sessions/
 
-Other Authentication Sources
+Other authentication sources
 ============================
 
-Django supports other authentication sources as well. You can even use 
-multiple sources at the same time.
+The authentication that comes with Django is good enough for most common cases,
+but you may have the need to hook into another authentication source -- that
+is, another source of usernames and passwords or authentication methods.
 
-Using multiple backends
------------------------
+For example, your company may already have an LDAP setup that stores a username
+and password for every employee. It'd be a hassle for both the network
+administrator and the users themselves if users had separate accounts in LDAP
+and the Django-based applications.
 
-The list of backends to use is controlled by the ``AUTHENTICATION_BACKENDS`` 
-setting. This should be a tuple of python path names. It defaults to 
-``('django.contrib.auth.backends.ModelBackend',)``. To add additional backends
-just add them to your settings.py file. Ordering matters, so if the same
-username and password is valid in multiple backends, the first one in the
-list will return a user object, and the remaining ones won't even get a chance.
+So, to handle situations like this, the Django authentication system lets you
+plug in another authentication sources. You can override Django's default
+database-based scheme, or you can use the default system in tandem with other
+systems.
+
+Specifying authentication backends
+----------------------------------
+
+Behind the scenes, Django maintains a list of "authentication backends" that it
+checks for authentication. When somebody calls
+``django.contrib.auth.authenticate()`` -- as described in "How to log a user in"
+above -- Django tries authenticating across all of its authentication backends.
+If the first authentication method fails, Django tries the second one, and so
+on, until all backends have been attempted.
+
+The list of authentication backends to use is specified in the
+``AUTHENTICATION_BACKENDS`` setting. This should be a tuple of Python path
+names that point to Python classes that know how to authenticate. These classes
+can be anywhere on your Python path.
+
+By default, ``AUTHENTICATION_BACKENDS`` is set to::
+
+    ('django.contrib.auth.backends.ModelBackend',)
+
+That's the basic authentication scheme that checks the Django users database.
+
+The order of ``AUTHENTICATION_BACKENDS`` matters, so if the same username and
+password is valid in multiple backends, Django will stop processing at the
+first positive match.
 
 Writing an authentication backend
 ---------------------------------
 
-An authentication backend is a class that implements 2 methods: 
-``get_user(id)`` and ``authenticate(**credentials)``. The ``get_user`` method 
-takes an id, which could be a username, and database id, whatever, and returns 
-a user object. The  ``authenticate`` method takes credentials as keyword 
-arguments. Many times it will just look like this::
+An authentication backend is a class that implements two methods:
+``get_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  ``authenticate`` method takes credentials as keyword arguments. Most of
+the time, it'll just look like this::
 
     class MyBackend:
         def authenticate(username=None, password=None):
-            # check the username/password and return a user
+            # Check the username/password and return a User.
 
-but it could also authenticate a token like so::
+But it could also authenticate a token, like so::
 
     class MyBackend:
         def authenticate(token=None):
-            # check the token and return a user
+            # Check the token and return a User.
+
+Either way, ``authenticate`` should check the credentials it gets, and it
+should return a ``User`` object that matches those credentials, if the
+credentials are valid. If they're not valid, it should return ``None``.
 
-Regardless, ``authenticate`` should check the credentials it gets, and if they 
-are valid, it should return a user object that matches those credentials.
+The Django admin system is tightly coupled to the Django ``User`` object
+described at the beginning of this document. For now, the best way to deal with
+this is to create a Django ``User`` object for each user that exists for your
+backend (e.g., in your LDAP directory, your external SQL database, etc.) You
+can either write a script to do this in advance, or your ``authenticate``
+method can do it the first time a user logs in.
 
-The Django admin system is tightly coupled to the Django User object described 
-at the beginning of this document. For now, the best way to deal with this is 
-to create a Django User object for each user that exists for your backend 
-(i.e. in your LDAP directory, your external SQL database, etc.) You can either 
-write a script to do this in advance, or your ``authenticate`` method can do 
-it the first time a user logs in.  Here's an example backend that 
-authenticates against a username and password variable defined in your 
-``settings.py`` file and creates a Django user object the first time they 
-authenticate::
+Here's an example backend that authenticates against a username and password
+variable defined in your ``settings.py`` file and creates a Django ``User``
+object the first time a user authenticates::
 
     from django.conf import settings
     from django.contrib.auth.models import User, check_password
 
     class SettingsBackend:
         """
-        Authenticate against vars in settings.py Use the login name, and a hash 
-        of the password. For example:
+        Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD.
+
+        Use the login name, and a hash of the password. For example:
 
         ADMIN_LOGIN = 'admin'
         ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de'
@@ -747,8 +808,9 @@ authenticate::
                 try:
                     user = User.objects.get(username=username)
                 except User.DoesNotExist:
-                    # Create a new user. Note that we can set password to anything
-                    # as it won't be checked, the password from settings.py will.
+                    # Create a new user. Note that we can set password
+                    # to anything, because it won't be checked; the password
+                    # from settings.py will.
                     user = User(username=username, password='get from settings.py')
                     user.is_staff = True
                     user.is_superuser = True
diff --git a/docs/faq.txt b/docs/faq.txt
index 37e15878f2..b374abfbf3 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -411,6 +411,36 @@ Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:
        absolute URL to your image in a template with
        ``{{ object.get_mug_shot_url }}``.
 
+Databases and models
+====================
+
+How can I see the raw SQL queries Django is running?
+----------------------------------------------------
+
+Make sure your Django ``DEBUG`` setting is set to ``True``. Then, just do
+this::
+
+    >>> from django.db import connection
+    >>> connection.queries
+    [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls',
+    'time': '0.002'}]
+
+``connection.queries`` is only available if ``DEBUG`` is ``True``. It's a list
+of dictionaries in order of query execution. Each dictionary has the following::
+
+    ``sql`` -- The raw SQL statement
+    ``time`` -- How long the statement took to execute, in seconds.
+
+``connection.queries`` includes all SQL statements -- INSERTs, UPDATES,
+SELECTs, etc. Each time your app hits the database, the query will be recorded.
+
+Can I use Django with a pre-existing database?
+----------------------------------------------
+
+Yes. See `Integrating with a legacy database`_.
+
+.. _`Integrating with a legacy database`: http://www.djangoproject.com/documentation/legacy_databases/
+
 If I make changes to a model, how do I update the database?
 -----------------------------------------------------------
 
@@ -439,35 +469,24 @@ uniqueness at that level. Single-column primary keys are needed for things such
 as the admin interface to work; e.g., you need a simple way of being able to
 specify an object to edit or delete.
 
-The database API
-================
+How do I add database-specific options to my CREATE TABLE statements, such as specifying MyISAM as the table type?
+------------------------------------------------------------------------------------------------------------------
 
-How can I see the raw SQL queries Django is running?
-----------------------------------------------------
+We try to avoid adding special cases in the Django code to accomodate all the
+database-specific options such as table type, etc. If you'd like to use any of
+these options, create an `SQL initial data file`_ that contains ``ALTER TABLE``
+statements that do what you want to do. The initial data files are executed in
+your database after the ``CREATE TABLE`` statements.
 
-Make sure your Django ``DEBUG`` setting is set to ``True``. Then, just do
-this::
+For example, if you're using MySQL and want your tables to use the MyISAM table
+type, create an initial data file and put something like this in it::
 
-    >>> from django.db import connection
-    >>> connection.queries
-    [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls',
-    'time': '0.002'}]
+    ALTER TABLE myapp_mytable ENGINE=MyISAM;
 
-``connection.queries`` is only available if ``DEBUG`` is ``True``. It's a list
-of dictionaries in order of query execution. Each dictionary has the following::
+As explained in the `SQL initial data file`_ documentation, this SQL file can
+contain arbitrary SQL, so you can make any sorts of changes you need to make.
 
-    ``sql`` -- The raw SQL statement
-    ``time`` -- How long the statement took to execute, in seconds.
-
-``connection.queries`` includes all SQL statements -- INSERTs, UPDATES,
-SELECTs, etc. Each time your app hits the database, the query will be recorded.
-
-Can I use Django with a pre-existing database?
-----------------------------------------------
-
-Yes. See `Integrating with a legacy database`_.
-
-.. _`Integrating with a legacy database`: http://www.djangoproject.com/documentation/legacy_databases/
+.. _SQL initial data file: http://www.djangoproject.com/documentation/model_api/#providing-initial-sql-data
 
 Why is Django leaking memory?
 -----------------------------
diff --git a/docs/i18n.txt b/docs/i18n.txt
index 1220ea95b3..1382d6df0c 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -35,12 +35,25 @@ How to internationalize your app: in three steps
        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
+======================================
+
+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
+use internationalization, you should take the two seconds to set
+``USE_I18N = False`` in your settings file. If ``USE_I18N`` is set to
+``False``, then Django will make some optimizations so as not to load the
+internationalization machinery.
+
+See the `documentation for USE_I18N`_.
+
+.. _documentation for USE_I18N: http://www.djangoproject.com/documentation/settings/#use-i18n
+
 How to specify translation strings
 ==================================
 
diff --git a/docs/serialization.txt b/docs/serialization.txt
index 41954b7a0d..25199e7a50 100644
--- a/docs/serialization.txt
+++ b/docs/serialization.txt
@@ -78,8 +78,25 @@ The Django object itself can be inspected as ``deserialized_object.object``.
 Serialization formats
 ---------------------
 
-Django "ships" with a few included serializers, and there's a simple API for creating and registering your own...
+Django "ships" with a few included serializers:
 
-.. note::
+    ==========  ==============================================================
+    Identifier  Information
+    ==========  ==============================================================
+    ``xml``     Serializes to and from a simple XML dialect.
+
+    ``json``    Serializes to and from JSON_ (using a version of simplejson_
+                bundled with Django).
+
+    ``python``  Translates to and from "simple" Python objects (lists, dicts,
+                strings, etc.).  Not really all that useful on its own, but 
+                used as a base for other serializers.
+    ==========  ==============================================================
+
+.. _json: http://json.org/
+.. _simplejson: http://undefined.org/python/#simplejson
+
+Writing custom serializers
+``````````````````````````
 
-    ... which will be documented once the API is stable :)
+XXX ...
diff --git a/docs/settings.txt b/docs/settings.txt
index 553736b280..4f4fb70298 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -107,15 +107,20 @@ For more, see the `diffsettings documentation`_.
 Using settings in Python code
 =============================
 
-In your Django apps, use settings by importing them from
+In your Django apps, use settings by importing the object
 ``django.conf.settings``. Example::
 
-    from django.conf.settings import DEBUG
+    from django.conf import settings
 
-    if DEBUG:
+    if settings.DEBUG:
         # Do something
 
-Note that your code should *not* import from either ``global_settings`` or
+Note that ``django.conf.settings`` isn't a module -- it's an object. So
+importing individual settings is not possible::
+
+    from django.conf.settings import DEBUG  # This won't work.
+
+Also note that your code should *not* import from either ``global_settings`` or
 your own settings file. ``django.conf.settings`` abstracts the concepts of
 default settings and site-specific settings; it presents a single interface.
 It also decouples the code that uses settings from the location of your
@@ -127,9 +132,9 @@ Altering settings at runtime
 You shouldn't alter settings in your applications at runtime. For example,
 don't do this in a view::
 
-    from django.conf.settings import DEBUG
+    from django.conf import settings
 
-    DEBUG = True   # Don't do this!
+    settings.DEBUG = True   # Don't do this!
 
 The only place you should assign to settings is in a settings file.
 
@@ -738,6 +743,16 @@ A boolean that specifies whether to output the "Etag" header. This saves
 bandwidth but slows down performance. This is only used if ``CommonMiddleware``
 is installed (see the `middleware docs`_).
 
+USE_I18N
+--------
+
+Default: ``True``
+
+A boolean that specifies whether Django's internationalization system should be
+enabled. This provides an easy way to turn it off, for performance. If this is
+set to ``False, Django will make some optimizations so as not to load the
+internationalization machinery.
+
 YEAR_MONTH_FORMAT
 -----------------