Merge branch 'develop' into chore/pyproject.toml-config

CHANGELOG.md

@@ -1,10 +1,23 @@
 ## Unreleased
 
+### Fix
+
+- **build**: solve versioning problem
+- **README.md**: update README.md
+- **stubs**: regenerate stubs
+
+### Refactor
+
+- improve docs for client section
+- improve client service to handle reqs without ctx
+
+## v0.4.0 (2024-07-17)
+
 ### Feat
 
 - **sage_imap**: enhance imap service
-- **IMAPMailboxService**: Add .eml file upload functionality to IMAP server
 - **sage_imap**: enhance EmailMessage dataclass
+- **IMAPMailboxService**: Add .eml file upload functionality to IMAP server
 
 ### Fix
 

README.md

@@ -26,7 +26,6 @@
     - [Example 3: Working with Mailbox Methods](#example-3-working-with-mailbox-methods)
     - [IMAPMailboxService Example](#imapmailboxservice-example)
       - [Example Usage with Nested Context Managers:](#example-usage-with-nested-context-managers)
-    - [Methods of IMAPMailboxService Explained](#methods-of-imapmailboxservice-explained)
   - [License](#license)
 
 ## Introduction
@@ -60,6 +59,8 @@ logging.basicConfig(level=logging.DEBUG)
 
 This example demonstrates how to create an IMAP client using the `IMAPClient` class.
 
+The `IMAPClient` class can also be used without a context manager; simply call `connect()` to establish the connection and `disconnect()` to close it
+
 ```python
 from sage_imap.services import IMAPClient
 
@@ -143,84 +144,21 @@ try:
     with IMAPClient('imap.example.com', username, password) as client:
         with IMAPMailboxService(client) as mailbox:
             # Select a mailbox
-            mailbox.select_mailbox(DefaultMailboxes.INBOX)
+            mailbox.select(DefaultMailboxes.INBOX)
 
             # Delete messages temporarily (move to trash)
             msg_set = MessageSet('1,2,3')
-            mailbox.delete_temporarily(msg_set)
+            mailbox.trash(msg_set)
 
             # Restore messages from trash to original folder
-            mailbox.restore_from_trash(msg_set, DefaultMailboxes.INBOX)
+            mailbox.restore(msg_set, DefaultMailboxes.INBOX)
 
             # Permanently delete messages
-            mailbox.delete_permanently(msg_set)
+            mailbox.delete(msg_set)
 
 except IMAPClientError as e:
     print(f"An error occurred with the IMAP client: {e}")
 ```
 
-### Methods of IMAPMailboxService Explained
-
-1. **select_mailbox(mailbox=DefaultMailboxes.INBOX)**
-   - **Purpose:** Selects the specified mailbox for subsequent operations.
-   - **Example:**
-     ```python
-     mailbox_service.select_mailbox('INBOX')
-     ```
-
-2. **close_mailbox()**
-   - **Purpose:** Closes the currently selected mailbox to ensure all changes are saved and the connection is properly terminated.
-   - **Example:**
-     ```python
-     mailbox_service.close_mailbox()
-     ```
-
-3. **check()**
-   - **Purpose:** Sends a CHECK command to the IMAP server to synchronize the mailbox.
-   - **Example:**
-     ```python
-     mailbox_service.check()
-     ```
-
-4. **delete_temporarily(msg_set: MessageSet)**
-   - **Purpose:** Marks messages for deletion and moves them to the trash folder.
-   - **Example:**
-     ```python
-     mailbox_service.delete_temporarily(MessageSet('1,2,3'))
-     ```
-
-5. **delete_permanently(msg_set: MessageSet)**
-   - **Purpose:** Permanently deletes messages marked for deletion.
-   - **Example:**
-     ```python
-     mailbox_service.delete_permanently(MessageSet('1,2,3'))
-     ```
-
-6. **move_to_folder(msg_set: MessageSet, folder: str)**
-   - **Purpose:** Moves messages to the specified folder.
-   - **Example:**
-     ```python
-     mailbox_service.move_to_folder(MessageSet('1,2,3'), 'Archive')
-     ```
-
-7. **restore_from_trash(msg_set: MessageSet, original_folder: str)**
-   - **Purpose:** Restores messages from the trash to the original folder.
-   - **Example:**
-     ```python
-     mailbox_service.restore_from_trash(MessageSet('1,2,3'), 'INBOX')
-     ```
-
-8. **get_mailbox_status(mailbox=DefaultMailboxes.INBOX, *status_items: List[MailboxStatusItems
-
-])**
-   - **Purpose:** Gets the status of the specified mailbox based on the provided status items.
-   - **Example:**
-     ```python
-     status = mailbox_service.get_mailbox_status('INBOX', MailboxStatusItems.MESSAGES)
-     print(f"Mailbox status: {status}")
-     ```
-
-By utilizing these classes and methods, you can manage your IMAP mailboxes effectively and perform necessary email operations in a robust and error-handling manner.
-
 ## License
 This project is licensed under the MIT License.

docs/source/code/flags.rst → docs/source/code/enums.rst

@@ -1,7 +1,7 @@
 Flag Module
 =============
 
-.. automodule:: sage_imap.helpers.flags
+.. automodule:: sage_imap.helpers.enums
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/code/message.rst → docs/source/code/models.rst

@@ -1,7 +1,7 @@
 Message Module
 ==============
 
-.. automodule:: sage_imap.helpers.message
+.. automodule:: sage_imap.models
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/code/modules.rst

@@ -6,8 +6,8 @@ Code API
 
    client
    exceptions
-   flags
+   enums
    folder
    mailbox
-   message
+   models
    search

docs/source/getting_started/examples/example1.rst

@@ -3,6 +3,10 @@ Example 1: Creating an IMAP Client
 
 This example demonstrates how to create an IMAP client using the `IMAPClient` class.
 
+The IMAPClient class can be used both with and without a context manager.
+
+# **With Context Manager**
+
 .. code-block:: python
 
     from sage_imap.services.client import IMAPClient
@@ -15,6 +19,24 @@ This example demonstrates how to create an IMAP client using the `IMAPClient` cl
         status, messages = client.select("INBOX")
         print(f"Selected INBOX with status: {status}")
 
+# **Without Context Manager**
+
+.. code-block:: python
+
+   from sage_imap.services.client import IMAPClient
+
+   # Initialize and use without context manager
+   client = IMAPClient('imap.example.com', 'username', 'password')
+   try:
+      client.connect()
+      capabilities = client.connection.capability()
+      print(f"Server capabilities: {capabilities}")
+
+      status, messages = client.connection.select("INBOX")
+      print(f"Selected INBOX with status: {status}")
+   finally:
+      client.disconnect()
+
 Explanation
 -----------
 
@@ -25,11 +47,15 @@ This example illustrates a low-level approach to working with IMAP. If you want
    - When the `with` block is entered, the connection to the IMAP server is established, and the user is authenticated.
    - When the `with` block is exited, the connection is automatically closed, ensuring that resources are cleaned up properly.
 
-2. **Why Use IMAPClient**:
+2. **IMAPClient Without Context Manager**:
+   - You can also use the `IMAPClient` class without a context manager. In this case, you need to manually call `connect()` to establish the connection and `disconnect()` to close it.
+   - This approach provides explicit control over when the connection is opened and closed but requires careful handling to ensure resources are properly released.
+
+3. **Why Use IMAPClient**:
    - The `IMAPClient` exists to simplify the management of IMAP connections. By using it as a context manager, you don't have to worry about manually opening and closing the connection. This reduces the risk of resource leaks and makes your code cleaner and more maintainable.
    - Within the context manager, you have access to the `imaplib` capabilities directly through the `client` object. This allows you to perform various IMAP operations seamlessly.
 
-3. **Capabilities and Select Methods**:
+4. **Capabilities and Select Methods**:
    - The `.capability()` method is called to retrieve the server's capabilities, providing information about what commands and features the server supports.
    - The `.select("INBOX")` method is used to select the "INBOX" mailbox for further operations. It returns the status of the selection and the number of messages in the mailbox.