Rename the email field of ValidatedEmail to normalized to be clearer about its importance

Author: JoshData

CHANGELOG.md

@@ -11,6 +11,7 @@ There are no significant changes to which email addresses are considered valid/i
 * Some syntax error messages have changed because they are now checked explicitly rather than as a part of other checks.
 * The quoted-string local part syntax (e.g. multiple @-signs, spaces, etc. if surrounded by quotes) and domain-literal addresses (e.g. @[192.XXX...] or @[IPv6:...]) are now parsed but not considered valid by default. Better error messages are now given for these addresses since it can be confusing for a technically valid address to be rejected, and new allow_quoted_local and allow_domain_literal options are added to allow these addresses if you really need them.
 * Some other error messages have changed to not repeat the email address in the error message.
+* The `email` field on the returned `ValidatedEmail` object has been renamed to `normalized` to be clearer about its importance, but access via `.email` is also still supported.
 * 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.
 * The __main__ tool now reads options to validate_email from environment variables.

README.md

@@ -65,11 +65,11 @@ try:
   # Check that the email address is valid. Turn on check_deliverability
   # for first-time validations like on account creation pages (but not
   # login pages).
-  validation = validate_email(email, check_deliverability=False)
+  emailinfo = validate_email(email, check_deliverability=False)
 
   # After this point, use only the normalized form of the email address,
   # especially before going to a database query.
-  email = validation.email
+  email = emailinfo.normalized
 
 except EmailNotValidError as e:
 
@@ -158,7 +158,7 @@ from email_validator import validate_email, caching_resolver
 resolver = caching_resolver(timeout=10)
 
 while True:
-  email = validate_email(email, dns_resolver=resolver).email
+  validate_email(email, dns_resolver=resolver)
 ```
 
 ### Test addresses
@@ -249,8 +249,8 @@ This library gives you back the ASCII-ized form in the `ascii_email`
 field in the returned object, which you can get like this:
 
 ```python
-valid = validate_email(email, allow_smtputf8=False)
-email = valid.ascii_email
+emailinfo = validate_email(email, allow_smtputf8=False)
+email = emailinfo.ascii_email
 ```
 
 The local part is left alone (if it has internationalized characters
@@ -266,7 +266,7 @@ Normalization
 
 The use of Unicode in email addresses introduced a normalization
 problem. Different Unicode strings can look identical and have the same
-semantic meaning to the user. The `email` field returned on successful
+semantic meaning to the user. The `normalized` field returned on successful
 validation provides the correctly normalized form of the given email
 address.
 
@@ -275,9 +275,9 @@ equivalent in domain names to their ASCII counterparts. This library
 normalizes them to their ASCII counterparts:
 
 ```python
-valid = validate_email("me@Ｄｏｍａｉｎ.com")
-print(valid.email)
-print(valid.ascii_email)
+emailinfo = validate_email("me@Ｄｏｍａｉｎ.com")
+print(emailinfo.normalized)
+print(emailinfo.ascii_email)
 # prints "me@domain.com" twice
 ```
 
@@ -321,7 +321,7 @@ For the email address `test@joshdata.me`, the returned object is:
 
 ```python
 ValidatedEmail(
-  email='test@joshdata.me',
+  normalized='test@joshdata.me',
   local_part='test',
   domain='joshdata.me',
   ascii_email='test@joshdata.me',
@@ -335,7 +335,7 @@ internationalized domain but ASCII local part, the returned object is:
 
 ```python
 ValidatedEmail(
-  email='example@ツ.life',
+  normalized='example@ツ.life',
   local_part='example',
   domain='ツ.life',
   ascii_email='example@xn--bdk.life',
@@ -345,20 +345,20 @@ ValidatedEmail(
 
 ```
 
-Note that the `email` and `domain` fields provide a normalized form of the
+Note that `normalized` and other fields provide a normalized form of the
 email address, domain name, and (in other cases) local part (see earlier
 discussion of normalization), which you should use in your database.
 
 Calling `validate_email` with the ASCII form of the above email address,
 `example@xn--bdk.life`, returns the exact same information (i.e., the
-`email` field always will contain Unicode characters, not Punycode).
+`normalized` field always will contain Unicode characters, not Punycode).
 
 For the fictitious address `ツ-test@joshdata.me`, which has an
 internationalized local part, the returned object is:
 
 ```python
 ValidatedEmail(
-  email='ツ-test@joshdata.me',
+  normalized='ツ-test@joshdata.me',
   local_part='ツ-test',
   domain='joshdata.me',
   ascii_email=None,
@@ -368,10 +368,8 @@ ValidatedEmail(
 ```
 
 Now `smtputf8` is `True` and `ascii_email` is `None` because the local
-part of the address is internationalized. The `local_part` and `email` fields
-return the normalized form of the address: certain Unicode characters
-(such as angstrom and ohm) may be replaced by other equivalent code
-points (a-with-ring and omega).
+part of the address is internationalized. The `local_part` and `normalized` fields
+return the normalized form of the address.
 
 Return value
 ------------
@@ -381,8 +379,8 @@ are:
 
 | Field | Value |
 | -----:|-------|
-| `email` | The normalized form of the email address that you should put in your database. This combines the `local_part` and `domain` fields (see below). |
-| `ascii_email` | If set, an ASCII-only form of the email address by replacing the domain part with [IDNA](https://tools.ietf.org/html/rfc5891) [Punycode](https://www.rfc-editor.org/rfc/rfc3492.txt). This field will be present when an ASCII-only form of the email address exists (including if the email address is already ASCII). If the local part of the email address contains internationalized characters, `ascii_email` will be `None`. If set, it merely combines `ascii_local_part` and `ascii_domain`. |
+| `normalized` | The normalized form of the email address that you should put in your database. This combines the `local_part` and `domain` fields (see below). |
+| `ascii_email` | If set, an ASCII-only form of the normalized email address by replacing the domain part with [IDNA](https://tools.ietf.org/html/rfc5891) [Punycode](https://www.rfc-editor.org/rfc/rfc3492.txt). This field will be present when an ASCII-only form of the email address exists (including if the email address is already ASCII). If the local part of the email address contains internationalized characters, `ascii_email` will be `None`. If set, it merely combines `ascii_local_part` and `ascii_domain`. |
 | `local_part` | The normalized local part of the given email address (before the @-sign). Normalization includes Unicode NFC normalization and removing unnecessary quoted-string quotes and backslashes. If `allow_quoted_local` is True and the surrounding quotes are necessary, the quotes _will_ be present in this field. |
 | `ascii_local_part` | If set, the local part, which is composed of ASCII characters only. |
 | `domain` | The canonical internationalized Unicode form of the domain part of the email address. If the returned string contains non-ASCII characters, either the [SMTPUTF8](https://tools.ietf.org/html/rfc6531) feature of your mail relay will be required to transmit the message or else the email address's domain part must be converted to IDNA ASCII first: Use `ascii_domain` field instead. |

email_validator/exceptions_types.py

@@ -22,13 +22,13 @@ 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: str
+    original: 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: str
+    normalized: str
 
     """The local part of the email address after Unicode normalization."""
     local_part: str
@@ -68,14 +68,22 @@ def __init__(self, **kwargs):
             setattr(self, k, v)
 
     def __repr__(self):
-        return f"<ValidatedEmail {self.email}>"
+        return f"<ValidatedEmail {self.normalized}>"
+
+    """For backwards compatibility, support old field names."""
+    def __getattr__(self, key):
+        if key == "original_email":
+            return self.original
+        if key == "email":
+            return self.normalized
+        raise AttributeError()
 
     """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):
         warnings.warn("dict-like access to the return value of validate_email is deprecated and may not be supported in the future.", DeprecationWarning, stacklevel=2)
         if key == "email":
-            return self.email
+            return self.normalized
         if key == "email_ascii":
             return self.ascii_email
         if key == "local":
@@ -97,7 +105,7 @@ def __eq__(self, other):
         if not isinstance(other, ValidatedEmail):
             return False
         return (
-            self.email == other.email
+            self.normalized == other.normalized
             and self.local_part == other.local_part
             and self.domain == other.domain
             and getattr(self, 'ascii_email', None) == getattr(other, 'ascii_email', None)

email_validator/validate_email.py

@@ -76,7 +76,7 @@ def validate_email(
 
     # Collect return values in this instance.
     ret = ValidatedEmail()
-    ret.original_email = email
+    ret.original = email
 
     # Validate the email address's local part syntax and get a normalized form.
     # If the original address was quoted and the decoded local part is a valid
@@ -113,7 +113,7 @@ def validate_email(
         ret.ascii_domain = domain_part_info["ascii_domain"]
 
     # Construct the complete normalized form.
-    ret.email = ret.local_part + "@" + ret.domain
+    ret.normalized = ret.local_part + "@" + ret.domain
 
     # If the email address has an ASCII form, add it.
     if not ret.smtputf8:
@@ -144,20 +144,20 @@ def validate_email(
     #
     # See the length checks on the local part and the domain.
     if ret.ascii_email and len(ret.ascii_email) > EMAIL_MAX_LENGTH:
-        if ret.ascii_email == ret.email:
+        if ret.ascii_email == ret.normalized:
             reason = get_length_reason(ret.ascii_email)
-        elif len(ret.email) > EMAIL_MAX_LENGTH:
+        elif len(ret.normalized) > EMAIL_MAX_LENGTH:
             # If there are more than 254 characters, then the ASCII
             # form is definitely going to be too long.
-            reason = get_length_reason(ret.email, utf8=True)
+            reason = get_length_reason(ret.normalized, utf8=True)
         else:
             reason = "(when converted to IDNA ASCII)"
         raise EmailSyntaxError(f"The email address is too long {reason}.")
-    if len(ret.email.encode("utf8")) > EMAIL_MAX_LENGTH:
-        if len(ret.email) > EMAIL_MAX_LENGTH:
+    if len(ret.normalized.encode("utf8")) > EMAIL_MAX_LENGTH:
+        if len(ret.normalized) > EMAIL_MAX_LENGTH:
             # If there are more than 254 characters, then the UTF-8
             # encoding is definitely going to be too long.
-            reason = get_length_reason(ret.email, utf8=True)
+            reason = get_length_reason(ret.normalized, utf8=True)
         else:
             reason = "(when encoded in bytes)"
         raise EmailSyntaxError(f"The email address is too long {reason}.")

tests/test_main.py

@@ -13,7 +13,7 @@ def test_dict_accessor():
     input_email = "testaddr@example.tld"
     valid_email = validate_email(input_email, check_deliverability=False)
     assert isinstance(valid_email.as_dict(), dict)
-    assert valid_email.as_dict()["original_email"] == input_email
+    assert valid_email.as_dict()["original"] == input_email
 
 
 def test_main_single_good_input(monkeypatch, capsys):
@@ -24,7 +24,7 @@ def test_main_single_good_input(monkeypatch, capsys):
     stdout, _ = capsys.readouterr()
     output = json.loads(str(stdout))
     assert isinstance(output, dict)
-    assert validate_email(test_email, dns_resolver=RESOLVER).original_email == output["original_email"]
+    assert validate_email(test_email, dns_resolver=RESOLVER).original == output["original"]
 
 
 def test_main_single_bad_input(monkeypatch, capsys):
@@ -53,7 +53,7 @@ def test_bytes_input():
     input_email = b"testaddr@example.tld"
     valid_email = validate_email(input_email, check_deliverability=False)
     assert isinstance(valid_email.as_dict(), dict)
-    assert valid_email.as_dict()["email"] == input_email.decode("utf8")
+    assert valid_email.as_dict()["normalized"] == input_email.decode("utf8")
 
     input_email = "testaddr中example.tld".encode("utf32")
     with pytest.raises(EmailSyntaxError):