boulder-oracle-sprint: Merged to [5147]

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

6 files changed, 82 insertions, 11 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 aae9a1da04..90d31bfeaa 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.
+
 FIXTURE_DIRS
 -------------
 
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