boulder-oracle-sprint: Merged to [5173]

git-svn-id: http://code.djangoproject.com/svn/django/branches/boulder-oracle-sprint@5174 bcc190cf-cafb-0310-a4f2-bffc1f526a37

7 files changed, 103 insertions, 43 deletions

diff --git a/docs/contributing.txt b/docs/contributing.txt
index 1d2b635b76..d05c166b37 100644
--- a/docs/contributing.txt
+++ b/docs/contributing.txt
@@ -396,10 +396,11 @@ To run the tests, ``cd`` to the ``tests/`` directory and type::
     ./runtests.py --settings=path.to.django.settings
 
 Yes, the unit tests need a settings module, but only for database connection
-info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``.
-You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just
-needs to be present) and a ``SITE_ID`` setting (any integer value will do) in
-order for all the tests to pass.
+info -- the ``DATABASE_NAME`` (required, but will be ignored),
+``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD`` settings. You
+will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just needs
+to be present) and a ``SITE_ID`` setting (any 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
diff --git a/docs/i18n.txt b/docs/i18n.txt
index 56e6f7e02c..1d7a0063b2 100644
--- a/docs/i18n.txt
+++ b/docs/i18n.txt
@@ -310,7 +310,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 and ``de_AT`` for Austrian German.
+``pt_BR`` for Brazilian Portugese and ``de_AT`` for Austrian German.
 
 The script should be run from one of three places:
 
@@ -463,8 +463,8 @@ 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 is
-      ``pt-br``.
+      standard language format, as a string. For example, Brazilian Portugese
+      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``
       (Austrian German) but Django only has ``de`` available, Django uses
diff --git a/docs/model-api.txt b/docs/model-api.txt
index a14c469661..961269aebd 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -459,7 +459,7 @@ string, not ``NULL``.
 ``blank``
 ~~~~~~~~~
 
-If ``True``, the field is allowed to be blank.
+If ``True``, the field is allowed to be blank. Default is ``False``.
 
 Note that this is different than ``null``. ``null`` is purely
 database-related, whereas ``blank`` is validation-related. If a field has
diff --git a/docs/serialization.txt b/docs/serialization.txt
index 8af4da26a8..3216cb061e 100644
--- a/docs/serialization.txt
+++ b/docs/serialization.txt
@@ -109,7 +109,7 @@ serializer, you must pass ``ensure_ascii=False`` as a parameter to the
 
 For example::
 
-    json_serializer = serializers.get_serializer("json")
+    json_serializer = serializers.get_serializer("json")()
     json_serializer.serialize(queryset, ensure_ascii=False, stream=response)
 
 Writing custom serializers
diff --git a/docs/sitemaps.txt b/docs/sitemaps.txt
index dafc009859..550f448de1 100644
--- a/docs/sitemaps.txt
+++ b/docs/sitemaps.txt
@@ -2,8 +2,6 @@
 The sitemap framework
 =====================
 
-**New in Django development version**.
-
 Django comes with a high-level sitemap-generating framework that makes
 creating sitemap_ XML files easy.
 
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 1eeede1fe8..853707f58c 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -212,21 +212,24 @@ template tags. If an invalid variable is provided to one of these template
 tags, the variable will be interpreted as ``None``. Filters are always
 applied to invalid variables within these template tags.
 
+If ``TEMPLATE_STRING_IF_INVALID`` contains a ``'%s'``, the format marker will
+be replaced with the name of the invalid variable.
+
 .. admonition:: For debug purposes only!
 
-    While ``TEMPLATE_STRING_IF_INVALID`` can be a useful debugging tool, 
-    it is a bad idea to turn it on as a 'development default'. 
+    While ``TEMPLATE_STRING_IF_INVALID`` can be a useful debugging tool,
+    it is a bad idea to turn it on as a 'development default'.
     
-    Many templates, including those in the Admin site, rely upon the 
-    silence of the template system when a non-existent variable is 
+    Many templates, including those in the Admin site, rely upon the
+    silence of the template system when a non-existent variable is
     encountered. If you assign a value other than ``''`` to
-    ``TEMPLATE_STRING_IF_INVALID``, you will experience rendering 
+    ``TEMPLATE_STRING_IF_INVALID``, you will experience rendering
     problems with these templates and sites.
     
-    Generally, ``TEMPLATE_STRING_IF_INVALID`` should only be enabled 
-    in order to debug a specific template problem, then cleared 
+    Generally, ``TEMPLATE_STRING_IF_INVALID`` should only be enabled
+    in order to debug a specific template problem, then cleared
     once debugging is complete.
-        
+
 Playing with Context objects
 ----------------------------
 
@@ -866,7 +869,7 @@ current context, available in the ``render`` method::
             try:
                 actual_date = resolve_variable(self.date_to_be_formatted, context)
                 return actual_date.strftime(self.format_string)
-            except VariableDoesNotExist:
+            except template.VariableDoesNotExist:
                 return ''
 
 ``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then
diff --git a/docs/testing.txt b/docs/testing.txt
index b3b33e9678..ba13dab67e 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -177,6 +177,7 @@ tools that can be used to establish tests and test conditions.
 
 * `Test Client`_
 * `TestCase`_
+* `Email services`_
 
 Test Client
 -----------
@@ -257,7 +258,7 @@ can be invoked on the ``Client`` instance.
     need to manually close the file after it has been provided to the POST.
 
 ``login(**credentials)``
-    ** New in Django development version **
+    **New in Django development version**
 
     On a production site, it is likely that some views will be protected from
     anonymous access through the use of the @login_required decorator, or some
@@ -289,9 +290,9 @@ can be invoked on the ``Client`` instance.
 Testing Responses
 ~~~~~~~~~~~~~~~~~
 
-The ``get()``, ``post()`` and ``login()`` methods all return a Response
-object. This Response object has the following properties that can be used
-for testing purposes:
+The ``get()`` and ``post()`` methods both return a Response object. This
+Response object has the following properties that can be used for testing
+purposes:
 
     ===============  ==========================================================
     Property         Description
@@ -396,7 +397,7 @@ extra facilities.
 
 Default Test Client
 ~~~~~~~~~~~~~~~~~~~
-** New in Django development version **
+**New in Django development version**
 
 Every test case in a ``django.test.TestCase`` instance has access to an
 instance of a Django `Test Client`_. This Client can be accessed as
@@ -453,9 +454,18 @@ This flush/load procedure is repeated for each test in the test case, so you
 can be certain that the outcome of a test will not be affected by
 another test, or the order of test execution.
 
+Emptying the test outbox
+~~~~~~~~~~~~~~~~~~~~~~~~
+**New in Django development version**
+
+At the start of each test case, in addition to installing fixtures,
+Django clears the contents of the test email outbox.
+
+For more detail on email services during tests, see `Email services`_.
+
 Assertions
 ~~~~~~~~~~
-** New in Django development version **
+**New in Django development version**
 
 Normal Python unit tests have a wide range of assertions, such as
 ``assertTrue`` and ``assertEquals`` that can be used to validate behavior.
@@ -468,30 +478,73 @@ that can be useful in testing the behavior of web sites.
     times in the content of the response.
 
 ``assertFormError(response, form, field, errors)``
-    Assert that a field on a form raised the provided list of errors when 
-    rendered on the form. 
-    
-    ``form`` is the name the form object was given in the template context. 
-    
-    ``field`` is the name of the field on the form to check. If ``field`` 
+    Assert that a field on a form raised the provided list of errors when
+    rendered on the form.
+
+    ``form`` is the name the form object was given in the template context.
+
+    ``field`` is the name of the field on the form to check. If ``field``
     has a value of ``None``, non-field errors will be checked.
-    
-    ``errors`` is an error string, or a list of error strings, that are 
-    expected as a result of form validation.    
-    
+
+    ``errors`` is an error string, or a list of error strings, that are
+    expected as a result of form validation.
+
 ``assertTemplateNotUsed(response, template_name)``
-    Assert that the template with the given name was *not* used in rendering 
+    Assert that the template with the given name was *not* used in rendering
     the response.
-    
+
 ``assertRedirects(response, expected_path)``
     Assert that the response received redirects the browser to the provided
-    path, and that the expected_path can be retrieved. 
+    path, and that the expected_path can be retrieved.
 
 ``assertTemplateUsed(response, template_name)``
     Assert that the template with the given name was used in rendering the
     response.
-    
-    
+
+Email services
+--------------
+**New in Django development version**
+
+If your view makes use of the `Django email services`_, you don't really
+want email to be sent every time you run a test using that view.
+
+When the Django test framework is initialized, it transparently replaces the
+normal `SMTPConnection`_ class with a dummy implementation that redirects all
+email to a dummy outbox. This outbox, stored as ``django.core.mail.outbox``,
+is a simple list of all `EmailMessage`_ instances that have been sent.
+For example, during test conditions, it would be possible to run the following
+code::
+
+    from django.core import mail
+
+    # Send message
+    mail.send_mail('Subject here', 'Here is the message.', 'from@example.com',
+        ['to@example.com'], fail_silently=False)
+
+    # One message has been sent
+    self.assertEqual(len(mail.outbox), 1)
+    # Subject of first message is correct
+    self.assertEqual(mail.outbox[0].subject, 'Subject here')
+
+The ``mail.outbox`` object does not exist under normal execution conditions.
+The outbox is created during test setup, along with the dummy `SMTPConnection`_.
+When the test framework is torn down, the standard `SMTPConnection`_ class
+is restored, and the test outbox is destroyed.
+
+As noted `previously`_, the test outbox is emptied at the start of every
+test in a Django TestCase. To empty the outbox manually, assign the empty list
+to mail.outbox::
+
+    from django.core import mail
+
+    # Empty the test outbox
+    mail.outbox = []
+
+.. _`Django email services`: ../email/
+.. _`SMTPConnection`: ../email/#the-emailmessage-and-smtpconnection-classes
+.. _`EmailMessage`: ../email/#the-emailmessage-and-smtpconnection-classes
+.. _`previously`: #emptying-the-test-outbox
+
 Running tests
 =============
 
@@ -516,6 +569,10 @@ database settings will the same as they would be for the project normally.
 If you wish to use a name other than the default for the test database,
 you can use the ``TEST_DATABASE_NAME`` setting to provide a name.
 
+The test database is created by the user in the ``DATABASE_USER`` setting.
+This user needs to have sufficient privileges to create a new database on the
+system.
+
 Once the test database has been established, Django will run your tests.
 If everything goes well, at the end you'll see::
 
@@ -606,11 +663,12 @@ a number of utility methods in the ``django.test.utils`` module.
 
 ``setup_test_environment()``
     Performs any global pre-test setup, such as the installing the
-    instrumentation of the template rendering system.
+    instrumentation of the template rendering system and setting up
+    the dummy SMTPConnection.
 
 ``teardown_test_environment()``
     Performs any global post-test teardown, such as removing the instrumentation
-    of the template rendering system.
+    of the template rendering system and restoring normal email services.
 
 ``create_test_db(verbosity=1, autoclobber=False)``
     Creates a new test database, and run ``syncdb`` against it.