Add type annotations (#99)

This is my first time using type hints so hopefully it's right.

* Added type annotations to the exported methods, some of the main internal methods, and the ValidatedEmail class.
* ValidatedEmail's ascii_email, ascii_local_part, ascii_domain, mx, and mx_fallback_type attributes now no longer are set by the class's __init__ method, although they are always filled in by validate_email.
* Make the main module's exports explicit to solve implicit re-export lint warning/error.
* Added py.typed.
* Added `mypy` to tests.
* Made a -dev4 release to test.

Closes #98.

Author: JoshData

.github/workflows/test_and_build.yaml

@@ -23,6 +23,9 @@ jobs:
       - name: Lint with flake8
         run: |
           make lint
+      - name: Check typing with mypy
+        run: |
+          make typing
       - name: Test with pytest
         run: |
           make test

.travis.yml

@@ -15,6 +15,7 @@ install:
 - make install
 
 script:
+- make typing
 - make lint
 - make test
 

CHANGELOG.md

@@ -1,9 +1,9 @@
-2.0.0-dev1
+2.0.0-dev4
 ----------
 
 This is a pre-release for version 2.0.0.
 
-There are no significant changes to which email addresses are considered valid/invalid, but there are many changes in error messages and internal improvements to the library, and Python 3.7+ is now required.
+There are no significant changes to which email addresses are considered valid/invalid, but there are many changes in error messages and internal improvements to the library including the addition of type annotations, and Python 3.7+ is now required.
 
 * Python 2.x and 3.x versions through 3.6, and dnspython 1.x, are no longer supported. Python 3.7+ with dnspython 2.x are now required.
 * The dnspython package is no longer required if DNS checks are not used, although it will install automatically.
@@ -12,6 +12,7 @@ There are no significant changes to which email addresses are considered valid/i
 * Some other error messages have changed to not repeat the email address in the error message.
 * The library has been reorganized internally into smaller modules.
 * The tests have been reorganized and expanded. Deliverability tests now mostly use captured DNS responses so they can be run off-line.
+* Type annotations have been added to the exported methods and the ValidatedEmail class and some internal methods.
 
 Version 1.3.1 (January 21, 2023)
 --------------------------------

Makefile

@@ -11,6 +11,10 @@ lint:
 	#python setup.py check -rms
 	flake8 --ignore=E501,E126,W503 email_validator tests
 
+.PHONY: typing
+typing:
+	mypy email_validator/*.py tests/*.py
+
 .PHONY: test
 test:
 	PYTHONPATH=.:$PYTHONPATH pytest --cov=email_validator
@@ -21,7 +25,7 @@ testcov: test
 	@coverage html
 
 .PHONY: all
-all: testcov lint
+all: typing testcov lint
 
 .PHONY: clean
 clean:

email_validator/__init__.py

@@ -1,8 +1,15 @@
 # -*- coding: utf-8 -*-
 
 # Export the main method, helper methods, and the public data types.
-from .exceptions_types import *  # noqa: F401,F403
-from .validate_email import validate_email  # noqa: F401
+from .exceptions_types import ValidatedEmail, EmailNotValidError, \
+                              EmailSyntaxError, EmailUndeliverableError
+from .validate_email import validate_email
+
+
+__all__ = ["validate_email",
+           "ValidatedEmail", "EmailNotValidError",
+           "EmailSyntaxError", "EmailUndeliverableError",
+           "caching_resolver"]
 
 
 def caching_resolver(*args, **kwargs):

email_validator/deliverability.py

@@ -1,20 +1,22 @@
+from typing import Optional, Any, Dict
+
 from .exceptions_types import EmailUndeliverableError
 
 import dns.resolver
 import dns.exception
 
 
-def caching_resolver(*, timeout=None, cache=None):
+def caching_resolver(*, timeout: Optional[int] = 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
+    resolver.cache = cache or dns.resolver.LRUCache()  # type: ignore
+    resolver.lifetime = timeout  # type: ignore # timeout, in seconds
     return resolver
 
 
-def validate_email_deliverability(domain, domain_i18n, timeout=None, dns_resolver=None):
+def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Optional[int] = 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
@@ -30,7 +32,7 @@ def validate_email_deliverability(domain, domain_i18n, timeout=None, dns_resolve
         dns_resolver = dns.resolver.get_default_resolver()
         dns_resolver.lifetime = timeout
 
-    deliverability_info = {}
+    deliverability_info: Dict[str, Any] = {}
 
     try:
         try:

email_validator/exceptions_types.py

@@ -1,3 +1,6 @@
+from typing import Optional
+
+
 class EmailNotValidError(ValueError):
     """Parent class of all exceptions raised by this module."""
     pass
@@ -18,42 +21,42 @@ class ValidatedEmail(object):
     and other information."""
 
     """The email address that was passed to validate_email. (If passed as bytes, this will be a string.)"""
-    original_email = None
+    original_email: str
 
     """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
+    email: str
 
     """The local part of the email address after Unicode normalization."""
-    local_part = None
+    local_part: str
 
     """The domain part of the email address after Unicode normalization or conversion to
     Unicode from IDNA ascii."""
-    domain = None
+    domain: str
 
     """If not None, a form of the email address that uses 7-bit ASCII characters only."""
-    ascii_email = None
+    ascii_email: Optional[str]
 
     """If not None, the local part of the email address using 7-bit ASCII characters only."""
-    ascii_local_part = None
+    ascii_local_part: Optional[str]
 
-    """If not None, a form of the domain name that uses 7-bit ASCII characters only."""
-    ascii_domain = None
+    """A form of the domain name that uses 7-bit ASCII characters only."""
+    ascii_domain: str
 
     """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
+    smtputf8: bool
 
     """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
+    mx: list
 
     """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
+    mx_fallback_type: str
 
     """Tests use this constructor."""
     def __init__(self, **kwargs):
@@ -92,13 +95,13 @@ def __eq__(self, other):
             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 getattr(self, 'ascii_email', None) == getattr(other, 'ascii_email', None)
+            and getattr(self, 'ascii_local_part', None) == getattr(other, 'ascii_local_part', None)
+            and getattr(self, 'ascii_domain', None) == getattr(other, 'ascii_domain', None)
             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
+            and repr(sorted(self.mx) if getattr(self, 'mx', None) else None)
+            == repr(sorted(other.mx) if getattr(other, 'mx', None) else None)
+            and getattr(self, 'mx_fallback_type', None) == getattr(other, 'mx_fallback_type', None)
         )
 
     """This helps producing the README."""

email_validator/syntax.py

@@ -30,7 +30,7 @@ def safe_character_display(c):
     return unicodedata.name(c, h)
 
 
-def validate_email_local_part(local, allow_smtputf8=True, allow_empty_local=False):
+def validate_email_local_part(local: str, allow_smtputf8: bool = True, allow_empty_local: bool = False):
     """Validates the syntax of the local part of an email address."""
 
     if len(local) == 0:

email_validator/validate_email.py

@@ -1,20 +1,22 @@
+from typing import Optional, Union
+
 from .exceptions_types import EmailSyntaxError, ValidatedEmail
 from .syntax import validate_email_local_part, validate_email_domain_part, get_length_reason
 from .rfc_constants import EMAIL_MAX_LENGTH
 
 
 def validate_email(
-    email,
+    email: Union[str, bytes],
     # /, # not supported in Python 3.6, 3.7
     *,
-    allow_smtputf8=None,
-    allow_empty_local=False,
-    check_deliverability=None,
-    test_environment=None,
-    globally_deliverable=None,
-    timeout=None,
-    dns_resolver=None
-):
+    allow_smtputf8: Optional[bool] = None,
+    allow_empty_local: bool = False,
+    check_deliverability: Optional[bool] = None,
+    test_environment: Optional[bool] = None,
+    globally_deliverable: Optional[bool] = None,
+    timeout: Optional[int] = None,
+    dns_resolver: Optional[object] = None
+) -> ValidatedEmail:
     """
     Validates an email address, raising an EmailNotValidError if the address is not valid or returning a dict of
     information when the address is valid. The email argument can be a str or a bytes instance,
@@ -70,7 +72,11 @@ def validate_email(
 
     # If the email address has an ASCII form, add it.
     if not ret.smtputf8:
-        ret.ascii_email = ret.ascii_local_part + "@" + ret.ascii_domain
+        if not ret.ascii_domain:
+            raise Exception("Missing ASCII domain.")
+        ret.ascii_email = (ret.ascii_local_part or "") + "@" + ret.ascii_domain
+    else:
+        ret.ascii_email = None
 
     # If the email address has an ASCII representation, then we assume it may be
     # transmitted in ASCII (we can't assume SMTPUTF8 will be used on all hops to

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = email_validator
-version = 2.0.0-dev1
+version = 2.0.0-dev4
 description = A robust email address syntax and deliverability validation library.
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -29,6 +29,9 @@ install_requires =
     idna>=2.0.0
 python_requires = >=3.7
 
+[options.package_data]
+* = py.typed
+
 [options.entry_points]
 console_scripts =
     email_validator=email_validator:main