Merge pull request #32 from Integration-Automation/dev

Edit docs

README.md

@@ -11,7 +11,8 @@
 [![MailThunder Stable Python3.11](https://github.com/Intergration-Automation-Testing/MailThunder/actions/workflows/mail_thunder_stable_python3_11.yml/badge.svg)](https://github.com/Intergration-Automation-Testing/MailThunder/actions/workflows/mail_thunder_stable_python3_11.yml)
 
 ### Documentation
-TODO
+
+Docs: <https://mailthunder.readthedocs.io/en/latest/>
 
 ### Notice
 * Default is using Google service provide, but you can change init setting to choose what service provide you want to use.
@@ -49,5 +50,5 @@ pip install je_mail_thunder
 ## Requires
 
 ```
-python 3.8 or later
+python 3.9 or later
 ```

docs/source/docs/API/imap_api.rst

@@ -3,23 +3,23 @@ MailThunder IMAP API
 
 .. code-block:: python
 
-    def imap_later_init(self):
+    def later_init(self):
         """
         Try to log in
         :return: None
         """
 
 .. code-block:: python
 
-    def imap_try_to_login_with_env_or_content(self):
+    def try_to_login_with_env_or_content(self):
         """
         Try to find user and password on cwd /mail_thunder_content.json or env var
         :return: None
         """
 
 .. code-block:: python
 
-    def imap_select_mailbox(self, mailbox: str = "INBOX", readonly: bool = False):
+    def select_mailbox(self, mailbox: str = "INBOX", readonly: bool = False):
         """
         :param mailbox: Mailbox we want to select like INBOX
         :param readonly: Readonly or not
@@ -28,7 +28,7 @@ MailThunder IMAP API
 
 .. code-block:: python
 
-    def imap_search_mailbox(self, search_str: [str, list] = "ALL", charset: str = None) -> list:
+    def search_mailbox(self, search_str: [str, list] = "ALL", charset: str = None) -> list:
         """
         Get all mail detail as list
         :param search_str: Search pattern
@@ -38,7 +38,7 @@ MailThunder IMAP API
 
 .. code-block:: python
 
-    def imap_mail_content_list(
+    def mail_content_list(
             self, search_str: [str, list] = "ALL", charset: str = None) -> List[Dict[str, Union[str, bytes]]]:
         mail_thunder_logger.info(f"imap_mail_content_list, search_str: {search_str}, charset: {charset}")
         """
@@ -50,7 +50,7 @@ MailThunder IMAP API
 
 .. code-block:: python
 
-    def imap_output_all_mail_as_file(
+    def output_all_mail_as_file(
             self, search_str: [str, list] = "ALL", charset: str = None) -> List[Dict[str, Union[str, bytes]]]:
         mail_thunder_logger.info(f"imap_mail_content_list, search_str: {search_str}, charset: {charset}")
         """
@@ -62,7 +62,7 @@ MailThunder IMAP API
 
 .. code-block:: python
 
-    def imap_quit(self):
+    def quit(self):
         """
         Quit service and close connect
         :return: None

docs/source/docs/API/smtp_api.rst

@@ -3,7 +3,7 @@ MailThunder SMTP API
 
 .. code-block:: python
 
-    def smtp_later_init(self):
+    def later_init(self):
         """
         Try to log in
         :return: None
@@ -12,7 +12,7 @@ MailThunder SMTP API
 .. code-block:: python
 
     @staticmethod
-    def smtp_create_message(message_content: str, message_setting_dict: dict, **kwargs):
+    def create_message(message_content: str, message_setting_dict: dict, **kwargs):
         """
         Create new EmailMessage instance
         :param message_content: Mail content
@@ -24,7 +24,7 @@ MailThunder SMTP API
 .. code-block:: python
 
     @staticmethod
-    def smtp_create_message_with_attach(message_content: str, message_setting_dict: dict,
+    def create_message_with_attach(message_content: str, message_setting_dict: dict,
                                         attach_file: str, use_html: bool = False):
         """
         Create new EmailMessage with attach file instance
@@ -37,7 +37,7 @@ MailThunder SMTP API
 
 .. code-block:: python
 
-    def smtp_try_to_login_with_env_or_content(self):
+    def try_to_login_with_env_or_content(self):
         """
         Try to find user and password on cwd /mail_thunder_content.json or env var
         :return: None
@@ -53,7 +53,7 @@ MailThunder SMTP API
 
 .. code-block:: python
 
-    def smtp_create_message_with_attach_and_send(self, message_content: str, message_setting_dict: dict,
+    def create_message_with_attach_and_send(self, message_content: str, message_setting_dict: dict,
                                                  attach_file: str, use_html: bool = False):
         """
         Create new EmailMessage with attach file instance then send EmailMessage instance
@@ -66,7 +66,7 @@ MailThunder SMTP API
 
 .. code-block:: python
 
-    def smtp_create_message_and_send(self, message_content: str, message_setting_dict: dict, **kwargs):
+    def create_message_and_send(self, message_content: str, message_setting_dict: dict, **kwargs):
         """
         Create new EmailMessage instance then send EmailMessage instance
         :param message_content: Mail content

docs/source/docs/Eng/read_google_mail.rst

@@ -3,22 +3,28 @@ Read Google Mail via IMAP
 
 .. code-block:: python
 
-    from je_mail_thunder import IMAPWrapper
+    from je_mail_thunder import IMAPWrapper, set_mail_thunder_os_environ
 
     # Set imap host
     imap_host = 'imap.gmail.com'
     # Init IMAPWrapper
     imap_wrapper = IMAPWrapper(host=imap_host)
-    imap_wrapper.imap_later_init()
+
+    set_mail_thunder_os_environ(
+        "test_user", # your user
+        "test_password" # your password
+    )
+
+    imap_wrapper.later_init()
     # Select INBOX
     imap_wrapper.select()
     # Get mail list
-    mail_list = imap_wrapper.imap_mail_content_list()
+    mail_list = imap_wrapper.mail_content_list()
     # Print SUBJECT FROM TO BODY
     for mail in mail_list:
         print(mail.get("SUBJECT"))
         print(mail.get("FROM"))
         print(mail.get("TO"))
         print(mail.get("BODY"))
     # Quit
-    imap_wrapper.imap_quit()
+    imap_wrapper.quit()

docs/source/docs/Eng/send_google_mail.rst

@@ -6,19 +6,19 @@ Send Google Mail via SMTP
     from je_mail_thunder import SMTPWrapper
     from je_mail_thunder import mail_thunder_content_data_dict
 
-    # Init SMTPWrapper
     smtp_wrapper = SMTPWrapper()
-    smtp_wrapper.smtp_later_init()
+    # need have mail_thunder_content.json in current folder
+    # and need to init SMTPWrapper first
+
+    mail_thunder_content_data_dict.update({
+        "user": "test_user", # your user
+        "password": "test_password", # your password
+    })
+
     user = mail_thunder_content_data_dict.get("user")
-    # Read html file
-    with open("test.html", "r+") as file:
-        html_string = file.read()
-    # Create message instance
-    message = smtp_wrapper.smtp_create_message_with_attach(
-        html_string,
-        {"Subject": "test_subject", "To": user, "From": user},
-        "test.html", use_html=True)
-    # Send message instance
+
+    smtp_wrapper.try_to_login_with_env_or_content()
+
+    message = smtp_wrapper.create_message("test", {"Subject": "test_subject", "To": user, "From": user})
     smtp_wrapper.send_message(message)
-    # QUIT
     smtp_wrapper.quit()

docs/source/docs/Zh/read_google_mail.rst

@@ -1,24 +1,30 @@
-讀取 Google 郵件使用 IMAP
+使用 IMAP 讀取 Google 郵件
 ----
 
 .. code-block:: python
 
-    from je_mail_thunder import IMAPWrapper
+    from je_mail_thunder import IMAPWrapper, set_mail_thunder_os_environ
 
-    # 設定 IMAP host
+    # 設置 IMAP 主機
     imap_host = 'imap.gmail.com'
-    # 初始化 IMAPWrapper
+    # 初始 IMAP 包裝類別
     imap_wrapper = IMAPWrapper(host=imap_host)
-    imap_wrapper.imap_later_init()
-    # 選擇郵件箱
+
+    set_mail_thunder_os_environ(
+        "test_user", # your user
+        "test_password" # your password
+    )
+
+    imap_wrapper.later_init()
+    # 選擇搜尋的信箱 (沒有帶參數是全部)
     imap_wrapper.select()
-    # 取得郵件 list
-    mail_list = imap_wrapper.imap_mail_content_list()
-    # 輸出郵件 主旨 從哪個郵件地址寄送到哪個地址 郵件 BODY
+    # 取得郵件列表
+    mail_list = imap_wrapper.mail_content_list()
+    # 輸出基本資訊
     for mail in mail_list:
         print(mail.get("SUBJECT"))
         print(mail.get("FROM"))
         print(mail.get("TO"))
         print(mail.get("BODY"))
-    # 退出
-    imap_wrapper.imap_quit()
+    # 離開
+    imap_wrapper.quit()

docs/source/docs/Zh/send_google_mail.rst

@@ -1,25 +1,23 @@
-寄送郵件使用 Google 信箱
+使用 Google 信箱寄送郵件
 ----
 
 .. code-block:: python
 
     from je_mail_thunder import SMTPWrapper
     from je_mail_thunder import mail_thunder_content_data_dict
 
-    # 初始化 SMTPWrapper
     smtp_wrapper = SMTPWrapper()
-    smtp_wrapper.smtp_later_init()
+
+    mail_thunder_content_data_dict.update({
+        "user": "test_user", # 你的使用者
+        "password": "test_password", # 你的密碼 (google 需使用應用程式密碼)
+    })
+
     user = mail_thunder_content_data_dict.get("user")
-    # 讀取 html 檔案
-    with open("test.html", "r+") as file:
-        html_string = file.read()
-    # 建立訊息
-    message = smtp_wrapper.smtp_create_message_with_attach(
-        html_string,
-        {"Subject": "test_subject", "To": user, "From": user},
-        "test.html", use_html=True)
-    # 傳送訊息
+
+    smtp_wrapper.try_to_login_with_env_or_content()
+
+    message = smtp_wrapper.create_message("test", {"Subject": "test_subject", "To": user, "From": user})
     smtp_wrapper.send_message(message)
-    # 退出
     smtp_wrapper.quit()
 

test/unit_test/manual_test/imap/imap_get_all_mail_content_test.py

@@ -5,7 +5,10 @@
 # Init IMAPWrapper
 imap_wrapper = IMAPWrapper(host=imap_host)
 
-set_mail_thunder_os_environ("test_user", "test_password")
+set_mail_thunder_os_environ(
+    "test_user", # your user
+    "test_password" # your password
+)
 
 imap_wrapper.later_init()
 # Select INBOX

test/unit_test/manual_test/smtp/smtp_send_mail_test.py

@@ -6,8 +6,8 @@
 # and need to init SMTPWrapper first
 
 mail_thunder_content_data_dict.update({
-    "user": "test_user",
-    "password": "test_password",
+    "user": "test_user", # your user
+    "password": "test_password", # your password
 })
 
 user = mail_thunder_content_data_dict.get("user")