[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [bridgedb/master] Refactor and update bridgedb.email package Sphinx documentation.



commit 1be3efddc0a35e38a67712e65395179252e89aef
Author: Isis Lovecruft <isis@xxxxxxxxxxxxxx>
Date:   Thu Aug 28 10:55:30 2014 +0000

    Refactor and update bridgedb.email package Sphinx documentation.
---
 lib/bridgedb/email/autoresponder.py |  109 +++++++++++++++++------------------
 lib/bridgedb/email/dkim.py          |   20 ++++---
 lib/bridgedb/email/request.py       |    7 ++-
 lib/bridgedb/email/server.py        |   84 ++++++++++++++-------------
 lib/bridgedb/email/templates.py     |   14 ++++-
 5 files changed, 126 insertions(+), 108 deletions(-)

diff --git a/lib/bridgedb/email/autoresponder.py b/lib/bridgedb/email/autoresponder.py
index aea8cae..44f4079 100644
--- a/lib/bridgedb/email/autoresponder.py
+++ b/lib/bridgedb/email/autoresponder.py
@@ -12,14 +12,15 @@
 # :license: see LICENSE for licensing information
 #_____________________________________________________________________________
 
-"""Functionality for autoresponding to incoming emails.
-
+"""
 .. py:module:: bridgedb.email.autoresponder
     :synopsis: Functionality for autoresponding to incoming emails.
 
 bridgedb.email.autoresponder
 ============================
 
+Functionality for autoresponding to incoming emails.
+
 ::
 
   bridgedb.email.autoresponder
@@ -66,15 +67,16 @@ def createResponseBody(lines, context, client, lang='en'):
 
     :param list lines: The list of lines from the original request sent by the
         client.
-    :type context: class:`MailServerContext`
+    :type context: class:`bridgedb.email.server.MailServerContext`
     :param context: The context which contains settings for the email server.
     :type client: :api:`twisted.mail.smtp.Address`
     :param client: The client's email address which should be in the
-        :header:`To:` header of the response email.
+        ``'To:'`` header of the response email.
     :param str lang: The 2-5 character locale code to use for translating the
         email. This is obtained from a client sending a email to a valid plus
         address which includes the translation desired, i.e. by sending an
-        email to ``bridges+fa@xxxxxxxxxxxxxx``, the client should receive a
+        email to `bridges+fa@xxxxxxxxxxxxxx
+        <mailto:bridges+fa@xxxxxxxxxxxxxx>`__, the client should receive a
         response in Farsi.
     :rtype: None or str
     :returns: None if we shouldn't respond to the client (i.e., if they have
@@ -136,21 +138,20 @@ def generateResponse(fromAddress, client, body, subject=None,
         the :header:`From:` header.
     :type client: :api:`twisted.mail.smtp.Address`
     :param client: The client's email address which should be in the
-        :header:`To:` header of the response email.
-    :param str subject: The string to write to the :header:`subject` header.
+        ``'To:'`` header of the response email.
+    :param str subject: The string to write to the ``Subject:'`` header.
     :param str body: The body of the email. If a **gpgContext** is also given,
         and that ``Context`` has email signing configured, then
         :meth:`EmailResponse.writeBody` will generate and include any
         ascii-armored OpenPGP signatures in the **body**.
     :type messageID: None or str
-    :param messageID: The :rfc:`2822` specifier for the :header:`Message-ID:`
+    :param messageID: The :rfc:`2822` specifier for the ``'Message-ID:'``
         header, if including one is desirable.
-    :type gpgContext: None or ``gpgme.Context``.
+    :type gpgContext: None or ``gpgme.Context``
     :param gpgContext: A pre-configured GPGME context. See
-        :func:`~crypto.getGPGContext`.
-    :rtype: :class:`EmailResponse`
-    :returns: A ``EmailResponse`` which contains the entire email. To obtain
-        the contents of the email, including all headers, simply use
+        :func:`~bridgedb.crypto.getGPGContext`.
+    :returns: An :class:`EmailResponse` which contains the entire email. To
+        obtain the contents of the email, including all headers, simply use
         :meth:`EmailResponse.readContents`.
     """
     response = EmailResponse(gpgContext)
@@ -180,20 +181,18 @@ class EmailResponse(object):
         keyfile, for example, rather than simply pasting it into the body of
         the email.)
 
-    :type _buff: unicode or buffer
-    :cvar _buff: Used internally to write lines for the response email into
-        the ``_mailfile``. The reason why both of these attributes have two
-        possible types is for the same Python-buggy reasons which require
-        :data:`~bridgedb.crypto.NEW_BUFFER_INTERFACE`.
-    :type mailfile: :class:`io.StringIO` or :class:`io.BytesIO`.
-    :cvar mailfile: An in-memory file for storing the formatted headers and
-        body of the response email.
-
-    :ivar str delimiter: Delimiter between lines written to the
-        :cvar:`mailfile`.
-    :ivar bool closed: ``True`` if :meth:`close` has been called.
-    :type to: :api:`twisted.mail.smtp.Address`
-    :ivar to: The client's email address which this response should be sent to.
+    :cvar _buff: (unicode or buffer) Used internally to write lines for the
+        response email into the ``_mailfile``. The reason why both of these
+        attributes have two possible types is for the same Python-buggy
+        reasons which require :data:`~bridgedb.crypto.NEW_BUFFER_INTERFACE`.
+    :cvar mailfile: (:class:`io.StringIO` or :class:`io.BytesIO`) An in-memory
+        file for storing the formatted headers and body of the response email.
+
+    :var str delimiter: Delimiter between lines written to the
+        :data:`mailfile`.
+    :var bool closed: ``True`` if :meth:`close` has been called.
+    :var to: An :api:`twisted.mail.smtp.Address` for the client's email address
+        which this response should be sent to.
     """
     _buff = buffer if NEW_BUFFER_INTERFACE else unicode
     mailfile = io.BytesIO if NEW_BUFFER_INTERFACE else io.StringIO
@@ -202,7 +201,7 @@ class EmailResponse(object):
         """Create a response to an email we have recieved.
 
         This class deals with correctly formatting text for the response email
-        headers and the response body into an instance of :cvar:`mailfile`.
+        headers and the response body into an instance of :data:`mailfile`.
 
         :type gpgContext: None or ``gpgme.Context``
         :param gpgContext: A pre-configured GPGME context. See
@@ -219,20 +218,20 @@ class EmailResponse(object):
         self.to = None
 
     def close(self):
-        """Close our :ivar:`mailfile` and set :ivar:`closed` to ``True``."""
+        """Close our :data:`mailfile` and set :data:`closed` to ``True``."""
         logging.debug("Closing %s.mailfile..." % (self.__class__.__name__))
         self.mailfile.close()
         self.closed = True
 
     def read(self, size=None):
-        """Read, at most, **size** bytes from our :ivar:`mailfile`.
+        """Read, at most, **size** bytes from our :data:`mailfile`.
 
         .. note:: This method is required by Twisted's SMTP system.
 
         :param int size: The number of bytes to read. Defaults to ``None``,
             which reads until EOF.
         :rtype: str
-        :returns: The bytes read from the :ivar:`mailfile`.
+        :returns: The bytes read from the :data:`mailfile`.
         """
         contents = ''
         logging.debug("Reading%s from %s.mailfile..."
@@ -249,12 +248,12 @@ class EmailResponse(object):
         return contents
 
     def readContents(self):
-        """Read the all the contents written thus far to the :cvar:`mailfile`,
+        """Read the all the contents written thus far to the :data:`mailfile`,
         and then :meth:`seek` to return to the original pointer position we
         were at before this method was called.
 
         :rtype: str
-        :returns: The entire contents of the :cvar:`mailfile`.
+        :returns: The entire contents of the :data:`mailfile`.
         """
         pointer = self.mailfile.tell()
         self.mailfile.seek(0)
@@ -263,17 +262,17 @@ class EmailResponse(object):
         return contents
 
     def rewind(self):
-        """Rewind to the very beginning of the :cvar:`mailfile`."""
+        """Rewind to the very beginning of the :data:`mailfile`."""
         logging.debug("Rewinding %s.mailfile..." % self.__class__.__name__)
         self.mailfile.seek(0)
 
     def write(self, line):
-        """Write the **line** to the :ivar:`mailfile`.
+        """Write the **line** to the :data:`mailfile`.
 
-        Any **line** written to me will have :ivar:`delimiter` appended to it
+        Any **line** written to me will have :data:`delimiter` appended to it
         beforehand.
 
-        :param str line: Something to append into the :ivar:`mailfile`.
+        :param str line: Something to append into the :data:`mailfile`.
         """
         if line.find('\r\n') != -1:
             # If **line** contains newlines, send it to :meth:`writelines` to
@@ -288,8 +287,8 @@ class EmailResponse(object):
     def writelines(self, lines):
         """Calls :meth:`write` for each line in **lines**.
 
-        Line endings of ``'\r\n'`` will be replaced with :ivar:`delimiter`
-        (i.e. ``'\n'``). See :api:`twisted.mail.smtp.SMTPClient.getMailData`
+        Line endings of ``'\\r\\n'`` will be replaced with :data:`delimiter`
+        (i.e. ``'\\n'``). See :api:`twisted.mail.smtp.SMTPClient.getMailData`
         for the reason.
 
         :type lines: basestring or list
@@ -308,17 +307,17 @@ class EmailResponse(object):
                      contentType='text/plain; charset="utf-8"', **kwargs):
         """Write all headers into the response email.
 
-        :param str fromAddress: The email address for the ``From:`` header.
-        :param str toAddress: The email address for the ``To:`` header.
+        :param str fromAddress: The email address for the ``'From:'`` header.
+        :param str toAddress: The email address for the ``'To:'`` header.
         :type subject: None or str
-        :param subject: The ``Subject:`` header.
+        :param subject: The ``'Subject:'`` header.
         :type inReplyTo: None or str
-        :param inReplyTo: If set, an ``In-Reply-To:`` header will be
-            generated. This should be set to the ``Message-ID:`` header from
+        :param inReplyTo: If set, an ``'In-Reply-To:'`` header will be
+            generated. This should be set to the ``'Message-ID:'`` header from
             the client's original request email.
         :param bool includeMessageID: If ``True``, generate and include a
-            ``Message-ID:`` header for the response.
-        :param str contentType: The ``Content-Type:`` header.
+            ``'Message-ID:'`` header for the response.
+        :param str contentType: The ``'Content-Type:'`` header.
         :kwargs: If given, the key will become the name of the header, and the
             value will become the Contents of that header.
         """
@@ -398,7 +397,7 @@ class SMTPAutoresponder(smtp.SMTPClient):
         """Gather all the data for building the response to the client.
 
         This method must return a file-like object containing the data of the
-        message to be sent. Lines in the file should be delimited by '\n'.
+        message to be sent. Lines in the file should be delimited by ``\\n``.
 
         :rtype: ``None`` or :class:`EmailResponse`
         :returns: An ``EmailResponse``, if we have a response to send in reply
@@ -438,7 +437,7 @@ class SMTPAutoresponder(smtp.SMTPClient):
 
         :rtype: list
         :returns: A list containing the client's
-            :func:`normalized <addr.normalizeEmail>` email
+            :func:`normalized <bridgedb.parse.addr.normalizeEmail>` email
             :api:`Address <twisted.mail.smtp.Address>`, if it originated from
             a domain that we accept and the address was well-formed. Otherwise,
             returns ``None``. Even though we're likely to respond to only one
@@ -604,19 +603,19 @@ class SMTPAutoresponder(smtp.SMTPClient):
     def runChecks(self, client):
         """Run checks on the incoming message, and only reply if they pass.
 
-          1. Check if the client's address is whitelisted.
+        1. Check if the client's address is whitelisted.
 
-          2. If it's not whitelisted, check that the domain names, taken from
+        2. If it's not whitelisted, check that the domain names, taken from
         the SMTP ``MAIL FROM:`` command and the email ``'From:'`` header, can
         be :func:`canonicalized <addr.canonicalizeEmailDomain>`.
 
-          3. Check that those canonical domains match.
+        3. Check that those canonical domains match.
 
-          4. If the incoming message is from a domain which supports DKIM
+        4. If the incoming message is from a domain which supports DKIM
         signing, then run :func:`bridgedb.email.dkim.checkDKIM` as well.
 
         .. note:: Calling this method sets the ``canonicalFromEmail`` and
-            :ivar:``canonicalDomainRules`` attributes of the :ivar:`incoming`
+            :data:``canonicalDomainRules`` attributes of the :data:`incoming`
             message.
 
         :param client: An :api:`twisted.mail.smtp.Address`, which contains
@@ -687,7 +686,7 @@ class SMTPAutoresponder(smtp.SMTPClient):
         return True
 
     def send(self, response, retries=0, timeout=30, reaktor=reactor):
-        """Send our **response** in reply to :ivar:`incoming`.
+        """Send our **response** in reply to :data:`incoming`.
 
         :type client: :api:`twisted.mail.smtp.Address`
         :param client: The email address of the client.
@@ -695,7 +694,7 @@ class SMTPAutoresponder(smtp.SMTPClient):
         :param int retries: Try resending this many times. (default: ``0``)
         :param int timeout: Timeout after this many seconds. (default: ``30``)
         :rtype: :api:`Deferred <twisted.internet.defer.Deferred>`
-        :returns: Our :ivar:`deferred`.
+        :returns: Our :data:`deferred`.
         """
         logging.info("Sending reply to %s ..." % str(response.to))
 
diff --git a/lib/bridgedb/email/dkim.py b/lib/bridgedb/email/dkim.py
index 9abcf3f..d797dbc 100644
--- a/lib/bridgedb/email/dkim.py
+++ b/lib/bridgedb/email/dkim.py
@@ -12,8 +12,7 @@
 # :license: see LICENSE for licensing information
 #_____________________________________________________________________________
 
-"""Functions for checking DKIM verification results in email headers.
-
+"""
 .. py:module:: bridgedb.email.dkim
     :synopsis: Functions for checking DKIM verification results in email
                headers.
@@ -21,6 +20,8 @@
 bridgedb.email.dkim
 ===================
 
+Functions for checking DKIM verification results in email headers.
+
 ::
 
  bridgedb.email.dkim
@@ -40,17 +41,20 @@ def checkDKIM(message, rules):
     a domain for which we're configured (in the ``EMAIL_DOMAIN_RULES``
     dictionary in the config file) to check DKIM verification results for.
 
+    Returns ``False`` if:
+
+    1. We're supposed to expect and check the DKIM headers for the
+       client's email provider domain.
+    2. Those headers were *not* okay.
+
+    Otherwise, returns ``True``.
+
     :type message: :api:`twisted.mail.smtp.rfc822.Message`
     :param message: The incoming client request email, including headers.
     :param dict rules: The list of configured ``EMAIL_DOMAIN_RULES`` for the
         canonical domain which the client's email request originated from.
-
     :rtype: bool
-    :returns: ``False`` if:
-        1. We're supposed to expect and check the DKIM headers for the
-           client's email provider domain.
-        2. Those headers were *not* okay.
-        Otherwise, returns ``True``.
+    :returns: ``False`` if the checks failed, ``True`` otherwise.
     """
     logging.info("Checking DKIM verification results...")
     logging.debug("Domain has rules: %s" % ', '.join(rules))
diff --git a/lib/bridgedb/email/request.py b/lib/bridgedb/email/request.py
index 7a6e7cc..cd7b47d 100644
--- a/lib/bridgedb/email/request.py
+++ b/lib/bridgedb/email/request.py
@@ -12,9 +12,7 @@
 # :license: see LICENSE for licensing information
 #_____________________________________________________________________________
 
-"""Classes for parsing and storing information about requests for bridges
-which are sent to the email distributor.
-
+"""
 .. py:module:: bridgedb.email.request
     :synopsis: Classes for parsing and storing information about requests for
                bridges which are sent to the email distributor.
@@ -22,6 +20,9 @@ which are sent to the email distributor.
 bridgedb.email.request
 ======================
 
+Classes for parsing and storing information about requests for bridges
+which are sent to the email distributor.
+
 ::
 
   bridgedb.email.request
diff --git a/lib/bridgedb/email/server.py b/lib/bridgedb/email/server.py
index 625849d..110c381 100644
--- a/lib/bridgedb/email/server.py
+++ b/lib/bridgedb/email/server.py
@@ -13,8 +13,7 @@
 #_____________________________________________________________________________
 
 
-"""Servers which interface with clients and distribute bridges over SMTP.
-
+"""
 .. py:module:: bridgedb.email.server
     :synopsis: Servers which interface with clients and distribute bridges
                over SMTP.
@@ -22,6 +21,8 @@
 bridgedb.email.server
 =====================
 
+Servers which interface with clients and distribute bridges over SMTP.
+
 ::
 
   bridgedb.email.server
@@ -81,7 +82,7 @@ class MailServerContext(object):
     :ivar str smtpServer: The IP address to use for outgoing SMTP.
     :ivar str smtpFromAddr: Use this address in the raw SMTP ``MAIL FROM``
         line for outgoing mail. (default: ``bridges@xxxxxxxxxxxxxx``)
-    :ivar str fromAddr: Use this address in the email :header:`From:`
+    :ivar str fromAddr: Use this address in the email ``From:``
         line for outgoing mail. (default: ``bridges@xxxxxxxxxxxxxx``)
     :ivar int nBridges: The number of bridges to send for each email.
     :ivar list blacklist: A list of blacklisted email addresses, taken from
@@ -98,12 +99,12 @@ class MailServerContext(object):
         """Create a context for storing configs for email bridge distribution.
 
         :type config: :class:`bridgedb.persistent.Conf`
-        :type distributor: :class:`bridgedb.Dist.EmailBasedDistributor`.
+        :type distributor: :class:`bridgedb.Dist.EmailBasedDistributor`
         :param distributor: The distributor will handle getting the correct
             bridges (or none) for a client for us.
-        :type schedule: :class:`bridgedb.schedule.ScheduledInterval`.
+        :type schedule: :class:`bridgedb.schedule.ScheduledInterval`
         :param schedule: An interval-based scheduler, used to help the
-            :ivar:`distributor` know if we should give bridges to a client.
+            :data:`distributor` know if we should give bridges to a client.
         """
         self.config = config
         self.distributor = distributor
@@ -156,20 +157,23 @@ class MailServerContext(object):
 class SMTPMessage(object):
     """Plugs into the Twisted Mail and receives an incoming message.
 
-    :ivar list lines: A list of lines from an incoming email message.
-    :ivar int nBytes: The number of bytes received thus far.
-    :ivar bool ignoring: If ``True``, we're ignoring the rest of this message
-        because it exceeded :ivar:`MailServerContext.maximumSize`.
-    :ivar canonicalFromSMTP: See :meth:`SMTPAutoresponder.runChecks`.
-    :ivar canonicalFromEmail: See :meth:`SMTPAutoresponder.runChecks`.
-    :ivar canonicalDomainRules: See :meth:`SMTPAutoresponder.runChecks`.
-    :type message: :api:`twisted.mail.smtp.rfc822.Message` or ``None``
-    :ivar message: The incoming email message.
-    :type responder: :class:`autoresponder.SMTPAutoresponder`
-    :ivar responder: A parser and checker for the incoming :ivar:`message`. If
-        it decides to do so, it will build a
-        :meth:`~autoresponder.SMTPAutoresponder.reply` email and
-        :meth:`~autoresponder.SMTPAutoresponder.send` it.
+    :var list lines: A list of lines from an incoming email message.
+    :var int nBytes: The number of bytes received thus far.
+    :var bool ignoring: If ``True``, we're ignoring the rest of this message
+        because it exceeded :data:`MailServerContext.maximumSize`.
+    :var canonicalFromSMTP: See
+        :meth:`~bridgedb.email.autoresponder.SMTPAutoresponder.runChecks`.
+    :var canonicalFromEmail: See
+        :meth:`~bridgedb.email.autoresponder.SMTPAutoresponder.runChecks`.
+    :var canonicalDomainRules: See
+        :meth:`~bridgedb.email.autoresponder.SMTPAutoresponder.runChecks`.
+    :var message: (:api:`twisted.mail.smtp.rfc822.Message` or ``None``) The
+        incoming email message.
+    :var responder: A :class:`~bridgedb.email.autoresponder.SMTPAutoresponder`
+        which parses and checks the incoming :data:`message`. If it decides to
+        do so, it will build a
+        :meth:`~bridgedb.email.autoresponder.SMTPAutoresponder.reply` email
+        and :meth:`~bridgedb.email.autoresponder.SMTPAutoresponder.send` it.
     """
     implements(smtp.IMessage)
 
@@ -219,7 +223,7 @@ class SMTPMessage(object):
                 logging.exception(error)
 
     def eomReceived(self):
-        """Tell the :ivar:`responder` to reply when we receive an EOM."""
+        """Tell the :data:`responder` to reply when we receive an EOM."""
         if not self.ignoring:
             self.message = self.getIncomingMessage()
             self.responder.reply()
@@ -230,7 +234,7 @@ class SMTPMessage(object):
         pass
 
     def getIncomingMessage(self):
-        """Create and parse an :rfc:`2822` message object for all :ivar:`lines`
+        """Create and parse an :rfc:`2822` message object for all :data:`lines`
         received thus far.
 
         :rtype: :api:`twisted.mail.smtp.rfc822.Message`
@@ -248,13 +252,13 @@ class SMTPIncomingDelivery(smtp.SMTP):
     for incoming connections.
 
     :type context: :class:`MailServerContext`
-    :ivar context: A context containing SMTP/Email configuration settings.
-    :ivar deferred: A :api:`deferred <twisted.internet.defer.Deferred>` which
+    :var context: A context containing SMTP/Email configuration settings.
+    :var deferred: A :api:`deferred <twisted.internet.defer.Deferred>` which
         will be returned when :meth:`reply` is called. Additional callbacks
         may be set on this deferred in order to schedule additional actions
         when the response is being sent.
     :type fromCanonicalSMTP: str or ``None``
-    :ivar fromCanonicalSMTP: If set, this is the canonicalized domain name of
+    :var fromCanonicalSMTP: If set, this is the canonicalized domain name of
        the address we received from incoming connection's ``MAIL FROM:``.
     """
     implements(smtp.IMessageDelivery)
@@ -265,7 +269,7 @@ class SMTPIncomingDelivery(smtp.SMTP):
 
     @classmethod
     def setContext(cls, context):
-        """Set our :ivar:`context` to a new :class:`MailServerContext."""
+        """Set our :data:`context` to a new :class:`MailServerContext`."""
         cls.context = context
 
     def receivedHeader(self, helo, origin, recipients):
@@ -289,15 +293,15 @@ class SMTPIncomingDelivery(smtp.SMTP):
 
         This is done at the SMTP layer. Meaning that if a Postfix or other
         email server is proxying emails from the outside world to BridgeDB,
-        the :api:`origin.domain <twisted.email.smtp.Address.domain` will be
+        the :api:`origin.domain <twisted.email.smtp.Address.domain>` will be
         set to the local hostname. Therefore, if the SMTP ``MAIL FROM:``
         domain name is our own hostname (as returned from
         :func:`socket.gethostname`) or our own FQDN, allow the connection.
 
         Otherwise, if the ``MAIL FROM:`` domain has a canonical domain in our
-        mapping (taken from :ivar:`context.canon <MailServerContext.canon>`, which
-        is taken in turn from the ``EMAIL_DOMAIN_MAP``), then our
-        :ivar:`fromCanonicalSMTP` is set to that domain.
+        mapping (taken from our :data:`context.canon`, which is taken in turn
+        from the ``EMAIL_DOMAIN_MAP``), then our :data:`fromCanonicalSMTP` is
+        set to that domain.
 
         :type helo: tuple
         :param helo: The lines received during SMTP client HELO.
@@ -381,7 +385,7 @@ class SMTPIncomingDelivery(smtp.SMTP):
 
 
 class SMTPIncomingDeliveryFactory(object):
-    """Factory for :class:`SMTPIncomingDelivery`s.
+    """Factory for :class:`SMTPIncomingDelivery` s.
 
     This class is used to distinguish between different messages delivered
     over the same connection. This can be used to optimize delivery of a
@@ -389,8 +393,8 @@ class SMTPIncomingDeliveryFactory(object):
     :api:`IMessageDelivery <twisted.mail.smtp.IMessageDelivery>` implementors
     due to their lack of information.
 
-    :ivar context: A :class:`MailServerContext` for storing configuration settings.
-    :ivar delivery: A :class:`SMTPIncomingDelivery` to deliver incoming
+    :var context: A :class:`MailServerContext` for storing configuration settings.
+    :var delivery: A :class:`SMTPIncomingDelivery` to deliver incoming
         SMTP messages to.
     """
     implements(smtp.IMessageDeliveryFactory)
@@ -403,7 +407,7 @@ class SMTPIncomingDeliveryFactory(object):
 
     @classmethod
     def setContext(cls, context):
-        """Set our :ivar:`context` and the context for our :ivar:`delivery`."""
+        """Set our :data:`context` and the context for our :data:`delivery`."""
         cls.context = context
         cls.delivery.setContext(cls.context)
 
@@ -414,11 +418,11 @@ class SMTPIncomingDeliveryFactory(object):
 
 class SMTPIncomingServerFactory(smtp.SMTPFactory):
     """Plugs into :api:`twisted.mail.smtp.SMTPFactory`; creates a new
-    :class:`SMTPMessageDelivery`, which handles response email automation,
-    whenever we get a incoming connection on the SMTP port.
+    :class:`SMTPIncomingDeliveryFactory`, which handles response email
+    automation whenever we get a incoming connection on the SMTP port.
 
-    .. warning:: My :ivar:`context` isn't an OpenSSL context, as is used for
-        the :api:`twisted.mail.smtp.ESMTPSender`
+    .. warning:: My :data:`context` isn't an OpenSSL context, as is used for
+        the :api:`twisted.mail.smtp.ESMTPSender`.
 
     :ivar context: A :class:`MailServerContext` for storing configuration settings.
     :ivar deliveryFactory: A :class:`SMTPIncomingDeliveryFactory` for
@@ -440,7 +444,7 @@ class SMTPIncomingServerFactory(smtp.SMTPFactory):
 
     @classmethod
     def setContext(cls, context):
-        """Set :ivar:`context` and :ivar:`deliveryFactory`.context."""
+        """Set :data:`context` and :data:`deliveryFactory`.context."""
         cls.context = context
         cls.deliveryFactory.setContext(cls.context)
 
@@ -456,7 +460,7 @@ def addServer(config, distributor, schedule):
     """Set up a SMTP server which listens on the configured ``EMAIL_PORT`` for
     incoming connections, and responds as necessary to requests for bridges.
 
-    :type config: :class:`bridgedb.persistent.Conf`
+    :type config: :class:`bridgedb.configure.Conf`
     :param config: A configuration object.
     :type distributor: :class:`bridgedb.Dist.EmailBasedDistributor`
     :param dist: A distributor which will handle database interactions, and
diff --git a/lib/bridgedb/email/templates.py b/lib/bridgedb/email/templates.py
index e4d5389..dda9f65 100644
--- a/lib/bridgedb/email/templates.py
+++ b/lib/bridgedb/email/templates.py
@@ -10,14 +10,15 @@
 # :license: see LICENSE for licensing information
 #_____________________________________________________________________________
 
-"""Templates for formatting emails sent out by the email distributor.
-
+"""
 .. py:module:: bridgedb.email.templates
     :synopsis: Templates for formatting emails sent out by the email
                distributor.
 
 bridgedb.email.templates
 ========================
+
+Templates for formatting emails sent out by the email distributor.
 """
 
 from __future__ import print_function
@@ -34,6 +35,9 @@ from bridgedb.HTTPServer import TEMPLATE_DIR
 
 
 def addCommands(template):
+    """Add some text telling a client about supported email command, as well as
+    which Pluggable Transports are currently available.
+    """
     # Tell them about the various email commands:
     cmdlist = []
     cmdlist.append(template.gettext(strings.EMAIL_MISC_TEXT.get(3)))
@@ -95,6 +99,12 @@ def addBridgeAnswer(template, answer):
     return bridgeLines
 
 def addHowto(template):
+    """Add help text on how to add bridges to Tor Browser.
+
+    :type template: ``gettext.NullTranslation`` or ``gettext.GNUTranslation``
+    :param template: A gettext translations instance, optionally with fallback
+        languages set.
+    """
     howToTBB  = template.gettext(strings.HOWTO_TBB[1]) % strings.EMAIL_SPRINTF["HOWTO_TBB1"]
     howToTBB += u'\n\n'
     howToTBB += template.gettext(strings.HOWTO_TBB[2])



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits