Generate valid email addresses for Gmail

valid_email_gen.py

"""Generate email addresses from an email address.

In theory, email addresses containing symbols should be valid by the RFC standard, but many services
restrict the allowable symbols in the name portion. Certain services will allow special chars, in
some cases even viewing addresses with chars interpolated in the local section to be the same as
the address without those interpolated chars.

Example:
    >>> email = 'tester@gmail.com'
    >>> allowable_chars = ['.', '_']
    >>> emails = [email for email in generate_email_addrs(email, allowable_chars)]
    ['tester@gmail.com', 'teste.r@gmail.com', 'test.e.r@gmail.com, ...
     'teste_r@gmail.com', ...]

    Produces all combinations (with repitition) of tester@gmail.com with the allowable chars
    interpolated between each character of the address's local portion.

Use Cases:
    Bypassing registration for websites.
        For example, Gmail views email addresses with '.' symbols in between the local portion to be
        the same as the original email address without the '.' symbols. Many websites will do very
        basic validation, Gmail will still say that an email address 'te#s^t!e*r@gmail.com is in
        valid format, even though you cannot create an account with those symbols.

"""

from itertools import combinations_with_replacement
from typing import Iterator, List, Any


def generate_email_addrs(email: str, allowable_chars: List[str]):
    """
    """
    email_fmt = _format_email_str(email)
    for email in _generate_interpolated_str(email, allowable_chars):
        yield email


def _format_email_str(email: str) -> str:
    """Formats an email address into an address that can be interpolated with chars.

    Args:
        email: Valid email address.

    Returns:
        Email address format string where the local portion can be interpolated with values.

    Example:
        >>> email = 'tester@gmail.com'
        >>> _format_email_str(email)
        't{}e{}s{}t{}e{}r@gmail.com'

    """
    local, domain = email.split('@')
    email_fmt_str = '{}'.join(list(local))
    return email_fmt_str + '@' + domain


def _generate_interpolated_str(format_str: str, values: List[Any]) -> Iterator[str]:
    """Interpolate combinations of values into a format string.

    The provided values are injected into the format string, up to a certain amount.

    Args:
        format_str: The format string.
        items: A list of items.

    Yields:
        The next interpolated string.

    Example:
        >>> format_str = a{}b{}c@domain.com
        >>> values = ['1', '2']
        >>> for istring in _generate_interpolated_str(format_str, values):
        >>>     print(istring)
        a1bc@domain.com
        ab1c@domain.com
        a1b1c@domain.com
        a2bc@domain.com
        ab2c@domain.com
        a2b2c@domain.com
        a1b2c@domain.com
        a2b1c@domain.com

        Generates all combinations of the a string with the values interpolated into the format
        string, with repetition.

    """
    inject_count = format_str.count("{}")
    for combination in combinations_with_replacement(values, inject_count):
        yield format_str.format(*combination)