Pulls an environment variable out of the environment and parses it to a
    ``datetime.datetime`` object. The environment variable is expected to be an
    iso8601 formatted string.

    If the name is not present in the environment and no default is specified
    then a ``ValueError`` will be raised.

    :param name: The name of the environment variable be pulled
    :type name: str

    :param required: Whether the environment variable is required. If ``True``
    and the variable is not present, a ``KeyError`` is raised.
    :type required: bool

    :param default: The value to return if the environment variable is not
    present. (Providing a default alongside setting ``required=True`` will raise
    a ``ValueError``)
    :type default: bool

def env_iso8601(name, required=False, default=empty):
    """Pulls an environment variable out of the environment and parses it to a
    ``datetime.datetime`` object. The environment variable is expected to be an
    iso8601 formatted string.

    If the name is not present in the environment and no default is specified
    then a ``ValueError`` will be raised.

    :param name: The name of the environment variable be pulled
    :type name: str

    :param required: Whether the environment variable is required. If ``True``
    and the variable is not present, a ``KeyError`` is raised.
    :type required: bool

    :param default: The value to return if the environment variable is not
    present. (Providing a default alongside setting ``required=True`` will raise
    a ``ValueError``)
    :type default: bool
    """
    try:
        import iso8601
    except ImportError:
        raise ImportError(
            'Parsing iso8601 datetime strings requires the iso8601 library'
        )

    if required and default is not empty:
        raise ValueError("Using `default` with `required=True` is invalid")

    value = get_env_value(name, required=required, default=empty)
    # change datetime.datetime to time, return time.struct_time type
    if default is not empty and value is empty:
        return default
    if value is empty:
        raise ValueError(
            "`env_iso8601` requires either a default value to be specified, or "
            "for the variable to be present in the environment"
        )
    return iso8601.parse_date(value)