Core Python API
Functions
outgoing
provides the following functions for constructing e-mail sender
objects. Once you have a sender object, simply use it in a context manager to
open it up, and then call its send()
method with each
email.message.EmailMessage
object you want to send. See Examples for
examples.
- outgoing.from_config_file(path: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]] = None, section: Optional[str] = 'outgoing', fallback: bool = True) outgoing.core.Sender [source]
Read configuration from the table/field
section
(default “outgoing
”) in the file atpath
(default: the path returned byget_default_configpath()
) and construct a sender object from the specification. The file may be either TOML or JSON (type detected based on file extension). Ifsection
isNone
, the entire file, rather than only a single field, is used as the configuration. Iffallback
is true, the file is not the default config file, and the file either does not exist or does not contain the given section, fall back to reading from the default section of the default config file.- Raises
InvalidConfigError – if the configuration is invalid
MissingConfigError – if no configuration file or section is present
- outgoing.from_dict(data: Mapping[str, Any], configpath: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]] = None) outgoing.core.Sender [source]
Construct a sender object using the given
data
as the configuration. Ifconfigpath
is given, any paths in thedata
will be resolved relative toconfigpath
’s parent directory; otherwise, they will be resolved relative to the current directory.data
should not contain a"configpath"
key; such an entry will be discarded.- Raises
InvalidConfigError – if the configuration is invalid
- outgoing.get_default_configpath() pathlib.Path [source]
Returns the location of the default config file (regardless of whether it exists) as a
pathlib.Path
object
Sender Objects
- class outgoing.Sender[source]
Sender
is aProtocol
implemented by sender objects. The protocol requires the following behavior:Sender objects can be used as context managers, and their
__enter__
methods returnself
.Within its own context, calling a sender’s
send(msg: email.message.EmailMessage)
method sends the given e-mail.
- __exit__(exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[types.TracebackType]) Optional[bool] [source]
- send(msg: email.message.EmailMessage) Any [source]
Send
msg
or raise an exception if that’s not possible
In addition to the base protocol, outgoing
’s built-in senders are
reentrant and reusable as context managers, and their send()
methods
can be called outside of a context.
Exceptions
- exception outgoing.Error[source]
Bases:
Exception
The superclass for all exceptions raised by
outgoing
- exception outgoing.InvalidConfigError(details: str, configpath: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]] = None)[source]
Bases:
outgoing.errors.Error
Raised on encountering an invalid configuration structure
- configpath: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]]
The path to the config file containing the invalid configuration
- exception outgoing.InvalidPasswordError(details: str, configpath: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]] = None)[source]
Bases:
outgoing.errors.InvalidConfigError
Raised on encountering an invalid password specifier or when no password can be determined from a specifier
- configpath: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]]
The path to the config file containing the invalid configuration
- exception outgoing.MissingConfigError(configpaths: Sequence[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]])[source]
Bases:
outgoing.errors.Error
Raised when no configuration section can be found in any config files
- configpaths: List[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]]
Paths to the configfiles searched for configuration
- exception outgoing.NetrcLookupError[source]
Bases:
outgoing.errors.Error
Raised by
lookup_netrc()
on failure to find a match in a netrc file
- exception outgoing.UnsupportedEmailError[source]
Bases:
outgoing.errors.Error
Raised by sender objects when asked to send an e-mail that uses features or constructs that the sending method does not support