Added more docs

Author: cubicbyte

tempmail/providers.py

@@ -13,34 +13,43 @@
 class OneSecMail:
     """1secmail.com API wrapper"""
 
-    def __init__(self, email: str | None = None, username: str | None = None, domain: str | None = None) -> None:
-        if email is not None:
-            username, domain = email.split('@')
+    def __init__(self, address: str | None = None, username: str | None = None, domain: str | None = None) -> None:
+        """Create a new 1secmail.com email address
+
+        :param address: The full email address (username@domain)
+        :param username: The username of the email address (before the @)
+        :param domain: The domain of the email address (after the @)
+        """
+
+        if address is not None:
+            username, domain = address.split('@')
 
         if domain is not None and domain not in self.get_domains():
             raise ValueError(f'Invalid domain: {domain}')
 
-        self.session = requests.Session()
+        self._session = requests.Session()
         self.username = username or utils.random_string(10)
+        """The username of the email address (before the @)"""
         self.domain = domain or random.choice(self.get_domains())
+        """The domain of the email address (after the @)"""
 
     def get_inbox(self) -> list['OneSecMail.MessageInfo']:
         """Get the inbox of the email address"""
-        resp = self.session.get(f'https://www.1secmail.com/api/v1/?action=getMessages&login={self.username}&domain={self.domain}')
+        resp = self._session.get(f'https://www.1secmail.com/api/v1/?action=getMessages&login={self.username}&domain={self.domain}')
         resp.raise_for_status()
         return [OneSecMail.MessageInfo.from_dict(self, msg_info) for msg_info in resp.json()]
 
     @utils.cache
     def get_message(self, id: int) -> 'OneSecMail.Message':
         """Get a message from the inbox"""
-        resp = self.session.get(f'https://www.1secmail.com/api/v1/?action=readMessage&login={self.username}&domain={self.domain}&id={id}')
+        resp = self._session.get(f'https://www.1secmail.com/api/v1/?action=readMessage&login={self.username}&domain={self.domain}&id={id}')
         resp.raise_for_status()
         return OneSecMail.Message.from_dict(self, resp.json())
 
     @utils.cache
     def download_attachment(self, id: int, file: str) -> bytes:
         """Download an attachment from a message as bytes"""
-        resp = self.session.get(f'https://www.1secmail.com/api/v1/?action=download&login={self.username}&domain={self.domain}&id={id}&file={file}')
+        resp = self._session.get(f'https://www.1secmail.com/api/v1/?action=download&login={self.username}&domain={self.domain}&id={id}&file={file}')
         resp.raise_for_status()
         return resp.content
 
@@ -83,24 +92,33 @@ def __str__(self) -> str:
 
     @dataclass
     class MessageInfo:
+        """Information about a message in the inbox"""
+
         id: int
+        "Message ID"
         from_addr: str
+        "Sender email address"
         subject: str
+        "Subject of the message"
         date_str: str
-        _mail: 'OneSecMail'
+        "Date the message was received in format YYYY-MM-DD HH:MM:SS"
+        _mail_instance: 'OneSecMail'
 
         @property
         def date(self) -> datetime:
+            """Date the message was received"""
             return datetime.fromisoformat(self.date_str)
 
         @property
         def message(self) -> 'OneSecMail.Message':
-            return self._mail.get_message(self.id)
+            """The full message"""
+            return self._mail_instance.get_message(self.id)
 
         @classmethod
-        def from_dict(cls, mail: 'OneSecMail', msg_info: dict[str, any]) -> 'OneSecMail.MessageInfo':
+        def from_dict(cls, mail_instance: 'OneSecMail', msg_info: dict[str, any]) -> 'OneSecMail.MessageInfo':
+            """Create a MessageInfo from a raw api response"""
             return cls(
-                _mail=mail,
+                _mail_instance=mail_instance,
                 id=msg_info['id'],
                 from_addr=msg_info['from'],
                 subject=msg_info['subject'],
@@ -109,28 +127,40 @@ def from_dict(cls, mail: 'OneSecMail', msg_info: dict[str, any]) -> 'OneSecMail.
 
     @dataclass
     class Message:
+        """Email message"""
+
         id: int
+        "Message ID"
         from_addr: str
+        "Sender email address"
         subject: str
+        "Subject of the message"
         date_str: str
+        "Date the message was received in format YYYY-MM-DD HH:MM:SS"
         body: str
+        "Message body (html if exists, text otherwise)"
         text_body: str
+        "Message body (text format)"
         html_body: str
-        _mail: 'OneSecMail'
+        "Message body (html format)"
+        _mail_instance: 'OneSecMail'
         _attachments: list[dict[str, any]]
 
         @property
         def date(self) -> datetime:
+            """Date the message was received"""
             return datetime.fromisoformat(self.date_str)
 
         @property
         def attachments(self) -> list['OneSecMail.Attachment']:
-            return [OneSecMail.Attachment.from_dict(self._mail, self.id, attachment) for attachment in self._attachments]
+            """List of attachments in the message (files)"""
+            return [OneSecMail.Attachment.from_dict(self._mail_instance, self.id, attachment) for attachment in self._attachments]
 
         @classmethod
-        def from_dict(cls, mail: 'OneSecMail', msg: dict[str, any]) -> 'OneSecMail.Message':
+        def from_dict(cls, mail_instance: 'OneSecMail', msg: dict[str, any]) -> 'OneSecMail.Message':
+            """Create a Message from a raw api response"""
             return cls(
-                _mail=mail,
+                _mail_instance=mail_instance,
                 _attachments=msg['attachments'],
                 id=msg['id'],
                 from_addr=msg['from'],
@@ -143,20 +173,26 @@ def from_dict(cls, mail: 'OneSecMail', msg: dict[str, any]) -> 'OneSecMail.Messa
 
     @dataclass
     class Attachment:
+        """Email attachment"""
+
         filename: str
+        "Name of the file of the attachment"
         content_type: str
+        "MIME type of the attachment"
         size: int
-        _mail: 'OneSecMail'
+        "Size of the attachment in bytes"
+        _mail_instance: 'OneSecMail'
         _message_id: int
 
         def download(self) -> bytes:
             """Download the attachment as bytes"""
-            return self._mail.download_attachment(self._message_id, self.filename)
+            return self._mail_instance.download_attachment(self._message_id, self.filename)
 
         @classmethod
-        def from_dict(cls, mail: 'OneSecMail', message_id: int, attachment: dict[str, any]) -> 'OneSecMail.Attachment':
+        def from_dict(cls, mail_instance: 'OneSecMail', message_id: int, attachment: dict[str, any]) -> 'OneSecMail.Attachment':
+            """Create an Attachment from a raw api response"""
             return cls(
-                _mail=mail,
+                _mail_instance=mail_instance,
                 _message_id=message_id,
                 filename=attachment['filename'],
                 content_type=attachment['contentType'],