diff --git a/README.md b/README.md index 44e07c2..02fef04 100644 --- a/README.md +++ b/README.md @@ -21,43 +21,75 @@ Copy the `micromail.py` file to your device. You will need to install the `datet ### Class MicromailClient -`class micromail.MicromailClient(host: str, port: int, ssl: bool=False, starttls: bool=False)` -: Create a new SMTP client. +- `class micromail.MicromailClient(host: str, port: int = 0, ssl: bool = False, starttls: bool = False)` -`MicromailClient.connect()` -: Establish a connection to the SMTP server. The connection is kept alive until `MicromailClient.quit()` is called. + Create a new SMTP client. -`MicromailClient.login(username: str, password: str)` -: Login to the SMTP server with the provided username and password. `PLAIN` and `LOGIN` authentication methods are currently supported. +- `MicromailClient.connect()` -`MicromailClient.write(data: bytearray)` -: Write `data` of type `bytearray` on the server. -`MicromailClient.send_command(*cmd: bytearray) -> code: bytearray, response: list[bytearray]` -: Send command to the SMTP server; returns status code and response. + Establish a connection to the SMTP server. The connection is kept alive until `MicromailClient.quit()` is called. -`MicromailClient.ehlo() -> res: list[bytearray]` -: Send SMTP EHLO command to the server and return response. +- `MicromailClient.login(username: str, password: str)` -`MicromailClient.starttls()` -: Send SMTP STARTTLS command and enable SSL on socket. + Login to the SMTP server with the provided username and password. `PLAIN` and `LOGIN` authentication methods are currently supported. -`MicromailClient.new_message(to: str|list[str], sender: None|str=None)` -: Create a new email; sender defaults to username. +- `MicromailClient.write(data: str | bytes)` -`MicromailClient.headers(headers:dict={})` -: Define email headers; supported headers are `date` (`str|datetime`, defaults to `datetime.now()`), `from` (`str`, defaults to `new_message` `sender`), `to` (`str|list[str]`, defaults to `new_message` `to`), `subject` (`str`). + Write `data` of type `bytearray` on the server. -`MicromailClient.write_line(content:str|bytearray)` -: Write message line; `\r\n` is appended to `content`. +- `MicromailClient.send_command(*cmd: str | bytes, code: int | list[int] = []) -> tuple[int, list[str]]` -`MicromailClient.send()` -: Send current email. + Send command to the SMTP server; returns status code and list of response lines. -`MicromailClient.quit()` -: Quit the SMTP server and disconnect from socket. +- `MicromailClient.read_res(cmd: str = "", code: int | list[int] = []) -> tuple[int, list[str]]` + + Read response from the SMTP server; returns status code and list of response lines. + +- `MicromailClient.ehlo() -> list[str]` + + Send SMTP EHLO command to the server and return response. + +- `MicromailClient.starttls()` + + Send SMTP STARTTLS command and enable SSL on socket. + +- `MicromailClient.new_message(to: str | list[str], sender: str | None = None)` + + Create a new email; sender defaults to username. + +- `MicromailClient.headers(headers: dict[str, str])` + + Define email headers; supported headers are `date` (`str`, defaults to current date), `from` (defaults to `new_message` `sender`), `to` (defaults to `new_message` `to`), `subject` (`str`). + +- `MicromailClient.write_line(content: str)` + + Write message line; `\r\n` is appended to `content`. + +- `MicromailClient.send()` + + Send current email. + +- `MicromailClient.quit()` + + Quit the SMTP server and disconnect from socket. ### Functions -`format_date(date: datetime)` -: Return date formatted as email date string. +- `format_date(date: datetime) -> str` + + Return date formatted as email date string. + +### Exceptions + +- `Error` + + Standard module error. + +- `NoSocketError` + + Raised when an operation on the socket is asked but the client is not connected to any socket. + +- `SMTPError(cmd: str, code: int, message: str)` + + Raised when an unexpected SMTP response code is received. diff --git a/micromail.py b/micromail.py index 0a4d507..966d0f6 100644 --- a/micromail.py +++ b/micromail.py @@ -110,7 +110,7 @@ class MicromailClient: def write(self, data: str | bytes) -> None: if self.socket is None: - raise Error("No socket to write to.") + raise NoSocketError if isinstance(data, str): data = data.encode()