email-validator 2.1.1__tar.gz → 2.2.0__tar.gz

{email_validator-2.1.1/email_validator.egg-info → email_validator-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: email_validator
-Version: 2.1.1
+Version: 2.2.0
 Summary: A robust email address syntax and deliverability validation library.
 Home-page: https://github.com/JoshData/python-email-validator
 Author: Joshua Tauberer
@@ -32,8 +32,7 @@ Python 3.8+ by [Joshua Tauberer](https://joshdata.me).
 This library validates that a string is of the form `name@example.com`
 and optionally checks that the domain name is set up to receive email.
 This is the sort of validation you would want when you are identifying
-users by their email address like on a registration/login form (but not
-necessarily for composing an email message, see below).
+users by their email address like on a registration form.
 
 Key features:
 
@@ -43,19 +42,21 @@ Key features:
   can display to end-users.
 * Checks deliverability (optional): Does the domain name resolve?
   (You can override the default DNS resolver to add query caching.)
-* Supports internationalized domain names and internationalized local parts.
-* Rejects addresses with unsafe Unicode characters, obsolete email address
-  syntax that you'd find unexpected, special use domain names like
-  `@localhost`, and domains without a dot by default. This is an
-  opinionated library!
+* Supports internationalized domain names (like `@ツ.life`),
+  internationalized local parts (like `ツ@example.com`),
+  and optionally parses display names (e.g. `"My Name" <me@example.com>`).
+* Rejects addresses with invalid or unsafe Unicode characters,
+  obsolete email address syntax that you'd find unexpected,
+  special use domain names like `@localhost`,
+  and domains without a dot by default.
+  This is an opinionated library!
 * Normalizes email addresses (important for internationalized
   and quoted-string addresses! see below).
 * Python type annotations are used.
 
 This is an opinionated library. You should definitely also consider using
-the less-opinionated [pyIsEmail](https://github.com/michaelherold/pyIsEmail) and
-[flanker](https://github.com/mailgun/flanker) if they are better for your
-use case.
+the less-opinionated [pyIsEmail](https://github.com/michaelherold/pyIsEmail)
+if it works better for you.
 
 [![Build Status](https://github.com/JoshData/python-email-validator/actions/workflows/test_and_build.yaml/badge.svg)](https://github.com/JoshData/python-email-validator/actions/workflows/test_and_build.yaml)
 
@@ -169,6 +170,8 @@ The `validate_email` function also accepts the following keyword arguments
 
 `allow_domain_literal=False`: Set to `True` to allow bracketed IPv4 and "IPv6:"-prefixd IPv6 addresses in the domain part of the email address. No deliverability checks are performed for these addresses. In the object returned by `validate_email`, the normalized domain will use the condensed IPv6 format, if applicable. The object's `domain_address` attribute will hold the parsed `ipaddress.IPv4Address` or `ipaddress.IPv6Address` object if applicable. You can also set `email_validator.ALLOW_DOMAIN_LITERAL` to `True` to turn this on for all calls by default.
 
+`allow_display_name=False`: Set to `True` to allow a display name and bracketed address in the input string, like `My Name <me@example.org>`. It's implemented in the spirit but not the letter of RFC 5322 3.4, so it may be stricter or more relaxed than what you want. The display name, if present, is provided in the returned object's `display_name` field after being unquoted and unescaped. You can also set `email_validator.ALLOW_DISPLAY_NAME` to `True` to turn this on for all calls by default.
+
 `allow_empty_local=False`: Set to `True` to allow an empty local part (i.e.
     `@example.com`), e.g. for validating Postfix aliases.
     
@@ -207,8 +210,12 @@ Internationalized email addresses
 The email protocol SMTP and the domain name system DNS have historically
 only allowed English (ASCII) characters in email addresses and domain names,
 respectively. Each has adapted to internationalization in a separate
-way, creating two separate aspects to email address
-internationalization.
+way, creating two separate aspects to email address internationalization.
+
+(If your mail submission library doesn't support Unicode at all, then
+immediately prior to mail submission you must replace the email address with
+its ASCII-ized form. This library gives you back the ASCII-ized form in the
+`ascii_email` field in the returned object.)
 
 ### Internationalized domain names (IDN)
 
@@ -231,6 +238,19 @@ email addresses, only English letters, numbers, and some punctuation
 (`._!#$%&'^``*+-=~/?{|}`) are allowed. In internationalized email address
 local parts, a wider range of Unicode characters are allowed.
 
+Email addresses with these non-ASCII characters require that your mail
+submission library and all the mail servers along the route to the destination,
+including your own outbound mail server, all support the
+[SMTPUTF8 (RFC 6531)](https://tools.ietf.org/html/rfc6531) extension.
+Support for SMTPUTF8 varies. If you know ahead of time that SMTPUTF8 is not
+supported by your mail submission stack, then you must filter out addresses that
+require SMTPUTF8 using the `allow_smtputf8=False` keyword argument (see above).
+This will cause the validation function to raise a `EmailSyntaxError` if
+delivery would require SMTPUTF8. If you do not set `allow_smtputf8=False`,
+you can also check the value of the `smtputf8` field in the returned object.
+
+### Unsafe Unicode characters are rejected
+
 A surprisingly large number of Unicode characters are not safe to display,
 especially when the email address is concatenated with other text, so this
 library tries to protect you by not permitting reserved, non-, private use,
@@ -241,48 +261,10 @@ cannot combine with something outside of the email address string or with
 the @-sign). See https://qntm.org/safe and https://trojansource.codes/
 for relevant prior work. (Other than whitespace, these are checks that
 you should be applying to nearly all user inputs in a security-sensitive
-context.)
-
-These character checks are performed after Unicode normalization (see below),
-so you are only fully protected if you replace all user-provided email addresses
-with the normalized email address string returned by this library. This does not
-guard against the well known problem that many Unicode characters look alike
-(or are identical), which can be used to fool humans reading displayed text.
-
-Email addresses with these non-ASCII characters require that your mail
-submission library and the mail servers along the route to the destination,
-including your own outbound mail server, all support the
-[SMTPUTF8 (RFC 6531)](https://tools.ietf.org/html/rfc6531) extension.
-Support for SMTPUTF8 varies. See the `allow_smtputf8` parameter.
-
-### If you know ahead of time that SMTPUTF8 is not supported by your mail submission stack
+context.) This does not guard against the well known problem that many
+Unicode characters look alike, which can be used to fool humans reading
+displayed text.
 
-By default all internationalized forms are accepted by the validator.
-But if you know ahead of time that SMTPUTF8 is not supported by your
-mail submission stack, then you must filter out addresses that require
-SMTPUTF8 using the `allow_smtputf8=False` keyword argument (see above).
-This will cause the validation function to raise a `EmailSyntaxError` if
-delivery would require SMTPUTF8. That's just in those cases where
-non-ASCII characters appear before the @-sign. If you do not set
-`allow_smtputf8=False`, you can also check the value of the `smtputf8`
-field in the returned object.
-
-If your mail submission library doesn't support Unicode at all --- even
-in the domain part of the address --- then immediately prior to mail
-submission you must replace the email address with its ASCII-ized form.
-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
-emailinfo = validate_email(email, allow_smtputf8=False)
-email = emailinfo.ascii_email
-```
-
-The local part is left alone (if it has internationalized characters
-`allow_smtputf8=False` will force validation to fail) and the domain
-part is converted to [IDNA ASCII](https://tools.ietf.org/html/rfc5891).
-(You probably should not do this at account creation time so you don't
-change the user's login information without telling them.)
 
 Normalization
 -------------
@@ -297,7 +279,7 @@ address.
 
 For example, the CJK fullwidth Latin letters are considered semantically
 equivalent in domain names to their ASCII counterparts. This library
-normalizes them to their ASCII counterparts:
+normalizes them to their ASCII counterparts (as required by IDNA):
 
 ```python
 emailinfo = validate_email("me@Ｄｏｍａｉｎ.com")
@@ -310,9 +292,7 @@ Because an end-user might type their email address in different (but
 equivalent) un-normalized forms at different times, you ought to
 replace what they enter with the normalized form immediately prior to
 going into your database (during account creation), querying your database
-(during login), or sending outbound mail. Normalization may also change
-the length of an email address, and this may affect whether it is valid
-and acceptable by your SMTP provider.
+(during login), or sending outbound mail.
 
 The normalizations include lowercasing the domain part of the email
 address (domain names are case-insensitive), [Unicode "NFC"
@@ -326,6 +306,11 @@ in the domain part, possibly other
 [UTS46](http://unicode.org/reports/tr46) mappings on the domain part,
 and conversion from Punycode to Unicode characters.
 
+Normalization may change the characters in the email address and the
+length of the email address, such that a string might be a valid address
+before normalization but invalid after, or vice versa. This library only
+permits addresses that are valid both before and after normalization.
+
 (See [RFC 6532 (internationalized email) section
 3.1](https://tools.ietf.org/html/rfc6532#section-3.1) and [RFC 5895
 (IDNA 2008) section 2](http://www.ietf.org/rfc/rfc5895.txt).)
@@ -340,13 +325,6 @@ they are unnecessary. For IPv6 domain literals, the IPv6 address is
 normalized to condensed form. [RFC 2142](https://datatracker.ietf.org/doc/html/rfc2142)
 also requires lowercase normalization for some specific mailbox names like `postmaster@`.
 
-### Length checks
-
-This library checks that the length of the email address is not longer than
-the maximum length. The check is performed on the normalized form of the
-address, which might be different from a string provided by a user. If you
-send email to the original string and not the normalized address, the email
-might be rejected because the original address could be too long.
 
 Examples
 --------
@@ -420,6 +398,7 @@ are:
 | `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. |
 | `ascii_domain` | The [IDNA](https://tools.ietf.org/html/rfc5891) [Punycode](https://www.rfc-editor.org/rfc/rfc3492.txt)-encoded form of the domain part of the given email address, as it would be transmitted on the wire. |
 | `domain_address` | If domain literals are allowed and if the email address contains one, an `ipaddress.IPv4Address` or `ipaddress.IPv6Address` object. |
+| `display_name` | If no display name was present and angle brackets do not surround the address, this will be `None`; otherwise, it will be set to the display name, or the empty string if there were angle brackets but no display name. If the display name was quoted, it will be unquoted and unescaped. |
 | `smtputf8` | A boolean indicating that the [SMTPUTF8](https://tools.ietf.org/html/rfc6531) feature of your mail relay will be required to transmit messages to this address because the local part of the address has non-ASCII characters (the local part cannot be IDNA-encoded). If `allow_smtputf8=False` is passed as an argument, this flag will always be false because an exception is raised if it would have been true. |
 | `mx` | A list of (priority, domain) tuples of MX records specified in the DNS for the domain (see [RFC 5321 section 5](https://tools.ietf.org/html/rfc5321#section-5)). May be `None` if the deliverability check could not be completed because of a temporary issue like a timeout. |
 | `mx_fallback_type` | `None` if an `MX` record is found. 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`). May be `None` if the deliverability check could not be completed because of a temporary issue like a timeout. |

{email_validator-2.1.1 → email_validator-2.2.0}/README.md

@@ -7,8 +7,7 @@ Python 3.8+ by [Joshua Tauberer](https://joshdata.me).
 This library validates that a string is of the form `name@example.com`
 and optionally checks that the domain name is set up to receive email.
 This is the sort of validation you would want when you are identifying
-users by their email address like on a registration/login form (but not
-necessarily for composing an email message, see below).
+users by their email address like on a registration form.
 
 Key features:
 
@@ -18,19 +17,21 @@ Key features:
   can display to end-users.
 * Checks deliverability (optional): Does the domain name resolve?
   (You can override the default DNS resolver to add query caching.)
-* Supports internationalized domain names and internationalized local parts.
-* Rejects addresses with unsafe Unicode characters, obsolete email address
-  syntax that you'd find unexpected, special use domain names like
-  `@localhost`, and domains without a dot by default. This is an
-  opinionated library!
+* Supports internationalized domain names (like `@ツ.life`),
+  internationalized local parts (like `ツ@example.com`),
+  and optionally parses display names (e.g. `"My Name" <me@example.com>`).
+* Rejects addresses with invalid or unsafe Unicode characters,
+  obsolete email address syntax that you'd find unexpected,
+  special use domain names like `@localhost`,
+  and domains without a dot by default.
+  This is an opinionated library!
 * Normalizes email addresses (important for internationalized
   and quoted-string addresses! see below).
 * Python type annotations are used.
 
 This is an opinionated library. You should definitely also consider using
-the less-opinionated [pyIsEmail](https://github.com/michaelherold/pyIsEmail) and
-[flanker](https://github.com/mailgun/flanker) if they are better for your
-use case.
+the less-opinionated [pyIsEmail](https://github.com/michaelherold/pyIsEmail)
+if it works better for you.
 
 [![Build Status](https://github.com/JoshData/python-email-validator/actions/workflows/test_and_build.yaml/badge.svg)](https://github.com/JoshData/python-email-validator/actions/workflows/test_and_build.yaml)
 
@@ -144,6 +145,8 @@ The `validate_email` function also accepts the following keyword arguments
 
 `allow_domain_literal=False`: Set to `True` to allow bracketed IPv4 and "IPv6:"-prefixd IPv6 addresses in the domain part of the email address. No deliverability checks are performed for these addresses. In the object returned by `validate_email`, the normalized domain will use the condensed IPv6 format, if applicable. The object's `domain_address` attribute will hold the parsed `ipaddress.IPv4Address` or `ipaddress.IPv6Address` object if applicable. You can also set `email_validator.ALLOW_DOMAIN_LITERAL` to `True` to turn this on for all calls by default.
 
+`allow_display_name=False`: Set to `True` to allow a display name and bracketed address in the input string, like `My Name <me@example.org>`. It's implemented in the spirit but not the letter of RFC 5322 3.4, so it may be stricter or more relaxed than what you want. The display name, if present, is provided in the returned object's `display_name` field after being unquoted and unescaped. You can also set `email_validator.ALLOW_DISPLAY_NAME` to `True` to turn this on for all calls by default.
+
 `allow_empty_local=False`: Set to `True` to allow an empty local part (i.e.
     `@example.com`), e.g. for validating Postfix aliases.
     
@@ -182,8 +185,12 @@ Internationalized email addresses
 The email protocol SMTP and the domain name system DNS have historically
 only allowed English (ASCII) characters in email addresses and domain names,
 respectively. Each has adapted to internationalization in a separate
-way, creating two separate aspects to email address
-internationalization.
+way, creating two separate aspects to email address internationalization.
+
+(If your mail submission library doesn't support Unicode at all, then
+immediately prior to mail submission you must replace the email address with
+its ASCII-ized form. This library gives you back the ASCII-ized form in the
+`ascii_email` field in the returned object.)
 
 ### Internationalized domain names (IDN)
 
@@ -206,6 +213,19 @@ email addresses, only English letters, numbers, and some punctuation
 (`._!#$%&'^``*+-=~/?{|}`) are allowed. In internationalized email address
 local parts, a wider range of Unicode characters are allowed.
 
+Email addresses with these non-ASCII characters require that your mail
+submission library and all the mail servers along the route to the destination,
+including your own outbound mail server, all support the
+[SMTPUTF8 (RFC 6531)](https://tools.ietf.org/html/rfc6531) extension.
+Support for SMTPUTF8 varies. If you know ahead of time that SMTPUTF8 is not
+supported by your mail submission stack, then you must filter out addresses that
+require SMTPUTF8 using the `allow_smtputf8=False` keyword argument (see above).
+This will cause the validation function to raise a `EmailSyntaxError` if
+delivery would require SMTPUTF8. If you do not set `allow_smtputf8=False`,
+you can also check the value of the `smtputf8` field in the returned object.
+
+### Unsafe Unicode characters are rejected
+
 A surprisingly large number of Unicode characters are not safe to display,
 especially when the email address is concatenated with other text, so this
 library tries to protect you by not permitting reserved, non-, private use,
@@ -216,48 +236,10 @@ cannot combine with something outside of the email address string or with
 the @-sign). See https://qntm.org/safe and https://trojansource.codes/
 for relevant prior work. (Other than whitespace, these are checks that
 you should be applying to nearly all user inputs in a security-sensitive
-context.)
-
-These character checks are performed after Unicode normalization (see below),
-so you are only fully protected if you replace all user-provided email addresses
-with the normalized email address string returned by this library. This does not
-guard against the well known problem that many Unicode characters look alike
-(or are identical), which can be used to fool humans reading displayed text.
-
-Email addresses with these non-ASCII characters require that your mail
-submission library and the mail servers along the route to the destination,
-including your own outbound mail server, all support the
-[SMTPUTF8 (RFC 6531)](https://tools.ietf.org/html/rfc6531) extension.
-Support for SMTPUTF8 varies. See the `allow_smtputf8` parameter.
-
-### If you know ahead of time that SMTPUTF8 is not supported by your mail submission stack
+context.) This does not guard against the well known problem that many
+Unicode characters look alike, which can be used to fool humans reading
+displayed text.
 
-By default all internationalized forms are accepted by the validator.
-But if you know ahead of time that SMTPUTF8 is not supported by your
-mail submission stack, then you must filter out addresses that require
-SMTPUTF8 using the `allow_smtputf8=False` keyword argument (see above).
-This will cause the validation function to raise a `EmailSyntaxError` if
-delivery would require SMTPUTF8. That's just in those cases where
-non-ASCII characters appear before the @-sign. If you do not set
-`allow_smtputf8=False`, you can also check the value of the `smtputf8`
-field in the returned object.
-
-If your mail submission library doesn't support Unicode at all --- even
-in the domain part of the address --- then immediately prior to mail
-submission you must replace the email address with its ASCII-ized form.
-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
-emailinfo = validate_email(email, allow_smtputf8=False)
-email = emailinfo.ascii_email
-```
-
-The local part is left alone (if it has internationalized characters
-`allow_smtputf8=False` will force validation to fail) and the domain
-part is converted to [IDNA ASCII](https://tools.ietf.org/html/rfc5891).
-(You probably should not do this at account creation time so you don't
-change the user's login information without telling them.)
 
 Normalization
 -------------
@@ -272,7 +254,7 @@ address.
 
 For example, the CJK fullwidth Latin letters are considered semantically
 equivalent in domain names to their ASCII counterparts. This library
-normalizes them to their ASCII counterparts:
+normalizes them to their ASCII counterparts (as required by IDNA):
 
 ```python
 emailinfo = validate_email("me@Ｄｏｍａｉｎ.com")
@@ -285,9 +267,7 @@ Because an end-user might type their email address in different (but
 equivalent) un-normalized forms at different times, you ought to
 replace what they enter with the normalized form immediately prior to
 going into your database (during account creation), querying your database
-(during login), or sending outbound mail. Normalization may also change
-the length of an email address, and this may affect whether it is valid
-and acceptable by your SMTP provider.
+(during login), or sending outbound mail.
 
 The normalizations include lowercasing the domain part of the email
 address (domain names are case-insensitive), [Unicode "NFC"
@@ -301,6 +281,11 @@ in the domain part, possibly other
 [UTS46](http://unicode.org/reports/tr46) mappings on the domain part,
 and conversion from Punycode to Unicode characters.
 
+Normalization may change the characters in the email address and the
+length of the email address, such that a string might be a valid address
+before normalization but invalid after, or vice versa. This library only
+permits addresses that are valid both before and after normalization.
+
 (See [RFC 6532 (internationalized email) section
 3.1](https://tools.ietf.org/html/rfc6532#section-3.1) and [RFC 5895
 (IDNA 2008) section 2](http://www.ietf.org/rfc/rfc5895.txt).)
@@ -315,13 +300,6 @@ they are unnecessary. For IPv6 domain literals, the IPv6 address is
 normalized to condensed form. [RFC 2142](https://datatracker.ietf.org/doc/html/rfc2142)
 also requires lowercase normalization for some specific mailbox names like `postmaster@`.
 
-### Length checks
-
-This library checks that the length of the email address is not longer than
-the maximum length. The check is performed on the normalized form of the
-address, which might be different from a string provided by a user. If you
-send email to the original string and not the normalized address, the email
-might be rejected because the original address could be too long.
 
 Examples
 --------
@@ -395,6 +373,7 @@ are:
 | `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. |
 | `ascii_domain` | The [IDNA](https://tools.ietf.org/html/rfc5891) [Punycode](https://www.rfc-editor.org/rfc/rfc3492.txt)-encoded form of the domain part of the given email address, as it would be transmitted on the wire. |
 | `domain_address` | If domain literals are allowed and if the email address contains one, an `ipaddress.IPv4Address` or `ipaddress.IPv6Address` object. |
+| `display_name` | If no display name was present and angle brackets do not surround the address, this will be `None`; otherwise, it will be set to the display name, or the empty string if there were angle brackets but no display name. If the display name was quoted, it will be unquoted and unescaped. |
 | `smtputf8` | A boolean indicating that the [SMTPUTF8](https://tools.ietf.org/html/rfc6531) feature of your mail relay will be required to transmit messages to this address because the local part of the address has non-ASCII characters (the local part cannot be IDNA-encoded). If `allow_smtputf8=False` is passed as an argument, this flag will always be false because an exception is raised if it would have been true. |
 | `mx` | A list of (priority, domain) tuples of MX records specified in the DNS for the domain (see [RFC 5321 section 5](https://tools.ietf.org/html/rfc5321#section-5)). May be `None` if the deliverability check could not be completed because of a temporary issue like a timeout. |
 | `mx_fallback_type` | `None` if an `MX` record is found. 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`). May be `None` if the deliverability check could not be completed because of a temporary issue like a timeout. |
@@ -458,4 +437,4 @@ git push --tags
 License
 -------
 
-This project is free of any copyright restrictions per the [Unlicense](https://unlicense.org/). (Prior to Feb. 4, 2024, the project was made available under the terms of the [CC0 1.0 Universal public domain dedication](http://creativecommons.org/publicdomain/zero/1.0/).) See [LICENSE](LICENSE) and [CONTRIBUTING.md](CONTRIBUTING.md).
+This project is free of any copyright restrictions per the [Unlicense](https://unlicense.org/). (Prior to Feb. 4, 2024, the project was made available under the terms of the [CC0 1.0 Universal public domain dedication](http://creativecommons.org/publicdomain/zero/1.0/).) See [LICENSE](LICENSE) and [CONTRIBUTING.md](CONTRIBUTING.md).

{email_validator-2.1.1 → email_validator-2.2.0}/email_validator/__init__.py

@@ -1,3 +1,5 @@
+from typing import TYPE_CHECKING
+
 # Export the main method, helper methods, and the public data types.
 from .exceptions_types import ValidatedEmail, EmailNotValidError, \
                               EmailSyntaxError, EmailUndeliverableError
@@ -9,12 +11,14 @@ __all__ = ["validate_email",
            "EmailSyntaxError", "EmailUndeliverableError",
            "caching_resolver", "__version__"]
 
-
-def caching_resolver(*args, **kwargs):
-    # Lazy load `deliverability` as it is slow to import (due to dns.resolver)
+if TYPE_CHECKING:
     from .deliverability import caching_resolver
+else:
+    def caching_resolver(*args, **kwargs):
+        # Lazy load `deliverability` as it is slow to import (due to dns.resolver)
+        from .deliverability import caching_resolver
 
-    return caching_resolver(*args, **kwargs)
+        return caching_resolver(*args, **kwargs)
 
 
 # These global attributes are a part of the library's API and can be
@@ -25,6 +29,7 @@ def caching_resolver(*args, **kwargs):
 ALLOW_SMTPUTF8 = True
 ALLOW_QUOTED_LOCAL = False
 ALLOW_DOMAIN_LITERAL = False
+ALLOW_DISPLAY_NAME = False
 GLOBALLY_DELIVERABLE = True
 CHECK_DELIVERABILITY = True
 TEST_ENVIRONMENT = False

{email_validator-2.1.1 → email_validator-2.2.0}/email_validator/__main__.py

@@ -17,17 +17,18 @@
 import json
 import os
 import sys
+from typing import Any, Dict, Optional
 
-from .validate_email import validate_email
+from .validate_email import validate_email, _Resolver
 from .deliverability import caching_resolver
 from .exceptions_types import EmailNotValidError
 
 
-def main(dns_resolver=None):
+def main(dns_resolver: Optional[_Resolver] = None) -> None:
     # The dns_resolver argument is for tests.
 
     # Set options from environment variables.
-    options = {}
+    options: Dict[str, Any] = {}
     for varname in ('ALLOW_SMTPUTF8', 'ALLOW_QUOTED_LOCAL', 'ALLOW_DOMAIN_LITERAL',
                     'GLOBALLY_DELIVERABLE', 'CHECK_DELIVERABILITY', 'TEST_ENVIRONMENT'):
         if varname in os.environ:

{email_validator-2.1.1 → email_validator-2.2.0}/email_validator/deliverability.py

@@ -1,4 +1,6 @@
-from typing import Optional, Any, Dict
+from typing import Any, List, Optional, Tuple, TypedDict
+
+import ipaddress
 
 from .exceptions_types import EmailUndeliverableError
 
@@ -6,17 +8,24 @@ import dns.resolver
 import dns.exception
 
 
-def caching_resolver(*, timeout: Optional[int] = None, cache=None, dns_resolver=None):
+def caching_resolver(*, timeout: Optional[int] = None, cache: Any = None, dns_resolver: Optional[dns.resolver.Resolver] = None) -> dns.resolver.Resolver:
     if timeout is None:
         from . import DEFAULT_TIMEOUT
         timeout = DEFAULT_TIMEOUT
     resolver = dns_resolver or dns.resolver.Resolver()
-    resolver.cache = cache or dns.resolver.LRUCache()  # type: ignore
-    resolver.lifetime = timeout  # type: ignore # timeout, in seconds
+    resolver.cache = cache or dns.resolver.LRUCache()
+    resolver.lifetime = timeout  # timeout, in seconds
     return resolver
 
 
-def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Optional[int] = None, dns_resolver=None):
+DeliverabilityInfo = TypedDict("DeliverabilityInfo", {
+    "mx": List[Tuple[int, str]],
+    "mx_fallback_type": Optional[str],
+    "unknown-deliverability": str,
+}, total=False)
+
+
+def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Optional[int] = None, dns_resolver: Optional[dns.resolver.Resolver] = None) -> DeliverabilityInfo:
     # 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
@@ -34,7 +43,7 @@ def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Option
     elif timeout is not None:
         raise ValueError("It's not valid to pass both timeout and dns_resolver.")
 
-    deliverability_info: Dict[str, Any] = {}
+    deliverability_info: DeliverabilityInfo = {}
 
     try:
         try:
@@ -57,10 +66,30 @@ def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Option
             deliverability_info["mx_fallback_type"] = None
 
         except dns.resolver.NoAnswer:
-            # If there was no MX record, fall back to an A record. (RFC 5321 Section 5)
+            # If there was no MX record, fall back to an A or AAA record
+            # (RFC 5321 Section 5). Check A first since it's more common.
+
+            # If the A/AAAA response has no Globally Reachable IP address,
+            # treat the response as if it were NoAnswer, i.e., the following
+            # address types are not allowed fallbacks: Private-Use, Loopback,
+            # Link-Local, and some other obscure ranges. See
+            # https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
+            # https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
+            # (Issue #134.)
+            def is_global_addr(address: Any) -> bool:
+                try:
+                    ipaddr = ipaddress.ip_address(address)
+                except ValueError:
+                    return False
+                return ipaddr.is_global
+
             try:
                 response = dns_resolver.resolve(domain, "A")
-                deliverability_info["mx"] = [(0, str(r)) for r in response]
+
+                if not any(is_global_addr(r.address) for r in response):
+                    raise dns.resolver.NoAnswer  # fall back to AAAA
+
+                deliverability_info["mx"] = [(0, domain)]
                 deliverability_info["mx_fallback_type"] = "A"
 
             except dns.resolver.NoAnswer:
@@ -69,7 +98,11 @@ def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Option
                 # (It's unclear if SMTP servers actually do this.)
                 try:
                     response = dns_resolver.resolve(domain, "AAAA")
-                    deliverability_info["mx"] = [(0, str(r)) for r in response]
+
+                    if not any(is_global_addr(r.address) for r in response):
+                        raise dns.resolver.NoAnswer
+
+                    deliverability_info["mx"] = [(0, domain)]
                     deliverability_info["mx_fallback_type"] = "AAAA"
 
                 except dns.resolver.NoAnswer as e:
@@ -89,7 +122,6 @@ def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Option
                 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(f"The domain name {domain_i18n} does not send email.")
             except dns.resolver.NoAnswer:

{email_validator-2.1.1 → email_validator-2.2.0}/email_validator/exceptions_types.py

@@ -1,5 +1,5 @@
 import warnings
-from typing import Optional
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 
 class EmailNotValidError(ValueError):
@@ -24,7 +24,7 @@ class ValidatedEmail:
     """The email address that was passed to validate_email. (If passed as bytes, this will be a string.)"""
     original: str
 
-    """The normalized email address, which should always be used in preferance to the original address.
+    """The normalized email address, which should always be used in preference 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."""
@@ -56,22 +56,20 @@ class ValidatedEmail:
 
     """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: list
+    mx: List[Tuple[int, str]]
 
     """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: str
+    mx_fallback_type: Optional[str]
 
-    """Tests use this constructor."""
-    def __init__(self, **kwargs):
-        for k, v in kwargs.items():
-            setattr(self, k, v)
+    """The display name in the original input text, unquoted and unescaped, or None."""
+    display_name: Optional[str]
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<ValidatedEmail {self.normalized}>"
 
     """For backwards compatibility, support old field names."""
-    def __getattr__(self, key):
+    def __getattr__(self, key: str) -> str:
         if key == "original_email":
             return self.original
         if key == "email":
@@ -79,13 +77,13 @@ class ValidatedEmail:
         raise AttributeError(key)
 
     @property
-    def email(self):
+    def email(self) -> str:
         warnings.warn("ValidatedEmail.email is deprecated and will be removed, use ValidatedEmail.normalized instead", DeprecationWarning)
         return self.normalized
 
     """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):
+    def __getitem__(self, key: str) -> Union[Optional[str], bool, List[Tuple[int, str]]]:
         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.normalized
@@ -106,7 +104,7 @@ class ValidatedEmail:
         raise KeyError()
 
     """Tests use this."""
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, ValidatedEmail):
             return False
         return (
@@ -120,21 +118,23 @@ class ValidatedEmail:
             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)
+            and getattr(self, 'display_name', None) == getattr(other, 'display_name', None)
         )
 
     """This helps producing the README."""
-    def as_constructor(self):
+    def as_constructor(self) -> str:
         return "ValidatedEmail(" \
             + ",".join(f"\n  {key}={repr(getattr(self, key))}"
                        for key in ('normalized', 'local_part', 'domain',
                                    'ascii_email', 'ascii_local_part', 'ascii_domain',
-                                   'smtputf8', 'mx', 'mx_fallback_type')
+                                   'smtputf8', 'mx', 'mx_fallback_type',
+                                   'display_name')
                        if hasattr(self, key)
                        ) \
             + ")"
 
     """Convenience method for accessing ValidatedEmail as a dict"""
-    def as_dict(self):
+    def as_dict(self) -> Dict[str, Any]:
         d = self.__dict__
         if d.get('domain_address'):
             d['domain_address'] = repr(d['domain_address'])