Coverage for postrfp/mail/protocol.py: 100%

1""" 

2Mailer Protocol Interface 

3 

4Defines the contract that all mailer implementations must follow. 

5This protocol can be implemented by a module or a class. 

6This replaces the current implicit duck typing with explicit type safety. 

7""" 

8 

9from typing import Protocol, runtime_checkable, Union, TYPE_CHECKING 

10 

11if TYPE_CHECKING: 

12 from postrfp.mail.schemas import TemplateEmailModel, SimpleEmailModel 

13 

14 

15@runtime_checkable 

16class MailerProtocol(Protocol): 

17 """ 

18 Protocol defining the interface for email delivery implementations. 

19 

20 All mailer implementations (stub, postmark, etc.) must implement this interface. 

21 This provides type safety while allowing different implementation strategies. 

22 """ 

23 

24 def send_email(self, model: Union["TemplateEmailModel", "SimpleEmailModel"]) -> str: 

25 """ 

26 Send an email using the provided Pydantic model. 

27 

28 Args: 

29 model: Email data Pydantic model - either TemplateEmailModel for event 

30 notifications or SimpleEmailModel for basic messages. 

31 

32 Returns: 

33 str: Message ID from the email provider (UUID for stub, MessageID from Postmark) 

34 

35 Raises: 

36 Exception: If email sending fails for any reason 

37 """ 

38 ...