diff --git a/README.md b/README.md index 8f3a43f..7554885 100644 --- a/README.md +++ b/README.md @@ -59,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 diff --git a/docs/source/getting_started/examples/example1.rst b/docs/source/getting_started/examples/example1.rst index 6a3e4b2..9594bba 100644 --- a/docs/source/getting_started/examples/example1.rst +++ b/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.