Export Sender

CHANGELOG.md

@@ -1,6 +1,7 @@
 v0.2.0 (in development)
 -----------------------
 - Require the `port` field of `SMTPSender` to be non-negative
+- Mark `Sender` as `runtime_checkable` and export it
 
 v0.1.0 (2021-03-06)
 -------------------

docs/pyapi.rst

@@ -22,17 +22,12 @@ examples.
 Sender Objects
 --------------
 
-Sender objects support, at minimum, the following protocol:
+.. autoclass:: Sender()
+    :special-members: __enter__, __exit__
 
-- They can be used as context managers, and their ``__enter__`` methods return
-  ``self``.
-
-- Within its own context, calling a sender's ``send(msg:
-  email.message.EmailMessage)`` method sends the given e-mail.
-
-In addition, ``outgoing``'s built-in senders are reentrant__ and reusable__ as
-context managers, and their ``send()`` methods can be called outside of a
-context.
+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.
 
 __ https://docs.python.org/3/library/contextlib.html#reentrant-context-managers
 __ https://docs.python.org/3/library/contextlib.html#reusable-context-managers

src/outgoing/__init__.py

@@ -29,6 +29,7 @@
 )
 from .core import (
     DEFAULT_CONFIG_SECTION,
+    Sender,
     from_config_file,
     from_dict,
     get_default_configpath,
@@ -57,6 +58,7 @@
     "OpenClosable",
     "Password",
     "Path",
+    "Sender",
     "StandardPassword",
     "from_config_file",
     "from_dict",

src/outgoing/core.py

@@ -15,9 +15,9 @@
 from .util import AnyPath
 
 if sys.version_info[:2] >= (3, 8):
-    from typing import Protocol
+    from typing import Protocol, runtime_checkable
 else:
-    from typing_extensions import Protocol
+    from typing_extensions import Protocol, runtime_checkable
 
 DEFAULT_CONFIG_SECTION = "outgoing"
 
@@ -28,7 +28,19 @@
 S = TypeVar("S", bound="Sender")
 
 
+@runtime_checkable
 class Sender(Protocol):
+    """
+    `Sender` is a `~typing.Protocol` implemented by sender objects.  The
+    protocol requires the following behavior:
+
+    - Sender objects can be used as context managers, and their ``__enter__``
+      methods return ``self``.
+
+    - Within its own context, calling a sender's ``send(msg:
+      email.message.EmailMessage)`` method sends the given e-mail.
+    """
+
     def __enter__(self: S) -> S:
         ...
 
@@ -41,6 +53,7 @@ def __exit__(
         ...
 
     def send(self, msg: EmailMessage) -> Any:
+        """ Send ``msg`` or raise an exception if that's not possible """
         ...
 
 

test/test_senders/test_babyl.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 from mailbits import email2dict
 import pytest
-from outgoing import from_dict
+from outgoing import Sender, from_dict
 from outgoing.senders.mailboxes import BabylSender
 
 
@@ -16,6 +16,7 @@ def test_babyl_construct(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Non
         },
         configpath=str(tmp_path / "foo.txt"),
     )
+    assert isinstance(sender, Sender)
     assert isinstance(sender, BabylSender)
     assert sender.dict() == {
         "configpath": tmp_path / "foo.txt",

test/test_senders/test_command.py

@@ -4,12 +4,13 @@
 from typing import List, Union
 import pytest
 from pytest_mock import MockerFixture
-from outgoing import from_dict
+from outgoing import Sender, from_dict
 from outgoing.senders.command import CommandSender
 
 
 def test_command_construct_default(tmp_path: Path) -> None:
     sender = from_dict({"method": "command"}, configpath=tmp_path / "foo.toml")
+    assert isinstance(sender, Sender)
     assert isinstance(sender, CommandSender)
     assert sender.dict() == {
         "configpath": tmp_path / "foo.toml",

test/test_senders/test_maildir.py

@@ -5,7 +5,7 @@
 from typing import Optional
 from mailbits import email2dict
 import pytest
-from outgoing import from_dict
+from outgoing import Sender, from_dict
 from outgoing.senders.mailboxes import MaildirSender
 
 
@@ -22,6 +22,7 @@ def test_maildir_construct(
         },
         configpath=str(tmp_path / "foo.txt"),
     )
+    assert isinstance(sender, Sender)
     assert isinstance(sender, MaildirSender)
     assert sender.dict() == {
         "configpath": tmp_path / "foo.txt",

test/test_senders/test_mbox.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 from mailbits import email2dict
 import pytest
-from outgoing import from_dict
+from outgoing import Sender, from_dict
 from outgoing.senders.mailboxes import MboxSender
 
 
@@ -16,6 +16,7 @@ def test_mbox_construct(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None
         },
         configpath=str(tmp_path / "foo.txt"),
     )
+    assert isinstance(sender, Sender)
     assert isinstance(sender, MboxSender)
     assert sender.dict() == {
         "configpath": tmp_path / "foo.txt",

test/test_senders/test_mh.py

@@ -5,7 +5,7 @@
 from typing import List, Union
 from mailbits import email2dict
 import pytest
-from outgoing import from_dict
+from outgoing import Sender, from_dict
 from outgoing.senders.mailboxes import MHSender
 
 
@@ -22,6 +22,7 @@ def test_mh_construct(
         },
         configpath=str(tmp_path / "foo.txt"),
     )
+    assert isinstance(sender, Sender)
     assert isinstance(sender, MHSender)
     assert sender.dict() == {
         "configpath": tmp_path / "foo.txt",

test/test_senders/test_mmdf.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 from mailbits import email2dict
 import pytest
-from outgoing import from_dict
+from outgoing import Sender, from_dict
 from outgoing.senders.mailboxes import MMDFSender
 
 
@@ -16,6 +16,7 @@ def test_mmdf_construct(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None
         },
         configpath=str(tmp_path / "foo.txt"),
     )
+    assert isinstance(sender, Sender)
     assert isinstance(sender, MMDFSender)
     assert sender.dict() == {
         "configpath": tmp_path / "foo.txt",

test/test_senders/test_smtp.py

@@ -7,7 +7,7 @@
 import pytest
 from pytest_mock import MockerFixture
 from smtpdfix import SMTPDFix
-from outgoing import from_dict
+from outgoing import Sender, from_dict
 from outgoing.errors import InvalidConfigError
 from outgoing.senders.smtp import SMTPSender
 
@@ -33,6 +33,7 @@ def test_smtp_construct_default_ssl(
         },
         configpath=str(tmp_path / "foo.txt"),
     )
+    assert isinstance(sender, Sender)
     assert isinstance(sender, SMTPSender)
     assert sender.dict() == {
         "configpath": tmp_path / "foo.txt",