reykit 1.0.0__py3-none-any.whl

reykit/remail.py

@@ -0,0 +1,276 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+@Time    : 2022-12-05 14:10:19
+@Author  : Rey
+@Contact : reyxbo@163.com
+@Explain : Email methods.
+"""
+
+
+from typing import Optional, Union
+from io import BufferedIOBase
+from smtplib import SMTP
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from email.mime.application import MIMEApplication
+
+from .rdata import unique
+from .rexception import throw
+from .ros import FileBytes, get_file_bytes
+
+
+__all__ = (
+    'REmail',
+)
+
+
+class REmail(object):
+    """
+    Rey's `email` type.
+    """
+
+
+    def __init__(
+        self,
+        username: str,
+        password: str
+    ) -> None:
+        """
+        Build `email` attributes.
+
+        Parameters
+        ----------
+        username : Email username.
+        password : Email password.
+        """
+
+        # Get parameter.
+        host, port = self.get_server_address(username)
+
+        # Set attribute.
+        self.username = username
+        self.password = password
+        self.host = host
+        self.port = port
+        self.smtp = SMTP(host, port)
+
+
+    def get_server_address(
+        self,
+        email: str
+    ) -> tuple[str, str]:
+        """
+        Get server address of email.
+
+        Parameters
+        ----------
+        email : Email address.
+
+        Returns
+        -------
+        Server address.
+        """
+
+        # Get.
+        domain_name = email.split('@')[-1]
+        host = 'smtp.' + domain_name
+        port = 25
+
+        return host, port
+
+
+    def get_smtp(self) -> SMTP:
+        """
+        Get `SMTP` connection instance and login.
+
+        Returns
+        -------
+        Instance.
+        """
+
+        # Login.
+        response = self.smtp.login(self.username, self.password)
+        code = response[0]
+        if code != 235:
+            throw(ConnectionError, response)
+
+        return self.smtp
+
+
+    def create_email(
+        self,
+        title: Optional[str],
+        text: Optional[str],
+        attachment: dict[str, bytes],
+        show_from: Optional[str],
+        show_to: Optional[list[str]],
+        show_cc: Optional[list[str]]
+    ) -> str:
+        """
+        create email content.
+
+        Parameters
+        ----------
+        title : Email title.
+        text : Email text.
+        attachment : Email attachments dictionary.
+            - `Key`: File name.
+            - `Value`: File bytes data.
+        show_from : Show from email address.
+        show_to : Show to email addresses list.
+        show_cc : Show carbon copy email addresses list.
+        """
+
+        # Handle parameter.
+        if show_to.__class__ == list:
+            show_to = ','.join(show_to)
+        if show_cc.__class__ == list:
+            show_cc = ','.join(show_cc)
+
+        # Instance.
+        mimes = MIMEMultipart()
+
+        # Add.
+
+        ## Title.
+        if title is not None:
+            mimes['subject'] = title
+        
+        ## Text.
+        if text is not None:
+            mime_text = MIMEText(text)
+            mimes.attach(mime_text)
+
+        ## Attachment.
+        for file_name, file_bytes in attachment.items():
+            mime_file = MIMEApplication(file_bytes)
+            mime_file.add_header('Content-Disposition', 'attachment', filename=file_name)
+            mimes.attach(mime_file)
+
+        ## Show from.
+        if show_from is not None:
+            mimes['from'] = show_from
+
+        ## Show to.
+        if show_to is not None:
+            mimes['to'] = show_to
+
+        ## Show cc.
+        if show_cc is not None:
+            mimes['cc'] = show_cc
+
+        # Create.
+        email = mimes.as_string()
+
+        return email
+
+
+    def send_email(
+        self,
+        to: Union[str, list[str]],
+        title: Optional[str] = None,
+        text: Optional[str] = None,
+        attachment: dict[str, FileBytes] = {},
+        cc: Optional[Union[str, list[str]]] = None,
+        show_from: Optional[str] = None,
+        show_to: Optional[Union[str, list[str]]] = None,
+        show_cc: Optional[Union[str, list[str]]] = None
+    ) -> None:
+        """
+        Send email.
+
+        Parameters
+        ----------
+        to : To email addresses.
+            - `str`: Email address, multiple comma interval.
+            - `list[str]`: Email addresses list.
+        title : Email title.
+        text : Email text.
+        attachment : Email attachments dictionary.
+            - `Key`: File name.
+            - `Value`: File bytes data source.
+                `bytes`: File bytes data.
+                `str`: File path.
+                `BufferedIOBase`: File bytes IO.
+        cc : Carbon copy email addresses.
+            - `str`: Email address, multiple comma interval.
+            - `list[str]`: Email addresses list.
+        show_from : Show from email address.
+            - `None`: Use attribute `self.username`.
+            - `str`: Email address.
+        show_to : Show to email addresses.
+            - `None`: Use parameter `to`.
+            - `str`: Email address, multiple comma interval.
+            - `list[str]`: Email addresses list.
+        show_cc : Show carbon copy email addresses.
+            - `None`: Use parameter `cc`.
+            - `str`: Email address, multiple comma interval.
+            - `list[str]`: Email addresses list.
+        """
+
+        # Handle parameter.
+
+        ## To.
+        if to.__class__ == str:
+            to = to.split(',')
+
+        ## Cc.
+        match cc:
+            case None:
+                cc = []
+            case str():
+                cc = cc.split(',')
+
+        ## Show from.
+        show_from = show_from or self.username
+
+        ## Show to.
+        show_to = show_to or to
+        if show_to.__class__ == str:
+            show_to = show_to.split(',')
+
+        ## Show cc.
+        show_cc = show_cc or cc
+        if show_cc.__class__ == str:
+            show_cc = show_cc.split(',')
+
+        ## Attachment.
+        for file_name, file_source in attachment.items():
+            file_bytes = get_file_bytes(file_source)
+            attachment[file_name] = file_bytes
+
+        # Create email.
+        email = self.create_email(
+            title,
+            text,
+            attachment,
+            show_from,
+            show_to,
+            show_cc
+        )
+
+        # Get SMTP.
+        smtp = self.get_smtp()
+
+        # Send email.
+        to += cc
+        to = unique(to)
+        smtp.sendmail(
+            self.username,
+            to,
+            email
+        )
+
+
+    __call__ = send_email
+
+
+    def __del__(self) -> None:
+        """
+        Delete instance.
+        """
+
+        # Quit.
+        self.smtp.quit()

reykit/rexception.py

@@ -0,0 +1,339 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+@Time    : 2024-07-17 09:46:40
+@Author  : Rey
+@Contact : reyxbo@163.com
+@Explain : Exception methods.
+"""
+
+
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+@Time    : 2022-12-05 14:09:42
+@Author  : Rey
+@Contact : reyxbo@163.com
+@Explain : Interpreter system methods.
+"""
+
+
+from typing import Any, Optional, Union, NoReturn
+from types import TracebackType
+from collections.abc import Iterable
+from sys import exc_info as sys_exc_info
+from os.path import exists as os_exists
+from traceback import format_exc
+from warnings import warn as warnings_warn
+
+from .rtype import RNull
+
+
+__all__ = (
+    'RError',
+    'RActiveError',
+    'throw',
+    'warn',
+    'catch_exc',
+    'check_least_one',
+    'check_most_one',
+    'check_file_found',
+    'check_file_exist',
+    'check_response_code'
+)
+
+
+class RError(Exception):
+    """
+    Rey `error` type.
+    """
+
+
+class RActiveError(RError):
+    """
+    Rey's `active error` type.
+    """
+
+
+def throw(
+    exception: type[BaseException] = AssertionError,
+    value: Any = RNull,
+    *values: Any,
+    text: Optional[str] = None,
+    frame: int = 2
+) -> NoReturn:
+    """
+    Throw exception.
+
+    Parameters
+    ----------
+    exception : Exception Type.
+    value : Exception value.
+    values : Exception values.
+    text : Exception text.
+    frame : Number of code to upper level.
+    """
+
+    # Text.
+    if text is None:
+        if exception.__doc__ is not None:
+            text = exception.__doc__.strip()
+        if (
+            text is None
+            or text == ''
+        ):
+            text = 'use error'
+        else:
+            text = text[0].lower() + text[1:]
+
+    ## Value.
+    if value is not RNull:
+        values = (value,) + values
+
+        ### Name.
+        from .rsystem import get_name
+        name = get_name(value, frame)
+        names = (name,)
+        if values != ():
+            names_values = get_name(values)
+            if names_values is not None:
+                names += names_values
+
+        ### Convert.
+        match exception:
+            case TypeError():
+                values = [
+                    value.__class__
+                    for value in values
+                    if value is not None
+                ]
+            case TimeoutError():
+                values = [
+                    int(value)
+                    if value % 1 == 0
+                    else round(value, 3)
+                    for value in values
+                    if value.__class__ == float
+                ]
+        values = [
+            repr(value)
+            for value in values
+        ]
+
+        ### Join.
+        if names == ():
+            values_len = len(values)
+            text_value = ', '.join(values)
+            if values_len == 1:
+                text_value = 'value is ' + text_value
+            else:
+                text_value = 'values is (%s)' % text_value
+        else:
+            names_values = zip(names, values)
+            text_value = ', '.join(
+                [
+                    'parameter "%s" is %s' % (name, value)
+                    for name, value in names_values
+                ]
+            )
+        text += ' %s.' % text_value
+
+    # Throw exception.
+    exception = exception(text)
+    raise exception
+
+
+def warn(
+    *infos: Any,
+    exception: type[BaseException] = UserWarning,
+    stacklevel: int = 3
+) -> None:
+    """
+    Throw warning.
+
+    Parameters
+    ----------
+    infos : Warn informations.
+    exception : Exception type.
+    stacklevel : Warning code location, number of recursions up the code level.
+    """
+
+    # Handle parameter.
+    if infos == ():
+        infos = 'Warning!'
+    elif len(infos) == 1:
+        if infos[0].__class__ == str:
+            infos = infos[0]
+        else:
+            infos = str(infos[0])
+    else:
+        infos = str(infos)
+
+    # Throw warning.
+    warnings_warn(infos, exception, stacklevel)
+
+
+def catch_exc(
+    title: Optional[str] = None
+) -> tuple[str, type[BaseException], BaseException, TracebackType]:
+    """
+    Catch exception information and print, must used in `except` syntax.
+
+    Parameters
+    ----------
+    title : Print title.
+        - `None`: Not print.
+        - `str`: Print and use this title.
+
+    Returns
+    -------
+    Exception data.
+        - `str`: Exception report text.
+        - `type[BaseException]`: Exception type.
+        - `BaseException`: Exception instance.
+        - `TracebackType`: Exception traceback instance.
+    """
+
+    # Get parameter.
+    exc_report = format_exc()
+    exc_report = exc_report.strip()
+    exc_type, exc_instance, exc_traceback = sys_exc_info()
+
+    # Print.
+    if title is not None:
+
+        ## Import.
+        from .rstdout import echo
+
+        ## Execute.
+        echo(exc_report, title=title, frame='half')
+
+    return exc_report, exc_type, exc_instance, exc_traceback
+
+
+def check_least_one(*values: Any) -> None:
+    """
+    Check that at least one of multiple values is not null, when check fail, then throw exception.
+
+    Parameters
+    ----------
+    values : Check values.
+    """
+
+    # Check.
+    for value in values:
+        if value is not None:
+            return
+
+    # Throw exception.
+    from .rsystem import get_name
+    vars_name = get_name(values)
+    if vars_name is not None:
+        vars_name_de_dup = list(set(vars_name))
+        vars_name_de_dup.sort(key=vars_name.index)
+        vars_name_str = ' ' + ' and '.join([f'"{var_name}"' for var_name in vars_name_de_dup])
+    else:
+        vars_name_str = ''
+    raise TypeError(f'at least one of parameters{vars_name_str} is not None')
+
+
+def check_most_one(*values: Any) -> None:
+    """
+    Check that at most one of multiple values is not null, when check fail, then throw exception.
+
+    Parameters
+    ----------
+    values : Check values.
+    """
+
+    # Check.
+    none_count = 0
+    for value in values:
+        if value is not None:
+            none_count += 1
+
+    # Throw exception.
+    if none_count > 1:
+        from .rsystem import get_name
+        vars_name = get_name(values)
+        if vars_name is not None:
+            vars_name_de_dup = list(set(vars_name))
+            vars_name_de_dup.sort(key=vars_name.index)
+            vars_name_str = ' ' + ' and '.join([f'"{var_name}"' for var_name in vars_name_de_dup])
+        else:
+            vars_name_str = ''
+        raise TypeError(f'at most one of parameters{vars_name_str} is not None')
+
+
+def check_file_found(path: str) -> None:
+    """
+    Check if file path found, if not, throw exception.
+
+    Parameters
+    ----------
+    path : File path.
+    """
+
+    # Check.
+    exist = os_exists(path)
+
+    # Throw exception.
+    if not exist:
+        throw(FileNotFoundError, path)
+
+
+def check_file_exist(path: str) -> None:
+    """
+    Check if file path exist, if exist, throw exception.
+
+    Parameters
+    ----------
+    path : File path.
+    """
+
+    # Check.
+    exist = os_exists(path)
+
+    # Throw exception.
+    if exist:
+        throw(FileExistsError, path)
+
+
+def check_response_code(
+    code: int,
+    range_: Optional[Union[int, Iterable[int]]] = None
+) -> bool:
+    """
+    Check if the response code is in range.
+
+    Parameters
+    ----------
+    code : Response code.
+    range_ : Pass the code range.
+        - `None`: Check if is between 200 and 299.
+        - `int`: Check if is this value.
+        - `Iterable`: Check if is in sequence.
+
+    Returns
+    -------
+    Check result.
+    """
+
+    # Check.
+    match range_:
+        case None:
+            result = code // 100 == 2
+        case int():
+            result = code == range_
+        case _ if hasattr(range_, '__contains__'):
+            result = code in range_
+        case _:
+            throw(TypeError, range_)
+
+    # Throw exception.
+    if not result:
+        throw(value=code)
+
+    return result