added doc for scrapy.mail

--HG--
extra : convert_revision : svn%3Ab85faa78-f9eb-468e-a121-7cced6da292c%40702

scrapy/trunk/docs/topics/email.rst

+.. _topics-email:
+
+=============
+Sending email
+=============
+
+.. module:: scrapy.mail
+   :synopsis: Helpers to easily send e-mail.
+
+Although Python makes sending e-mail relatively easy via the `smtplib library`_,
+Scrapy provides a couple of light wrappers over it, to make sending e-mail
+extra quick.
+
+The code lives in a single module: ``scrapy.mail``.
+
+.. _smtplib library: http://docs.python.org/library/smtplib.html
+
+Quick example
+=============
+
+Here's a quick example of how to send an email (without attachments)::
+
+    from scrapy.mail import MailSender
+
+    mailer = MailSender()
+    mailer.send(to=["someone@example.com"], "Some subject", "Some body", cc=["another@example.com"])
+
+MailSender class
+================
+
+MailSender is the class used to send emails from Scrapy. It's
+currently only a warpper over the (IO blocking) smtplib
+library but it's gonna be ported to Twisted soon.
+
+.. class:: scrapy.mail.MailSender(smtphost, mailfrom)
+
+    ``smtphost`` is a string with the SMTP host to use for sending the emails
+
+    ``mailfrom`` is a string with the email address to use for sending messages
+    (in the ``From:`` header)
+
+.. method:: send(to, subject, body, cc=None, attachs=None)
+
+    Send mail to the given recipients
+        
+    ``to`` is a list of email recipients
+
+    ``subject`` is a string with the subject of the message
+
+    ``cc`` is a list of emails to CC 
+
+    ``body`` is a string with the body of the message
+
+    ``attachs`` is a list of tuples containing (attach_name, mimetype, file_object) where:
+        ``attach_name`` is a string with the name will appear on the emails attachment
+        ``mimetype`` is the mimetype of the attachment
+        ``file_object`` is a readable file object
+

scrapy/trunk/docs/topics/index.rst

@@ -20,4 +20,5 @@ This section introduces all key concepts of Scrapy.
    extensions
    stats
    webconsole
+   email
    robotstxt

scrapy/trunk/scrapy/mail/__init__.py

+"""
+Mail sending helpers
+
+See documentation in docs/topics/email.rst
+"""
 import smtplib
 
 from email.MIMEMultipart import MIMEMultipart
@@ -20,14 +25,6 @@ class MailSender(object):
             raise NotConfigured("MAIL_HOST and MAIL_FROM settings are required")
 
     def send(self, to, subject, body, cc=None, attachs=None):
-        """
-        Send mail to the given recipients
-        
-        - to: must be a list of email recipients
-        - attachs must be a list of tuples: (attach_name, mimetype, file_object)
-        - body and subjet must be a string
-        """
-
         msg = MIMEMultipart()
         msg['From'] = self.mailfrom
         msg['To'] = COMMASPACE.join(to)