Add toggle for disabling gTLD domains

In some cases, it doesn't make sense within the domain of the problem
you're solving to accept a domain at a gTLD, in particular when that
gTLD is not registered.

To ease the use of the library in cases such as this, `is_email` now
takes a flag called `allow_gtld` that disallows any address where the
domain part of the email address is a gTLD.

Author: michaelherold

README.rst

@@ -77,10 +77,23 @@ These are primary indicators of whether an email address can even be
 issued at that domain. However, a valid response here *is not a guarantee
 that the email exists*, merely that is *can* exist.
 
+If you want to limit using a `gTLD`_ as the domain part of the email
+address, you can do so with a flag:
+
+.. code-block:: python
+
+    from pyisemail import is_email
+
+    address = "thiswont@workatall"
+    bool_result_with_check = is_email(address, allow_gtld=False)
+    detailed_result_with_check = is_email(address, allow_gtld=False, diagnose=True)
+
 In addition to the base ``is_email`` functionality, you can also use the
 validators by themselves. Check the validator source doe to see how this
 works.
 
+.. _gTLD: https://en.wikipedia.org/wiki/Generic_top-level_domain
+
 Uninstall
 ---------
 

pyisemail/__init__.py

@@ -2,27 +2,36 @@
 from pyisemail.email_validator import EmailValidator
 from pyisemail.reference import Reference
 from pyisemail.validators import DNSValidator
+from pyisemail.validators import GTLDValidator
 from pyisemail.validators import ParserValidator
 from pyisemail.version import VERSION
 
 __version__ = VERSION
 __all__ = ['is_email']
 
 
-def is_email(address, check_dns=False, diagnose=False):
+def is_email(address, check_dns=False, diagnose=False, allow_gtld=True):
     """Validate an email address.
 
     Keyword arguments:
     address   --- the email address as a string
     check_dns --- flag for whether to check the DNS status of the domain
     diagnose  --- flag for whether to return True/False or a Diagnosis
+    allow_gtld --- flag for whether to prevent gTLDs as the domain
 
     """
 
     threshold = BaseDiagnosis.CATEGORIES["THRESHOLD"]
     d = ParserValidator().is_email(address, True)
-    if check_dns is True and d < BaseDiagnosis.CATEGORIES["DNSWARN"]:
-        threshold = BaseDiagnosis.CATEGORIES["VALID"]
-        d = max(d, DNSValidator().is_valid(address.split("@")[1], True))
+
+    if d < BaseDiagnosis.CATEGORIES["DNSWARN"]:
+        domain = address.split("@")[1]
+
+        if check_dns is True or allow_gtld is False:
+            threshold = BaseDiagnosis.CATEGORIES["VALID"]
+        if check_dns is True:
+            d = max(d, DNSValidator().is_valid(domain, True))
+        if allow_gtld is False:
+            d = max(d, GTLDValidator().is_valid(domain, True))
 
     return d if diagnose else d < threshold

pyisemail/diagnosis/__init__.py

@@ -2,6 +2,7 @@
 from pyisemail.diagnosis.cfws_diagnosis import CFWSDiagnosis
 from pyisemail.diagnosis.deprecated_diagnosis import DeprecatedDiagnosis
 from pyisemail.diagnosis.dns_diagnosis import DNSDiagnosis
+from pyisemail.diagnosis.gtld_diagnosis import GTLDDiagnosis
 from pyisemail.diagnosis.invalid_diagnosis import InvalidDiagnosis
 from pyisemail.diagnosis.rfc5321_diagnosis import RFC5321Diagnosis
 from pyisemail.diagnosis.rfc5322_diagnosis import RFC5322Diagnosis

pyisemail/diagnosis/gtld_diagnosis.py

@@ -0,0 +1,17 @@
+from pyisemail.diagnosis import BaseDiagnosis
+
+
+class GTLDDiagnosis(BaseDiagnosis):
+
+    """A diagnosis indicating that a domain is a disallowed gTLD."""
+
+    DESCRIPTION = "Address uses a gTLD as its domain."
+
+    ERROR_CODES = {"GTLD": 2}
+
+    MESSAGES = {
+        "GTLD": (
+            "Address has a gTLD as its domain and you "
+            "have disallowed those in your check."
+        )
+    }

pyisemail/validators/__init__.py

@@ -1,4 +1,5 @@
 from pyisemail.validators.dns_validator import DNSValidator
+from pyisemail.validators.gtld_validator import GTLDValidator
 from pyisemail.validators.parser_validator import ParserValidator
 
-__all__ = ['DNSValidator', 'ParserValidator']
+__all__ = ['DNSValidator', 'GTLDValidator', 'ParserValidator']

pyisemail/validators/gtld_validator.py

@@ -0,0 +1,20 @@
+from pyisemail.diagnosis import GTLDDiagnosis, ValidDiagnosis
+
+
+class GTLDValidator(object):
+    def is_valid(self, domain, diagnose=False):
+
+        """Check whether a domain is a gTLD.
+
+        Keyword arguments:
+        domain   --- the domain to check
+        diagnose --- flag to report a diagnosis or a boolean (default False)
+
+        """
+
+        if "." in domain:
+            d = ValidDiagnosis()
+        else:
+            d = GTLDDiagnosis("GTLD")
+
+        return d

tests/test_is_email.py

@@ -1,19 +1,25 @@
 from testscenarios import TestWithScenarios
 from unittest import TestCase
+
 try:
     from unittest.mock import patch
 except ImportError:
     from mock import patch
 import dns.resolver
 from pyisemail import is_email
-from pyisemail.diagnosis import BaseDiagnosis, DNSDiagnosis
+from pyisemail.diagnosis import (
+    BaseDiagnosis,
+    DNSDiagnosis,
+    GTLDDiagnosis,
+    ValidDiagnosis,
+)
 from tests.validators import create_diagnosis, get_scenarios
 
 
 class IsEmailTest(TestWithScenarios):
 
     scenarios = get_scenarios("tests.xml")
-    threshold = BaseDiagnosis.CATEGORIES['THRESHOLD']
+    threshold = BaseDiagnosis.CATEGORIES["THRESHOLD"]
 
     def test_without_diagnosis(self):
         result = is_email(self.address)
@@ -22,8 +28,10 @@ def test_without_diagnosis(self):
         self.assertEqual(
             result,
             expected,
-            ("%s (%s): Got %s, but expected %s."
-             % (self.id, self.address, result, expected))
+            (
+                "%s (%s): Got %s, but expected %s."
+                % (self.id, self.address, result, expected)
+            ),
         )
 
     def test_with_diagnosis(self):
@@ -33,20 +41,33 @@ def test_with_diagnosis(self):
         self.assertEqual(
             result,
             expected,
-            ("%s (%s): Got %s, but expected %s."
-                % (self.id, self.address, result, expected))
+            (
+                "%s (%s): Got %s, but expected %s."
+                % (self.id, self.address, result, expected)
+            ),
         )
 
 
-@patch('dns.resolver.query', side_effect=dns.resolver.NoAnswer)
+@patch("dns.resolver.query", side_effect=dns.resolver.NoAnswer)
 class CheckDNSFailureTestCase(TestCase):
-
     def test_without_diagnosis(self, mocked_method):
-        result = is_email('test@example.com', check_dns=True)
+        result = is_email("test@example.com", check_dns=True)
         expected = False
         self.assertEqual(result, expected)
 
     def test_with_diagnosis(self, mocked_method):
-        result = is_email('test@example.com', check_dns=True, diagnose=True)
-        expected = DNSDiagnosis('NO_RECORD')
+        result = is_email("test@example.com", check_dns=True, diagnose=True)
+        expected = DNSDiagnosis("NO_RECORD")
         self.assertEqual(result, expected)
+
+
+class GTLDTest(TestCase):
+    def test_with_diagnosis(self):
+        self.assertTrue(is_email("a@b"))
+        self.assertFalse(is_email("a@b", allow_gtld=False))
+
+    def test_without_diagnosis(self):
+        self.assertEqual(is_email("a@b", diagnose=True), ValidDiagnosis())
+        self.assertEqual(
+            is_email("a@b", allow_gtld=False, diagnose=True), GTLDDiagnosis("GTLD")
+        )