From fa5655414a1c2dde4ff5b1eb184a309b3c10b40c Mon Sep 17 00:00:00 2001 From: Sven Heidemann Date: Mon, 17 May 2021 17:54:57 +0200 Subject: [PATCH] Added docs for cpl.mailing --- src/cpl/mailing/email.py | 78 ++++++++++++++++-------- src/cpl/mailing/email_client_abc.py | 19 +++--- src/cpl/mailing/email_client_service.py | 27 ++++---- src/cpl/mailing/email_client_settings.py | 1 + 4 files changed, 74 insertions(+), 51 deletions(-) diff --git a/src/cpl/mailing/email.py b/src/cpl/mailing/email.py index d204c070..d4d149e7 100644 --- a/src/cpl/mailing/email.py +++ b/src/cpl/mailing/email.py @@ -2,16 +2,24 @@ import re class EMail: + r"""Represents an email - def __init__(self, header: list[str] = None, subject: str = None, body: str = None, transceiver: str = None, receiver: list[str] = None): - """ - Represents an email - :param header: - :param subject: - :param body: - :param transceiver: - :param receiver: - """ + Parameter + --------- + header: list[:class:`str`] + Header of the E-Mail + subject: :class:`str` + Subject of the E-Mail + body: :class:`str` + Body of the E-Mail + transceiver: :class:`str` + Transceiver of the E-Mail + receiver: list[:class:`str`] + Receiver of the E-Mail + """ + + def __init__(self, header: list[str] = None, subject: str = None, body: str = None, transceiver: str = None, + receiver: list[str] = None): self._header: list[str] = header self._subject: str = subject @@ -73,18 +81,26 @@ class EMail: @staticmethod def check_mail(address: str) -> bool: - """ - Checks if an email is valid - :param address: - :return: + r"""Checks if an email is valid + + Parameter + --------- + address: :class:`str` + The address to check + + Returns + ------- + Result if E-Mail is valid or not """ return bool(re.search('^\\w+([.-]?\\w+)*@\\w+([.-]?\\w+)*(.\\w{2,3})+$', address)) def add_header(self, header: str): - """ - Adds header - :param header: - :return: + r"""Adds header + + Parameter + --------- + header: :class:`str` + The header of the E-Mail """ if self._header is None: self._header = [] @@ -92,10 +108,12 @@ class EMail: self._header.append(header) def add_receiver(self, receiver: str): - """ - Adds receiver - :param receiver: - :return: + r"""Adds receiver + + Parameter + --------- + receiver: :class:`str` + The receiver of the E-Mail """ if self._receiver is None: self._receiver = [] @@ -106,9 +124,17 @@ class EMail: raise Exception(f'Invalid email: {receiver}') def get_content(self, transceiver: str): + r"""Returns the mail as string + + Parameter + --------- + transceiver: :class:`str` + The transceiver of the E-Mail + + Returns + ------- + E-Mail as string """ - Returns the mail as string - :param transceiver: - :return: - """ - return str(f'From: {transceiver}\r\nTo: {self.receiver}\r\n{self.header}\r\nSubject: {self.subject}\r\n{self.body}').encode('utf-8') + return str( + f'From: {transceiver}\r\nTo: {self.receiver}\r\n{self.header}\r\nSubject: {self.subject}\r\n{self.body}').encode( + 'utf-8') diff --git a/src/cpl/mailing/email_client_abc.py b/src/cpl/mailing/email_client_abc.py index 29690394..dfc80424 100644 --- a/src/cpl/mailing/email_client_abc.py +++ b/src/cpl/mailing/email_client_abc.py @@ -4,27 +4,24 @@ from cpl.mailing.email import EMail class EMailClientABC(ABC): + """ABC of :class:`cpl.mailing.email_client_service.EMailClient`""" @abstractmethod def __init__(self): - """ - ABC to send emails - """ ABC.__init__(self) @abstractmethod def connect(self): - """ - Connects to server - :return: - """ + r"""Connects to server""" pass @abstractmethod def send_mail(self, email: EMail): - """ - Sends email - :param email: - :return: + r"""Sends email + + Parameter + --------- + email: :class:`cpl.mailing.email.EMail` + Object of the E-Mail to send """ pass diff --git a/src/cpl/mailing/email_client_service.py b/src/cpl/mailing/email_client_service.py index 170489ff..f169fa11 100644 --- a/src/cpl/mailing/email_client_service.py +++ b/src/cpl/mailing/email_client_service.py @@ -11,14 +11,19 @@ from cpl.utils.credential_manager import CredentialManager class EMailClient(EMailClientABC): + r"""Service to send emails + + Parameter + --------- + environment: :class:`cpl.environment.application_environment_abc.ApplicationEnvironmentABC` + Environment of the application + logger: :class:`cpl.logging.logger_abc.LoggerABC` + The logger to use + mail_settings: :class:`cpl.mailing.email_client_settings.EMailClientSettings` + Settings for mailing + """ def __init__(self, environment: ApplicationEnvironmentABC, logger: LoggerABC, mail_settings: EMailClientSettings): - """ - Service to send emails - :param environment: - :param logger: - :param mail_settings: - """ EMailClientABC.__init__(self) self._environment = environment @@ -30,10 +35,7 @@ class EMailClient(EMailClientABC): self.create() def create(self): - """ - Creates connection - :return: - """ + r"""Creates connection""" self._logger.trace(__name__, f'Started {__name__}.create') self.connect() self._logger.trace(__name__, f'Stopped {__name__}.create') @@ -54,10 +56,7 @@ class EMailClient(EMailClientABC): self._logger.trace(__name__, f'Stopped {__name__}.connect') def login(self): - """ - Login to server - :return: - """ + r"""Login to server""" self._logger.trace(__name__, f'Started {__name__}.login') try: self._logger.debug(__name__, f'Try to login {self._mail_settings.user_name}@{self._mail_settings.host}:{self._mail_settings.port}') diff --git a/src/cpl/mailing/email_client_settings.py b/src/cpl/mailing/email_client_settings.py index 3c75f1e8..31b7f151 100644 --- a/src/cpl/mailing/email_client_settings.py +++ b/src/cpl/mailing/email_client_settings.py @@ -6,6 +6,7 @@ from cpl.mailing.email_client_settings_name_enum import EMailClientSettingsNameE class EMailClientSettings(ConfigurationModelABC): + r"""Representation of mailing settings""" def __init__(self): ConfigurationModelABC.__init__(self)