Reorganize the library into smaller modules

There are no logic changes in this commit, just moving code.

Author: JoshData

CHANGELOG.md

@@ -1,3 +1,8 @@
+In Development
+--------------
+
+* The library has been reorganized internally into smaller modules.
+
 Version 1.3.1 (January 21, 2023)
 --------------------------------
 

email_validator/__init__.py

@@ -0,0 +1,53 @@
+# A command-line tool for testing.
+#
+# Usage:
+#
+# python -m email_validator
+#
+# Provide email addresses to validate either as a command-line argument
+# or in STDIN separated by newlines. No output will be given for valid
+# email addresses. Validation errors will be printed for invalid email
+# addresses.
+
+import json
+import sys
+
+from .validate_email import validate_email
+from .deliverability import caching_resolver
+from .exceptions_types import EmailNotValidError
+
+
+def __utf8_input_shim(input_str):
+    if sys.version_info < (3,):
+        return input_str.decode("utf-8")
+    return input_str
+
+
+def __utf8_output_shim(output_str):
+    if sys.version_info < (3,):
+        return unicode_class(output_str).encode("utf-8")
+    return output_str
+
+
+def main():
+    if len(sys.argv) == 1:
+        # Validate the email addresses pased line-by-line on STDIN.
+        dns_resolver = caching_resolver()
+        for line in sys.stdin:
+            email = __utf8_input_shim(line.strip())
+            try:
+                validate_email(email, dns_resolver=dns_resolver)
+            except EmailNotValidError as e:
+                print(__utf8_output_shim("{} {}".format(email, e)))
+    else:
+        # Validate the email address passed on the command line.
+        email = __utf8_input_shim(sys.argv[1])
+        try:
+            result = validate_email(email)
+            print(json.dumps(result.as_dict(), indent=2, sort_keys=True, ensure_ascii=False))
+        except EmailNotValidError as e:
+            print(__utf8_output_shim(e))
+
+
+if __name__ == "__main__":
+    main()

email_validator/__main__.py

@@ -0,0 +1,131 @@
+from .exceptions_types import EmailUndeliverableError
+
+import dns.resolver
+import dns.exception
+
+
+def caching_resolver(*, timeout=None, cache=None):
+    if timeout is None:
+        from . import DEFAULT_TIMEOUT
+        timeout = DEFAULT_TIMEOUT
+    resolver = dns.resolver.Resolver()
+    resolver.cache = cache or dns.resolver.LRUCache()
+    resolver.lifetime = timeout  # timeout, in seconds
+    return resolver
+
+
+def validate_email_deliverability(domain, domain_i18n, timeout=None, dns_resolver=None):
+    # Check that the domain resolves to an MX record. If there is no MX record,
+    # try an A or AAAA record which is a deprecated fallback for deliverability.
+    # Raises an EmailUndeliverableError on failure. On success, returns a dict
+    # with deliverability information.
+
+    # If no dns.resolver.Resolver was given, get dnspython's default resolver.
+    # Override the default resolver's timeout. This may affect other uses of
+    # dnspython in this process.
+    if dns_resolver is None:
+        from . import DEFAULT_TIMEOUT
+        if timeout is None:
+            timeout = DEFAULT_TIMEOUT
+        dns_resolver = dns.resolver.get_default_resolver()
+        dns_resolver.lifetime = timeout
+
+    deliverability_info = {}
+
+    def dns_resolver_resolve_shim(domain, record):
+        try:
+            # dns.resolver.Resolver.resolve is new to dnspython 2.x.
+            # https://dnspython.readthedocs.io/en/latest/resolver-class.html#dns.resolver.Resolver.resolve
+            return dns_resolver.resolve(domain, record)
+        except AttributeError:
+            # dnspython 2.x is only available in Python 3.6 and later. For earlier versions
+            # of Python, we maintain compatibility with dnspython 1.x which has a
+            # dnspython.resolver.Resolver.query method instead. The only difference is that
+            # query may treat the domain as relative and use the system's search domains,
+            # which we prevent by adding a "." to the domain name to make it absolute.
+            # dns.resolver.Resolver.query is deprecated in dnspython version 2.x.
+            # https://dnspython.readthedocs.io/en/latest/resolver-class.html#dns.resolver.Resolver.query
+            return dns_resolver.query(domain + ".", record)
+
+    try:
+        # We need a way to check how timeouts are handled in the tests. So we
+        # have a secret variable that if set makes this method always test the
+        # handling of a timeout.
+        if getattr(validate_email_deliverability, 'TEST_CHECK_TIMEOUT', False):
+            raise dns.exception.Timeout()
+
+        try:
+            # Try resolving for MX records.
+            response = dns_resolver_resolve_shim(domain, "MX")
+
+            # For reporting, put them in priority order and remove the trailing dot in the qnames.
+            mtas = sorted([(r.preference, str(r.exchange).rstrip('.')) for r in response])
+
+            # Remove "null MX" records from the list (their value is (0, ".") but we've stripped
+            # trailing dots, so the 'exchange' is just ""). If there was only a null MX record,
+            # email is not deliverable.
+            mtas = [(preference, exchange) for preference, exchange in mtas
+                    if exchange != ""]
+            if len(mtas) == 0:
+                raise EmailUndeliverableError("The domain name %s does not accept email." % domain_i18n)
+
+            deliverability_info["mx"] = mtas
+            deliverability_info["mx_fallback_type"] = None
+
+        except (dns.resolver.NoNameservers, dns.resolver.NXDOMAIN, dns.resolver.NoAnswer):
+
+            # If there was no MX record, fall back to an A record, as SMTP servers do.
+            try:
+                response = dns_resolver_resolve_shim(domain, "A")
+                deliverability_info["mx"] = [(0, str(r)) for r in response]
+                deliverability_info["mx_fallback_type"] = "A"
+            except (dns.resolver.NoNameservers, dns.resolver.NXDOMAIN, dns.resolver.NoAnswer):
+
+                # If there was no A record, fall back to an AAAA record.
+                try:
+                    response = dns_resolver_resolve_shim(domain, "AAAA")
+                    deliverability_info["mx"] = [(0, str(r)) for r in response]
+                    deliverability_info["mx_fallback_type"] = "AAAA"
+                except (dns.resolver.NoNameservers, dns.resolver.NXDOMAIN, dns.resolver.NoAnswer):
+
+                    # If there was no MX, A, or AAAA record, then mail to
+                    # this domain is not deliverable.
+                    raise EmailUndeliverableError("The domain name %s does not exist." % domain_i18n)
+
+            # Check for a SPF reject-all record ("v=spf1 -all") which indicates
+            # no emails are sent from this domain (similar to a NULL MX record
+            # but for sending rather than receiving). In combination with the
+            # absence of an MX record, this is probably a good sign that the
+            # domain is not used for email.
+            try:
+                response = dns_resolver_resolve_shim(domain, "TXT")
+                for rec in response:
+                    value = b"".join(rec.strings)
+                    if value.startswith(b"v=spf1 "):
+                        deliverability_info["spf"] = value.decode("ascii", errors='replace')
+                        if value == b"v=spf1 -all":
+                            raise EmailUndeliverableError("The domain name %s does not send email." % domain_i18n)
+            except dns.resolver.NoAnswer:
+                # No TXT records means there is no SPF policy, so we cannot take any action.
+                pass
+            except (dns.resolver.NoNameservers, dns.resolver.NXDOMAIN):
+                # Failure to resolve at this step will be ignored.
+                pass
+
+    except dns.exception.Timeout:
+        # A timeout could occur for various reasons, so don't treat it as a failure.
+        return {
+            "unknown-deliverability": "timeout",
+        }
+
+    except EmailUndeliverableError:
+        # Don't let these get clobbered by the wider except block below.
+        raise
+
+    except Exception as e:
+        # Unhandled conditions should not propagate.
+        raise EmailUndeliverableError(
+            "There was an error while checking if the domain name in the email address is deliverable: " + str(e)
+        )
+
+    return deliverability_info

email_validator/deliverability.py

@@ -0,0 +1,122 @@
+class EmailNotValidError(ValueError):
+    """Parent class of all exceptions raised by this module."""
+    pass
+
+
+class EmailSyntaxError(EmailNotValidError):
+    """Exception raised when an email address fails validation because of its form."""
+    pass
+
+
+class EmailUndeliverableError(EmailNotValidError):
+    """Exception raised when an email address fails validation because its domain name does not appear deliverable."""
+    pass
+
+
+class ValidatedEmail(object):
+    """The validate_email function returns objects of this type holding the normalized form of the email address
+    and other information."""
+
+    """The email address that was passed to validate_email. (If passed as bytes, this will be a string.)"""
+    original_email = None
+
+    """The normalized email address, which should always be used in preferance to the original address.
+    The normalized address converts an IDNA ASCII domain name to Unicode, if possible, and performs
+    Unicode normalization on the local part and on the domain (if originally Unicode). It is the
+    concatenation of the local_part and domain attributes, separated by an @-sign."""
+    email = None
+
+    """The local part of the email address after Unicode normalization."""
+    local_part = None
+
+    """The domain part of the email address after Unicode normalization or conversion to
+    Unicode from IDNA ascii."""
+    domain = None
+
+    """If not None, a form of the email address that uses 7-bit ASCII characters only."""
+    ascii_email = None
+
+    """If not None, the local part of the email address using 7-bit ASCII characters only."""
+    ascii_local_part = None
+
+    """If not None, a form of the domain name that uses 7-bit ASCII characters only."""
+    ascii_domain = None
+
+    """If True, the SMTPUTF8 feature of your mail relay will be required to transmit messages
+    to this address. This flag is True just when ascii_local_part is missing. Otherwise it
+    is False."""
+    smtputf8 = None
+
+    """If a deliverability check is performed and if it succeeds, a list of (priority, domain)
+    tuples of MX records specified in the DNS for the domain."""
+    mx = None
+
+    """If no MX records are actually specified in DNS and instead are inferred, through an obsolete
+    mechanism, from A or AAAA records, the value is the type of DNS record used instead (`A` or `AAAA`)."""
+    mx_fallback_type = None
+
+    """Tests use this constructor."""
+    def __init__(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)
+
+    """As a convenience, str(...) on instances of this class return the normalized address."""
+    def __self__(self):
+        return self.normalized_email
+
+    def __repr__(self):
+        return "<ValidatedEmail {}>".format(self.email)
+
+    """For backwards compatibility, some fields are also exposed through a dict-like interface. Note
+    that some of the names changed when they became attributes."""
+    def __getitem__(self, key):
+        if key == "email":
+            return self.email
+        if key == "email_ascii":
+            return self.ascii_email
+        if key == "local":
+            return self.local_part
+        if key == "domain":
+            return self.ascii_domain
+        if key == "domain_i18n":
+            return self.domain
+        if key == "smtputf8":
+            return self.smtputf8
+        if key == "mx":
+            return self.mx
+        if key == "mx-fallback":
+            return self.mx_fallback_type
+        raise KeyError()
+
+    """Tests use this."""
+    def __eq__(self, other):
+        if not isinstance(other, ValidatedEmail):
+            return False
+        return (
+            self.email == other.email
+            and self.local_part == other.local_part
+            and self.domain == other.domain
+            and self.ascii_email == other.ascii_email
+            and self.ascii_local_part == other.ascii_local_part
+            and self.ascii_domain == other.ascii_domain
+            and self.smtputf8 == other.smtputf8
+            and repr(sorted(self.mx) if self.mx else self.mx)
+            == repr(sorted(other.mx) if other.mx else other.mx)
+            and self.mx_fallback_type == other.mx_fallback_type
+        )
+
+    """This helps producing the README."""
+    def as_constructor(self):
+        return "ValidatedEmail(" \
+            + ",".join("\n  {}={}".format(
+                       key,
+                       repr(getattr(self, key)))
+                       for key in ('email', 'local_part', 'domain',
+                                   'ascii_email', 'ascii_local_part', 'ascii_domain',
+                                   'smtputf8', 'mx', 'mx_fallback_type')
+                       ) \
+            + ")"
+
+    """Convenience method for accessing ValidatedEmail as a dict"""
+    def as_dict(self):
+        return self.__dict__

email_validator/exceptions_types.py

@@ -0,0 +1,39 @@
+import sys
+
+# These constants are defined by the email specifications.
+
+# Based on RFC 2822 section 3.2.4 / RFC 5322 section 3.2.3, these
+# characters are permitted in email addresses (not taking into
+# account internationalization):
+ATEXT = r'a-zA-Z0-9_!#\$%&\'\*\+\-/=\?\^`\{\|\}~'
+
+# A "dot atom text", per RFC 2822 3.2.4:
+DOT_ATOM_TEXT = '[' + ATEXT + ']+(?:\\.[' + ATEXT + ']+)*'
+
+# RFC 6531 section 3.3 extends the allowed characters in internationalized
+# addresses to also include three specific ranges of UTF8 defined in
+# RFC3629 section 4, which appear to be the Unicode code points from
+# U+0080 to U+10FFFF.
+ATEXT_INTL = ATEXT + u"\u0080-\U0010FFFF"
+DOT_ATOM_TEXT_INTL = '[' + ATEXT_INTL + ']+(?:\\.[' + ATEXT_INTL + ']+)*'
+
+# The domain part of the email address, after IDNA (ASCII) encoding,
+# must also satisfy the requirements of RFC 952/RFC 1123 which restrict
+# the allowed characters of hostnames further. The hyphen cannot be at
+# the beginning or end of a *dot-atom component* of a hostname either.
+ATEXT_HOSTNAME = r'(?:(?:[a-zA-Z0-9][a-zA-Z0-9\-]*)?[a-zA-Z0-9])'
+
+# Length constants
+# RFC 3696 + errata 1003 + errata 1690 (https://www.rfc-editor.org/errata_search.php?rfc=3696&eid=1690)
+# explains the maximum length of an email address is 254 octets.
+EMAIL_MAX_LENGTH = 254
+LOCAL_PART_MAX_LENGTH = 64
+DOMAIN_MAX_LENGTH = 255
+
+
+# In Python 2.x, turn the regexes above from bytes regexes into unicode
+# regexes. If Python 3.x had a "ur" string literal prefix we'd use that instead.
+if sys.version_info < (3,):
+    ATEXT = ATEXT.decode("ascii")
+    DOT_ATOM_TEXT = DOT_ATOM_TEXT.decode("ascii")
+    ATEXT_HOSTNAME = ATEXT_HOSTNAME.decode("ascii")