Remove example and example.com/net/org from the special use domains list

By popular demand in #78.

Author: JoshData

email_validator/__init__.py

@@ -39,20 +39,66 @@
 # IANA Special Use Domain Names
 # Last Updated 2021-09-21
 # https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.txt
+#
 # The domain names without dots would be caught by the check that the domain
 # name in an email address must have a period, but this list will also catch
 # subdomains of these domains, which are also reserved.
 SPECIAL_USE_DOMAIN_NAMES = (
-    "arpa",  # consolidated from a lot of arpa subdomains, we'll assume all subdomains of arpa are actually reserved
-    "example",
-    "example.com",
-    "example.net",
-    "example.org",
+    # The "arpa" entry here is consolidated from a lot of arpa subdomains
+    # for private address (i.e. non-routable IP addresses like 172.16.x.x)
+    # reverse mapping, plus some other subdomains. Although RFC 6761 says
+    # that application software should not treat these domains as special,
+    # they are private-use domains and so cannot have globally deliverable
+    # email addresses, which is an assumption of this library, and probably
+    # all of arpa is similarly special-use, so we reject it all.
+    "arpa",
+
+    # RFC 6761 says applications "SHOULD NOT" treat the "example" domains
+    # as special, i.e. applications should accept these domains.
+    #
+    # The domain "example" alone fails our syntax validation because it
+    # lacks a dot (we assume no one has an email address on a TLD directly).
+    # "@example.com/net/org" will currently fail DNS-based deliverability
+    # checks because IANA publishes a NULL MX for these domains, and
+    # "@mail.example[.com/net/org]" and other subdomains will fail DNS-
+    # based deliverability checks because IANA does not publish MX or A
+    # DNS records for these subdomains.
+    # "example", # i.e. "wwww.example"
+    # "example.com",
+    # "example.net",
+    # "example.org",
+
+    # RFC 6761 says that applications are permitted to treat this domain
+    # as special and that DNS should return an immediate negative response,
+    # so we also immediately reject this domain, which also follows the
+    # purpose of the domain.
     "invalid",
+
+    # RFC 6762 says that applications "may" treat ".local" as special and
+    # that "name resolution APIs and libraries SHOULD recognize these names
+    # as special," and since ".local" has no global definition, we reject
+    # it, as we expect email addresses to be gloally routable.
     "local",
+
+    # RFC 6761 says that applications (like this library) are permitted
+    # to treat "localhost" as special, and since it cannot have a globally
+    # deliverable email address, we reject it.
     "localhost",
+
+    # RFC 7686 says "applications that do not implement the Tor protocol
+    # SHOULD generate an error upon the use of .onion and SHOULD NOT
+    # perform a DNS lookup.
     "onion",
-    "test",  # see special logic for 'test' where this is checked
+
+    # Although RFC 6761 says that application software should not treat
+    # these domains as special, it also warns users that the address may
+    # resolve differently in different systems, and therefore it cannot
+    # have a globally routable email address, which is an assumption of
+    # this library, so we reject "@test" and "@*.test" addresses, unless
+    # the test_environment keyword argument is given, to allow their use
+    # in application-level test environments. These domains will generally
+    # fail deliverability checks because "test" is not an actual TLD.
+    "test",
 )
 
 # ease compatibility in type checking
@@ -501,11 +547,7 @@ def validate_email_domain_part(domain, test_environment=False):
     # Some might fail DNS-based deliverability checks, but that
     # can be turned off, so we should fail them all sooner.
     for d in SPECIAL_USE_DOMAIN_NAMES:
-        # RFC 6761 says that applications should not block use of the 'test'
-        # domain name, presumably because that would prevent it from being
-        # used for actual testing. We'll block it, except when a special
-        # testing flag is used, indicating that the module is being used
-        # in a test environment.
+        # See the note near the definition of SPECIAL_USE_DOMAIN_NAMES.
         if d == "test" and test_environment:
             continue
 

tests/test_main.py

@@ -1,4 +1,5 @@
 import dns.resolver
+import re
 import pytest
 from email_validator import EmailSyntaxError, EmailUndeliverableError, \
                             validate_email, validate_email_deliverability, \
@@ -260,9 +261,6 @@ def test_email_invalid_syntax(email_input, error_msg):
     'email_input',
     [
         ('me@anything.arpa'),
-        ('me@anything.example'),
-        ('me@example.com'),
-        ('me@mail.example.com'),
         ('me@valid.invalid'),
         ('me@link.local'),
         ('me@host.localhost'),
@@ -279,6 +277,23 @@ def test_email_invalid_reserved_domain(email_input):
     assert "is a special-use or reserved name" in str(exc_info.value)
 
 
+@pytest.mark.parametrize(
+    'email_input',
+    [
+        ('me@mail.example'),
+        ('me@example.com'),
+        ('me@mail.example.com'),
+    ],
+)
+def test_email_example_reserved_domain(email_input):
+    # Since these all fail deliverabiltiy from a static list,
+    # DNS deliverability checks do not arise.
+    with pytest.raises(EmailUndeliverableError) as exc_info:
+        validate_email(email_input)
+    # print(f'({email_input!r}, {str(exc_info.value)!r}),')
+    assert re.match(r"The domain name [a-z\.]+ does not (accept email|exist)\.", str(exc_info.value)) is not None
+
+
 @pytest.mark.parametrize(
     'email_input',
     [