unicode: Merged from trunk up to [5150].

git-svn-id: http://code.djangoproject.com/svn/django/branches/unicode@5151 bcc190cf-cafb-0310-a4f2-bffc1f526a37

7 files changed, 137 insertions, 55 deletions

diff --git a/docs/documentation.txt b/docs/documentation.txt
index e72dd47ba1..decb066fa1 100644
--- a/docs/documentation.txt
+++ b/docs/documentation.txt
@@ -94,12 +94,10 @@ Formatting
 
 The text documentation is written in ReST (ReStructured Text) format. That
 means it's easy to read but is also formatted in a way that makes it easy to
-convert into other formats, such as HTML. If you're interested, the script that
-converts the ReST text docs into djangoproject.com's HTML lives at
-`djangoproject.com/django_website/apps/docs/parts/build_documentation.py`_ in
-the Django Subversion repository.
+convert into other formats, such as HTML. If you have the `reStructuredText`_
+library installed, you can use ``rst2html`` to generate your own HTML files.
 
-.. _djangoproject.com/django_website/apps/docs/parts/build_documentation.py: http://code.djangoproject.com/browser/djangoproject.com/django_website/apps/docs/parts/build_documentation.py
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
 Differences between versions
 ============================
diff --git a/docs/email.txt b/docs/email.txt
index 8ebdaa8136..2793ee8ae3 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -22,7 +22,8 @@ In two lines::
 
 Mail will be sent using the SMTP host and port specified in the `EMAIL_HOST`_
 and `EMAIL_PORT`_ settings. The `EMAIL_HOST_USER`_ and `EMAIL_HOST_PASSWORD`_
-settings, if set, will be used to authenticate to the SMTP server.
+settings, if set, will be used to authenticate to the SMTP server and the
+`EMAIL_USE_TLS`_ settings will control whether a secure connection is used.
 
 .. note::
 
@@ -34,6 +35,7 @@ settings, if set, will be used to authenticate to the SMTP server.
 .. _EMAIL_PORT: ../settings/#email-port
 .. _EMAIL_HOST_USER: ../settings/#email-host-user
 .. _EMAIL_HOST_PASSWORD: ../settings/#email-host-password
+.. _EMAIL_USE_TLS: ../settings/#email-use-tls
 
 
 send_mail()
@@ -183,3 +185,65 @@ from the request's POST data, sends that to admin@example.com and redirects to
             return HttpResponse('Make sure all fields are entered and valid.')
 
 .. _Header injection: http://securephp.damonkohler.com/index.php/Email_Injection
+
+The EmailMessage and SMTPConnection classes
+===========================================
+
+**New in Django development version**
+
+Django's ``send_mail()`` and ``send_mass_mail()`` functions are actually thin
+wrappers that make use of the ``EmailMessage`` and ``SMTPConnection`` classes
+in ``django.mail``.  If you ever need to customize the way Django sends email,
+you can subclass these two classes to suit your needs.
+
+.. note::
+    Not all features of the ``EmailMessage`` class are available through the
+    ``send_mail()`` and related wrapper functions. If you wish to use advanced
+    features such as including BCC recipients or multi-part email, you will
+    need to create ``EmailMessage`` instances directly.
+
+In general, ``EmailMessage`` is responsible for creating the email message
+itself. ``SMTPConnection`` is responsible for the network connection side of
+the operation. This means you can reuse the same connection (an
+``SMTPConnection`` instance) for multiple messages.
+
+The ``EmailMessage`` class is initialised as follows::
+
+    email = EmailMessage(subject, body, from_email, to, bcc, connection)
+
+All of these parameters are optional. If ``from_email`` is omitted, the value
+from ``settings.DEFAULT_FROM_EMAIL`` is used. Both the ``to`` and ``bcc``
+parameters are lists of addresses.
+
+The class has the following methods that you can use:
+
+ * ``send()`` sends the message, using either the connection that is specified
+   in the ``connection`` attribute, or creating a new connection if none already
+   exists.
+ * ``message()`` constructs a ``django.core.mail.SafeMIMEText`` object (a
+   sub-class of Python's ``email.MIMEText.MIMEText`` class) holding the
+   message to be sent. If you ever need to extend the `EmailMessage` class,
+   you will probably want to override this method to put the content you wish
+   into the MIME object.
+ * ``recipients()`` returns a lists of all the recipients of the message,
+   whether they are recorded in the ``to`` or ``bcc`` attributes. This is
+   another method you need to possibly override when sub-classing, since the
+   SMTP server needs to be told the full list of recipients when the message
+   is sent. If you add another way to specify recipients in your class, they
+   need to be returned from this method as well.
+
+The ``SMTPConnection`` class is initialized with the host, port, username and
+password for the SMTP server. If you don't specify one or more of those
+options, they are read from your settings file.
+
+If you are sending lots of messages at once, the ``send_messages()`` method of
+the ``SMTPConnection`` class will be useful. It takes a list of ``EmailMessage``
+instances (or sub-classes) and sends them over a single connection. For
+example, if you have a function called ``get_notification_email()`` that returns a
+list of ``EmailMessage`` objects representing some periodic email you wish to
+send out, you could send this with::
+
+    connection = SMTPConnection()   # Use default settings for connection
+    messages = get_notification_email()
+    connection.send_messages(messages)
+
diff --git a/docs/sessions.txt b/docs/sessions.txt
index 55fbc2c3da..c7124ba703 100644
--- a/docs/sessions.txt
+++ b/docs/sessions.txt
@@ -107,7 +107,7 @@ posts a comment. It doesn't let a user post a comment more than once::
 This simplistic view logs in a "member" of the site::
 
     def login(request):
-        m = members.get_object(username__exact=request.POST['username'])
+        m = Member.objects.get(username=request.POST['username'])
         if m.password == request.POST['password']:
             request.session['member_id'] = m.id
             return HttpResponse("You're logged in.")
diff --git a/docs/settings.txt b/docs/settings.txt
index 39179248de..4a62a3ecf0 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -428,6 +428,15 @@ Subject-line prefix for e-mail messages sent with ``django.core.mail.mail_admins
 or ``django.core.mail.mail_managers``. You'll probably want to include the
 trailing space.
 
+EMAIL_USE_TLS
+-------------
+
+**New in Django development version**
+
+Default: ``False``
+
+Whether to use a TLS (secure) connection when talking to the SMTP server.
+
 FILE_CHARSET
 ------------
 
@@ -508,44 +517,17 @@ in standard language format. For example, U.S. English is ``"en-us"``. See the
 LANGUAGES
 ---------
 
-Default: A tuple of all available languages. Currently, this is::
+Default: A tuple of all available languages. This list is continually growing
+and including a copy here would inevitably become rapidly out of date. You can
+see the current list of translated languages by looking in
+``django/conf/global_settings.py`` (or view the `online source`_).
 
-    LANGUAGES = (
-        ('ar', _('Arabic')),
-        ('bn', _('Bengali')),
-        ('cs', _('Czech')),
-        ('cy', _('Welsh')),
-        ('da', _('Danish')),
-        ('de', _('German')),
-        ('el', _('Greek')),
-        ('en', _('English')),
-        ('es', _('Spanish')),
-        ('es_AR', _('Argentinean Spanish')),
-        ('fr', _('French')),
-        ('gl', _('Galician')),
-        ('hu', _('Hungarian')),
-        ('he', _('Hebrew')),
-        ('is', _('Icelandic')),
-        ('it', _('Italian')),
-        ('ja', _('Japanese')),
-        ('nl', _('Dutch')),
-        ('no', _('Norwegian')),
-        ('pt-br', _('Brazilian')),
-        ('ro', _('Romanian')),
-        ('ru', _('Russian')),
-        ('sk', _('Slovak')),
-        ('sl', _('Slovenian')),
-        ('sr', _('Serbian')),
-        ('sv', _('Swedish')),
-        ('ta', _('Tamil')),
-        ('uk', _('Ukrainian')),
-        ('zh-cn', _('Simplified Chinese')),
-        ('zh-tw', _('Traditional Chinese')),
-    )
+.. _online source: http://code.djangoproject.com/browser/django/trunk/django/conf/global_settings.py
 
-A tuple of two-tuples in the format (language code, language name). This
-specifies which languages are available for language selection. See the
-`internationalization docs`_ for details.
+The list is a tuple of two-tuples in the format (language code, language
+name) -- for example, ``('ja', 'Japanese')``. This specifies which languages
+are available for language selection. See the `internationalization docs`_ for
+details.
 
 Generally, the default value should suffice. Only set this setting if you want
 to restrict language selection to a subset of the Django-provided languages.
diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt
index c3b02b5d3f..d9d4f53b88 100644
--- a/docs/syndication_feeds.txt
+++ b/docs/syndication_feeds.txt
@@ -646,15 +646,15 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas
         def item_enclosure_mime_type(self, item):
             """
             Takes an item, as returned by items(), and returns the item's
-            enclosure mime type.
+            enclosure MIME type.
             """
 
         def item_enclosure_mime_type(self):
             """
-            Returns the enclosure length, in bytes, for every item in the feed.
+            Returns the enclosure MIME type for every item in the feed.
             """
 
-        item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure mime-type.
+        item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure MIME type.
 
         # ITEM PUBDATE -- It's optional to use one of these three. This is a
         # hook that specifies how to get the pubdate for a given item.
diff --git a/docs/templates_python.txt b/docs/templates_python.txt
index 7cc9acede8..1eeede1fe8 100644
--- a/docs/templates_python.txt
+++ b/docs/templates_python.txt
@@ -345,7 +345,7 @@ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
       ``request.user.get_and_delete_messages()`` for every request. That method
       collects the user's messages and deletes them from the database.
 
-      Note that messages are set with ``user.add_message()``. See the
+      Note that messages are set with ``user.message_set.create``. See the
       `message docs`_ for more.
 
     * ``perms`` -- An instance of
diff --git a/docs/testing.txt b/docs/testing.txt
index a135734144..5a2579b624 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -166,7 +166,7 @@ To assist in testing various features of your application, Django provides
 tools that can be used to establish tests and test conditions.
 
 * `Test Client`_
-* Fixtures_
+* `TestCase`_
 
 Test Client
 -----------
@@ -357,9 +357,31 @@ The following is a simple unit test using the Test Client::
             # Check that the rendered context contains 5 customers
             self.failUnlessEqual(len(response.context['customers']), 5)
 
-Fixtures
+TestCase
 --------
 
+Normal python unit tests extend a base class of ``unittest.testCase``. 
+Django provides an extension of this base class - ``django.test.TestCase`` 
+- that provides some additional capabilities that can be useful for 
+testing web sites. 
+
+Moving from a normal unittest TestCase to a Django TestCase is easy - just
+change the base class of your test from ``unittest.TestCase`` to 
+``django.test.TestCase``. All of the standard Python unit test facilities
+will continue to be available, but they will be augmented with some useful
+extra facilities.
+
+Default Test Client
+~~~~~~~~~~~~~~~~~~~
+** 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 
+``self.client``. This client is recreated for each test.
+
+Fixture loading
+~~~~~~~~~~~~~~~
+
 A test case for a database-backed website isn't much use if there isn't any
 data in the database. To make it easy to put test data into the database,
 Django provides a fixtures framework.
@@ -376,16 +398,14 @@ multiple applications.
     This provides a mechanism to populate a new database with any initial
     data (such as a default set of categories). Fixtures with other names
     can be installed manually using ``django-admin.py loaddata``. 
-    
 
 However, for the purposes of unit testing, each test must be able to 
 guarantee the contents of the database at the start of each and every
-test. To do this, Django provides a TestCase baseclass that can integrate
-with fixtures.
+test. 
 
-Moving from a normal unittest TestCase to a Django TestCase is easy - just
-change the base class of your test, and define a list of fixtures
-to be used. For example, the test case from `Writing unittests`_ would 
+To define a fixture for a test, all you need to do is add a class
+attribute to your test describing the fixtures you want the test to use.
+For example, the test case from `Writing unittests`_ would 
 look like::
 
     from django.test import TestCase
@@ -410,6 +430,24 @@ 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.
 
+Assertions
+~~~~~~~~~~
+** 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. 
+``django.TestCase`` adds to these, providing some assertions
+that can be useful in testing the behavior of web sites.
+
+``assertRedirects(response, expected_path)``
+    Assert that the response received redirects the browser to the provided
+    path, and that the expected_path can be retrieved.
+
+``assertContains(response, text, count=1)``
+    Assert that a response indicates that a page was retreived successfully,
+    (i.e., the HTTP status code was 200), and that ``text`` occurs ``count`` 
+    times in the content of the response.
+    
 Running tests
 =============