per-object-permissions: Merged to trunk [5486] NOTE: Not fully tested, will be working on this over the next few weeks.

git-svn-id: http://code.djangoproject.com/svn/django/branches/per-object-permissions@5488 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 90 insertions, 11 deletions

diff --git a/docs/email.txt b/docs/email.txt
index 37a4f38a5e..66948e5294 100644
--- a/docs/email.txt
+++ b/docs/email.txt
@@ -19,13 +19,23 @@ In two lines::
 
     send_mail('Subject here', 'Here is the message.', 'from@example.com',
         ['to@example.com'], fail_silently=False)
-        
+
+Mail is 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, are used to authenticate to the SMTP server, and the
+`EMAIL_USE_TLS`_ setting controls whether a secure connection is used.
+
 .. note::
 
-    The character set of email sent with ``django.core.mail`` will be set to
+    The character set of e-mail sent with ``django.core.mail`` will be set to
     the value of your `DEFAULT_CHARSET setting`_.
-    
-.. _DEFAULT_CHARSET setting: ../settings/#DEFAULT_CHARSET
+
+.. _DEFAULT_CHARSET setting: ../settings/#default-charset
+.. _EMAIL_HOST: ../settings/#email-host
+.. _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()
 ===========
@@ -34,8 +44,8 @@ The simplest way to send e-mail is using the function
 ``django.core.mail.send_mail()``. Here's its definition::
 
     send_mail(subject, message, from_email, recipient_list,
-        fail_silently=False, auth_user=EMAIL_HOST_USER,
-        auth_password=EMAIL_HOST_PASSWORD)
+        fail_silently=False, auth_user=None,
+        auth_password=None)
 
 The ``subject``, ``message``, ``from_email`` and ``recipient_list`` parameters
 are required.
@@ -65,7 +75,7 @@ send_mass_mail()
 Here's the definition::
 
     send_mass_mail(datatuple, fail_silently=False,
-        auth_user=EMAIL_HOST_USER, auth_password=EMAIL_HOST_PASSWORD):
+        auth_user=None, auth_password=None):
 
 ``datatuple`` is a tuple in which each element is in this format::
 
@@ -101,9 +111,9 @@ The "From:" header of the e-mail will be the value of the `SERVER_EMAIL setting`
 
 This method exists for convenience and readability.
 
-.. _ADMINS setting: http://www.djangoproject.com/documentation/settings/#admins
-.. _EMAIL_SUBJECT_PREFIX setting: http://www.djangoproject.com/documentation/settings/#email-subject-prefix
-.. _SERVER_EMAIL setting: http://www.djangoproject.com/documentation/settings/#server-email
+.. _ADMINS setting: ../settings/#admins
+.. _EMAIL_SUBJECT_PREFIX setting: ../settings/#email-subject-prefix
+.. _SERVER_EMAIL setting: ../settings/#server-email
 
 mail_managers() function
 ========================
@@ -114,7 +124,7 @@ Here's the definition::
 
     mail_managers(subject, message, fail_silently=False)
 
-.. _MANAGERS setting: http://www.djangoproject.com/documentation/settings/#managers
+.. _MANAGERS setting: ../settings/#managers
 
 Examples
 ========
@@ -174,3 +184,72 @@ 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.core.mail``.  If you ever need to customize the way Django sends
+e-mail, 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 BCC'ed recipients or multi-part e-mail, you'll need to
+    create ``EmailMessage`` instances directly.
+
+In general, ``EmailMessage`` is responsible for creating the e-mail 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 initialized 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, as strings.
+
+For example::
+
+    email = EmailMessage('Hello', 'Body goes here', 'from@example.com',
+                ['to1@example.com', 'to2@example.com'],
+                ['bcc@example.com'])
+
+The class has the following methods:
+
+    * ``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'll probably want to override this method to put the content you wish
+      into the MIME object.
+
+    * ``recipients()`` returns a list of all the recipients of the message,
+      whether they're recorded in the ``to`` or ``bcc`` attributes. This is
+      another method you might need to override when sub-classing, because 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're sending lots of messages at once, the ``send_messages()`` method of
+the ``SMTPConnection`` class is useful. It takes a list of ``EmailMessage``
+instances (or subclasses) 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 e-mail 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)