email-validator 2.1.2__tar.gz → 2.3.0__tar.gz

{email_validator-2.1.2/email_validator.egg-info → email_validator-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
-Name: email_validator
-Version: 2.1.2
+Metadata-Version: 2.4
+Name: email-validator
+Version: 2.3.0
 Summary: A robust email address syntax and deliverability validation library.
 Home-page: https://github.com/JoshData/python-email-validator
 Author: Joshua Tauberer
@@ -22,6 +22,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: dnspython>=2.0.0
 Requires-Dist: idna>=2.0.0
+Dynamic: license-file
 
 email-validator: Validate Email Addresses
 =========================================
@@ -32,30 +33,31 @@ 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:
 
 * Checks that an email address has the correct syntax --- great for
-  email-based registration/login forms or validing data.
+  email-based registration/login forms or validating data.
 * Gives friendly English error messages when validation fails that you
   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)
 
@@ -167,11 +169,14 @@ The `validate_email` function also accepts the following keyword arguments
 
 `allow_quoted_local=False`: Set to `True` to allow obscure and potentially problematic email addresses in which the part of the address before the @-sign contains spaces, @-signs, or other surprising characters when the local part is surrounded in quotes (so-called quoted-string local parts). In the object returned by `validate_email`, the normalized local part removes any unnecessary backslash-escaping and even removes the surrounding quotes if the address would be valid without them. You can also set `email_validator.ALLOW_QUOTED_LOCAL` to `True` to turn this on for all calls by default.
 
-`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_domain_literal=False`: Set to `True` to allow bracketed IPv4 and "IPv6:"-prefixed 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.
     
+`strict=False`: Set to `True` to perform additional syntax checks (currently only a local part length check). This should be used by mail service providers at address creation to ensure email addresses meet broad compatibility requirements.
 
 ### DNS timeout and cache
 
@@ -207,8 +212,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 +240,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 +263,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 +281,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 +294,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 +308,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 +327,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 +400,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. |
@@ -470,8 +451,7 @@ To release:
 * Update CHANGELOG.md.
 * Update the version number in `email_validator/version.py`.
 * Make & push a commit with the new version number and make sure tests pass.
-* Make & push a tag (see command below).
-* Make a release at https://github.com/JoshData/python-email-validator/releases/new.
+* Make a release at https://github.com/JoshData/python-email-validator/releases/new creating a new tag (or use command below).
 * Publish a source and wheel distribution to pypi (see command below).
 
 ```sh

{email_validator-2.1.2 → email_validator-2.3.0}/README.md

@@ -7,30 +7,31 @@ 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:
 
 * Checks that an email address has the correct syntax --- great for
-  email-based registration/login forms or validing data.
+  email-based registration/login forms or validating data.
 * Gives friendly English error messages when validation fails that you
   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)
 
@@ -142,11 +143,14 @@ The `validate_email` function also accepts the following keyword arguments
 
 `allow_quoted_local=False`: Set to `True` to allow obscure and potentially problematic email addresses in which the part of the address before the @-sign contains spaces, @-signs, or other surprising characters when the local part is surrounded in quotes (so-called quoted-string local parts). In the object returned by `validate_email`, the normalized local part removes any unnecessary backslash-escaping and even removes the surrounding quotes if the address would be valid without them. You can also set `email_validator.ALLOW_QUOTED_LOCAL` to `True` to turn this on for all calls by default.
 
-`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_domain_literal=False`: Set to `True` to allow bracketed IPv4 and "IPv6:"-prefixed 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.
     
+`strict=False`: Set to `True` to perform additional syntax checks (currently only a local part length check). This should be used by mail service providers at address creation to ensure email addresses meet broad compatibility requirements.
 
 ### DNS timeout and cache
 
@@ -182,8 +186,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 +214,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 +237,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 +255,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 +268,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 +282,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 +301,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 +374,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. |
@@ -445,8 +425,7 @@ To release:
 * Update CHANGELOG.md.
 * Update the version number in `email_validator/version.py`.
 * Make & push a commit with the new version number and make sure tests pass.
-* Make & push a tag (see command below).
-* Make a release at https://github.com/JoshData/python-email-validator/releases/new.
+* Make a release at https://github.com/JoshData/python-email-validator/releases/new creating a new tag (or use command below).
 * Publish a source and wheel distribution to pypi (see command below).
 
 ```sh
@@ -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.2 → email_validator-2.3.0}/email_validator/__init__.py

@@ -1,6 +1,8 @@
+from typing import TYPE_CHECKING
+
 # Export the main method, helper methods, and the public data types.
-from .exceptions_types import ValidatedEmail, EmailNotValidError, \
-                              EmailSyntaxError, EmailUndeliverableError
+from .exceptions import EmailNotValidError, EmailSyntaxError, EmailUndeliverableError
+from .types import ValidatedEmail
 from .validate_email import validate_email
 from .version import __version__
 
@@ -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
@@ -23,8 +27,11 @@ def caching_resolver(*args, **kwargs):
 # Default values for keyword arguments.
 
 ALLOW_SMTPUTF8 = True
+ALLOW_EMPTY_LOCAL = False
 ALLOW_QUOTED_LOCAL = False
 ALLOW_DOMAIN_LITERAL = False
+ALLOW_DISPLAY_NAME = False
+STRICT = False
 GLOBALLY_DELIVERABLE = True
 CHECK_DELIVERABILITY = True
 TEST_ENVIRONMENT = False

{email_validator-2.1.2 → email_validator-2.3.0}/email_validator/__main__.py

@@ -12,23 +12,25 @@
 # When using STDIN, no output will be given for valid email addresses.
 #
 # Keyword arguments to validate_email can be set in environment variables
-# of the same name but upprcase (see below).
+# of the same name but uppercase (see below).
 
 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
+from .exceptions 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 = {}
-    for varname in ('ALLOW_SMTPUTF8', 'ALLOW_QUOTED_LOCAL', 'ALLOW_DOMAIN_LITERAL',
+    options: Dict[str, Any] = {}
+    for varname in ('ALLOW_SMTPUTF8', 'ALLOW_EMPTY_LOCAL', 'ALLOW_QUOTED_LOCAL', 'ALLOW_DOMAIN_LITERAL',
+                    'ALLOW_DISPLAY_NAME',
                     'GLOBALLY_DELIVERABLE', 'CHECK_DELIVERABILITY', 'TEST_ENVIRONMENT'):
         if varname in os.environ:
             options[varname.lower()] = bool(os.environ[varname])
@@ -37,7 +39,7 @@ def main(dns_resolver=None):
             options[varname.lower()] = float(os.environ[varname])
 
     if len(sys.argv) == 1:
-        # Validate the email addresses pased line-by-line on STDIN.
+        # Validate the email addresses passed line-by-line on STDIN.
         dns_resolver = dns_resolver or caching_resolver()
         for line in sys.stdin:
             email = line.strip()

{email_validator-2.1.2 → email_validator-2.3.0}/email_validator/deliverability.py

@@ -1,24 +1,31 @@
-from typing import Optional, Any, Dict
+from typing import Any, List, Optional, Tuple, TypedDict
 
 import ipaddress
 
-from .exceptions_types import EmailUndeliverableError
+from .exceptions import EmailUndeliverableError
 
 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
@@ -36,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:
@@ -69,9 +76,9 @@ def validate_email_deliverability(domain: str, domain_i18n: str, timeout: Option
             # 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(ipaddr):
+            def is_global_addr(address: Any) -> bool:
                 try:
-                    ipaddr = ipaddress.ip_address(ipaddr)
+                    ipaddr = ipaddress.ip_address(address)
                 except ValueError:
                     return False
                 return ipaddr.is_global
@@ -115,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.3.0/email_validator/exceptions.py

@@ -0,0 +1,13 @@
+class EmailNotValidError(ValueError):
+    """Parent class of all exceptions raised by this module."""
+    pass
+
+
+class EmailSyntaxError(EmailNotValidError):
+    """Exception raised when an email address fails validation because of its form."""
+    pass
+
+
+class EmailUndeliverableError(EmailNotValidError):
+    """Exception raised when an email address fails validation because its domain name does not appear deliverable."""
+    pass