[tor-commits] [bridgedb/master] Add docstring for email.server.MailMessage.getClientAddress.

[isis at torproject.org]

commit c68a04ed3f23777c14962164cc19918fb30b96b2
Author: Isis Lovecruft <isis at torproject.org>
Date:   Fri May 9 16:33:54 2014 +0000

    Add docstring for email.server.MailMessage.getClientAddress.
---
 lib/bridgedb/email/server.py |   12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/lib/bridgedb/email/server.py b/lib/bridgedb/email/server.py
index 838093e..7aeb4ff 100644
--- a/lib/bridgedb/email/server.py
+++ b/lib/bridgedb/email/server.py
@@ -501,7 +501,7 @@ class MailMessage(object):
         """Create and parse an :rfc:`2822` message object for all ``lines``
         received thus far.
 
-        :rtype: :api:`twisted.mail.smtp.rfc822.Message`.
+        :rtype: :api:`twisted.mail.smtp.rfc822.Message`
         :returns: A ``Message`` comprised of all lines received thus far.
         """
         rawMessage = io.StringIO()
@@ -510,6 +510,16 @@ class MailMessage(object):
         return smtp.rfc822.Message(rawMessage)
 
     def getClientAddress(self, incoming):
+        """Attempt to get the client's email address from an incoming email.
+
+        :type incoming: :api:`twisted.mail.smtp.rfc822.Message`
+        :param incoming: An incoming ``Message``, i.e. as returned from
+            :meth:`getIncomingMessage`.
+        :rtype: ``None`` or :api:`twisted.mail.smtp.Address`
+        :returns: The client's email ``Address``, if it originated from a
+            domain that we accept and the address was well-formed. Otherwise,
+            returns ``None``.
+        """
         addrHeader = None
         try: fromAddr = incoming.getaddr("From")[1]
         except (IndexError, TypeError, AttributeError): pass