fast-gmail 1.0.0__tar.gz

fast_gmail-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 aleti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fast_gmail-1.0.0/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.1
+Name: fast_gmail
+Version: 1.0.0
+Summary: GmailApi wrapper
+Home-page: https://github.com/aleti1/fast_gmail
+Author: Aleti
+Author-email: aleti.open.source@gmail.com
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client==2.125.0
+Requires-Dist: google-auth-httplib2==0.2.0
+Requires-Dist: google-auth-oauthlib==1.2.0
+Requires-Dist: typing-extensions==4.11.0
+
+# Fast-gmail a simple python wrapper for gmailapi
+
+[![PyPI Downloads](https://img.shields.io/pypi/dm/fast-gmail.svg?label=PyPI%20downloads)](
+https://pypi.org/project/fast-gmail/)
+
+---
+## Functionalities:
+- Send text/html messages
+- Send messages with signature & attachments
+- Get messages with pagination
+- Filter messages
+- Get drafts
+- Edit message labels
+- Get message attachments
+
+
+## Instalation:
+`pip install fast-gmail`
+
+---
+
+## Usage:
+
+### Initialization
+- Go to https://console.developers.google.com/apis/credentials and login to correct account
+- Setup Oauth consent screen
+- Create new credentials with OAuth client ID for web or installed app
+- Set Authorized Javascript origins to http://localhost:3000/
+- Set Authorized redirect URIs to http://localhost:3000/
+- Download the credentials.json file
+- Go to Enable APIs & services and enable GmailAPI
+
+With credentials.json file downloaded we can connect to Gmail
+```
+gmail = GmailApi(
+    credentials_file_path = __path_to_credentials_json_file__,
+    port = 3000, # default is 3000 but you can use any other port IMPORTANT: if you change this default value don't forget to also changed on Authorized Javascript origins & Authorized redirect URIs
+)
+```
+
+### Send message
+``` 
+    from fast_gmail import GmailApi
+
+    messages = GmailApi().send_message(
+        sender: str,
+        to: str,
+        subject: str,
+        html: Optional[str]=None,
+        text: Optional[str]=None,
+        cc: Optional[List[str] | str]=None,
+        bcc: Optional[List[str] | str]=None,
+        attachments: Optional[List[str] | str]=None,
+        signature: bool = True
+    )
+    """Sends an email message.
+        Args:
+            sender (str): Email address of the message sender.
+            to (str): Email address of the recipient.
+            subject (str): Subject line of the email.
+            html (Optional[str], optional): HTML content of the email body. Defaults to None.
+            text (Optional[str], optional): Plain text content of the email body. Defaults to None.
+            cc (Optional[List[str] | str], optional): List of email addresses to carbon copy. Defaults to None.
+            bcc (Optional[List[str] | str], optional): List of email addresses to blind carbon copy. Defaults to None.
+            attachments (Optional[List[str] | str], optional): List of file paths to attach to the email. Defaults to None.
+            signature (bool, optional): Whether to include a signature (if configured). Defaults to True.
+        Returns:
+            Optional[Message]: An object representing the sent message, or None on error.
+    """
+```
+
+### Get messages
+```
+    messages = GmailApi().get_messages(
+        includeSpamTrash: bool = False,
+        max_results: int = 10,
+        labels: Union[List[Labels], List[str], None] = None,
+        next_page_token: str = None,
+        existing_pages: Optional[List[str] | str] = None,
+        previous_page_token: Optional[str] = None,
+        query: Union[SearchParams, str] = None,
+    )
+    """Retrieves messages from a user's mailbox.
+        Args:
+            includeSpamTrash (bool, optional): If True, includes messages from spam and trash folders. Defaults to False.
+            max_results (int, optional): Maximum number of messages to return. Defaults to MAX_RESULTS (10).
+            labels (Union[List[Labels], List[str], None], optional): List of label IDs or strings to filter by. Defaults to None (all labels).
+            next_page_token (str, optional): Page token for fetching the next page of results.
+            existing_pages (Optional[List[str] | str], optional): Used internally for pagination. Defaults to None.
+            previous_page_token (Optional[str], optional): Page token for fetching the previous page of results.
+            query (Union[SearchParams, str], optional): Search query to filter messages. Can be a string or a SearchParams object. 
+        Returns:
+            GetMessagesResponse: An object containing the retrieved messages and pagination information.
+    """
+```
+
+### Get INBOX/SPAM/TRASH messages
+```
+    messages = GmailApi().get_inbox_messages(
+        max_results: int = MAX_RESULTS,
+        next_page_token: str = None,
+        existing_pages: Optional[List[str] | str] = None,
+        previous_page_token: Optional[str] = None,
+        query: Union[SearchParams, str] = None
+    )
+
+    # helpers for spam or trash
+    messages = GmailApi().get_spam_messages()
+    messages = GmailApi().get_trash_messages()
+```
+
+### GET message
+```
+    message = GmailApi().get_message(id)
+    # returns a Message object
+```
+
+### GET attachment
+```
+    message = GmailApi().get_message(id)
+    attachment_id = None
+    attachment_name = None
+    for attacment in message.attachments:
+        attachment_id = attachment.part_id
+        attachment_name = attachment.filename
+
+    # get attachment by id
+    by_id = message.get_attachment(id=attachment_id)
+    # or by filename
+    by_name = message.get_attachment(filename=attachment_name) # returns an Attachment object
+
+    # save file to disk
+    by_id.save(filepath=f"/tmp/{attachment.filename}", overwrite=True)
+```
+
+### Message actions
+```
+    message = GmailApi().get_message(id)
+
+    # mark read or unread
+    message.toggle_read_unread
+    # or
+    message.mark_as_read
+    # or
+    message.mark_as_unread
+
+    # spam
+    message.toggle_spam
+    # or
+    message.mark_spam
+    message.mark_not_spam
+
+    # trash
+    message.toggle_trash
+    # or
+    message.move_to_trash
+    message.move_from_trash
+
+    # starred
+    message.toggle_starred
+    message.mark_starred
+    message.mark_not_starred
+
+    #important
+    message.toggle_important
+    message.mark_important
+    message.mark_not_important
+
+    # other properties
+    message.body
+    message.html
+    message.plain
+    message.recipient
+    message.subject
+    message.sender
+    message.snippet
+    message.is_starred
+    message.is_important
+    message.is_spam
+    message.is_unread
+    ...
+
+```
+
+---
+
+## Classes:
+
+### class GmailApi:
+###### Attributes:
+
+- **credentials (Optional[Credentials])**: Stores user credentials (OAuth tokens) for accessing Gmail.
+- **google_service (GoogleService)**: An instance of GoogleService used for making API requests.
+- **max_results (int)**: Maximum number of messages to retrieve per request (default 10).
+- **SEPARATOR_SYMBOL (str)**: String used for separating page tokens during pagination.
+- **profile_data (Optional[GmailProfile])**: Caches the user's Gmail profile information.
+
+###### Constructor (__init__):
+- Initializes the GmailApi object.
+- Reads credentials from token and credentials files.
+- Handles refreshing expired tokens.
+- Creates a GoogleService instance for making API calls.
+
+###### Methods:
+###### Message Retrieval:
+- **get_message(id: str)-> Optional[Message]**: Retrieves a message by its ID.
+- **get_draft(id: str)-> Optional[Message]**: Retrieves a draft by its ID.
+###### Message Sending:
+- **send_message(sender, to, subject, ...)-> Optional[Message]**: Sends an email message with various options (text, HTML, attachments, signature).
+###### Inbox Management:
+- **get_inbox_messages()-> GetMessagesResponse**: Retrieves messages from the inbox.
+Similar methods exist for getting trash, spam, and all messages with various filtering options.
+###### Drafts Management:
+- **get_draft_messages()**: Retrieves draft messages.
+###### Attachment Management:
+- **get_attachment(message_id: str, attachment_id: str) -> Optional[MessagePartBody]**: Retrieves an attachment from a message.
+###### Profile and Label Management:
+- **labels**: Returns a list of user labels.
+- **profile**: Retrieves and caches the user's Gmail profile information.
+
+Overall, this code provides a well-structured and functional interface for interacting with Gmail using the Gmail API.
+
+---
+
+### class Message:
+###### Properties:
+- **id**: Unique identifier for the message.
+- **snippet**: Shortened summary of the message content.
+- **threadId**: Thread ID that groups related messages together.
+- **historyId**: Unique identifier for a specific message history change.
+- **sizeEstimate**: Approximate size of the message in bytes.
+- **internalDate**: Internal timestamp representing when the message was created.
+- **payload**: Object of type MessagePart containing the parsed content of the message body and attachments.
+- **raw**: Optional property containing the raw email data (if available).
+- **labelIds**: List of label IDs associated with the message.
+- **labels**: List of GmailLabel objects representing the message's labels (fetched on demand).
+
+###### Additional Message Properties:
+- **message_headers**: Returns a list of MessageHeader objects from the message's payload (if available).
+- **body**: Returns the message body content (combines plain text and HTML if both exist).
+- **html**: Returns the HTML content of the message body (if available).
+- **plain**: Returns the plain text content of the message body (if available).
+- **alternative**: Returns the text content of the most appropriate alternative part (if message uses multipart/alternative).
+- **recipient**: Extracts the recipient's email address from the "To" header (if available).
+- **message_id**: Extracts the message ID from the message headers (if available).
+- **subject**: Extracts the subject line from the message headers (if available).
+- **sender**: Extracts the sender's email address from the "From" header (if available).
+- **has_attachments**: Checks if the message or its nested parts contain attachments.
+- **attachments**: Returns a list of Attachment objects for all attachments within the message.
+- **is_unread, is_starred, is_important, etc.**: Boolean properties indicating the message's label status (unread, starred, important, spam, draft, trash).
+- **created_date**: Converts the internalDate to a datetime object representing the message creation time.
+- **date**: Parses the "Received" or "Date" header to get the message delivery date (if available).
+- **date_string**: Formats the delivery date according to a specified format string (defaults to "%a, %d %b %Y %H:%M:%S %z").
+
+---
+
+###### Methods:
+- **mark_as_read, mark_as_unread**: Toggles the unread flag for the message.
+- **toogle_read_unread**: Shortcut to toggle the unread flag based on the current state.
+- **mark_spam, mark_not_spam**: Toggles the spam label for the message.
+- **toggle_spam**: Shortcut to toggle the spam label based on the current state.
+- **move_to_trash, move_from_trash**: Toggles the trash label for the message.
+- **toggle_trash**: Shortcut to toggle the trash label based on the current state.
+- **mark_important, mark_not_important**: Toggles the important label for the message.
+- **toggle_important**: Shortcut to toggle the important label based on the current state.
+- **mark_starred, mark_not_starred**: Toggles the starred label for the message.
+- **toggle_starred**: Shortcut to toggle the starred label based on the current state.
+- **get_attachment(filename=None, id=None)**: Retrieves an attachment by filename or internal part ID.
+- **get_labels**: Fetches and returns a list of GmailLabel objects for all labels associated with the message.
+- **add_label(label), add_labels(labels)**: Adds labels to the message.
+- **remove_label(label), remove_labels(labels)**: Removes labels from the message.
+- **modify_labels(labels_to_add=None, labels_to_remove=None)**: Updates message labels by adding and/or removing labels.
+
+Overall, this Message class provides a comprehensive way to access and manage individual email messages within a Gmail account. It allows you to retrieve message details, content, attachments, labels, and perform various actions like marking as read/unread, starring, labeling, and trash management.
+
+---
+
+### class Attachment:
+###### Properties:
+- **filename (str)**: This attribute stores the filename of the attachment.
+- **mimeType (str)**: This attribute stores the MIME type of the attachment content, which specifies the format of the data (e.g., image/jpeg, text/plain).
+- **part_id (str)**: This attribute stores the internal identifier for the attachment within the message parts. This ID is used to download the attachment using the Gmail API.
+- **google_service (GoogleService)**: This attribute holds a reference to the GoogleService object used for downloading the attachment. This object likely encapsulates authentication and communication details with the Gmail API.
+- **id (Optional[str])**: This optional attribute stores the ID of the attachment generated by Gmail after a message is fetched using the .get() method. This ID might change for the same attachment across different fetches.
+- **data (Optional[str])**: This optional attribute stores the Base64 encoded content of the attachment data downloaded from the API.
+
+###### Methods:
+- **download() -> None**: This method downloads the attachment data from the Gmail API if it hasn't been downloaded already. It raises exceptions for errors like missing message ID or HTTP errors during download.
+- **save(filepath: Optional[str] = None, overwrite: bool = False) -> None**: This method saves the attachment data to a file. It allows specifying the filepath and whether to overwrite existing files. It raises an error if the file already exists and overwrite is set to False.
+
+Overall, the Attachment class provides functionality to manage attachments associated with Gmail messages. It handles downloading attachments from the API, storing downloaded data, and saving them to local files.
+
+---
+
+### class GetMessagesResponse:
+###### Attributes:
+- **next_page_token (Optional[str], optional)**: Token for fetching the next page of results. Defaults to None.
+- **existing_pages (Optional[str], optional)**: Used internally for pagination. Defaults to None. List like string of page tokens separated by GmailApi.SEPARATOR_SYMBOL
+- **previous_page_token (Optional[List[str | None]], optional)**: Token for fetching the previous page of results (may be empty list). Defaults to [].
+- **messages (List[Message])**: List of retrieved message objects.

fast_gmail-1.0.0/README.md

@@ -0,0 +1,300 @@
+# Fast-gmail a simple python wrapper for gmailapi
+
+[![PyPI Downloads](https://img.shields.io/pypi/dm/fast-gmail.svg?label=PyPI%20downloads)](
+https://pypi.org/project/fast-gmail/)
+
+---
+## Functionalities:
+- Send text/html messages
+- Send messages with signature & attachments
+- Get messages with pagination
+- Filter messages
+- Get drafts
+- Edit message labels
+- Get message attachments
+
+
+## Instalation:
+`pip install fast-gmail`
+
+---
+
+## Usage:
+
+### Initialization
+- Go to https://console.developers.google.com/apis/credentials and login to correct account
+- Setup Oauth consent screen
+- Create new credentials with OAuth client ID for web or installed app
+- Set Authorized Javascript origins to http://localhost:3000/
+- Set Authorized redirect URIs to http://localhost:3000/
+- Download the credentials.json file
+- Go to Enable APIs & services and enable GmailAPI
+
+With credentials.json file downloaded we can connect to Gmail
+```
+gmail = GmailApi(
+    credentials_file_path = __path_to_credentials_json_file__,
+    port = 3000, # default is 3000 but you can use any other port IMPORTANT: if you change this default value don't forget to also changed on Authorized Javascript origins & Authorized redirect URIs
+)
+```
+
+### Send message
+``` 
+    from fast_gmail import GmailApi
+
+    messages = GmailApi().send_message(
+        sender: str,
+        to: str,
+        subject: str,
+        html: Optional[str]=None,
+        text: Optional[str]=None,
+        cc: Optional[List[str] | str]=None,
+        bcc: Optional[List[str] | str]=None,
+        attachments: Optional[List[str] | str]=None,
+        signature: bool = True
+    )
+    """Sends an email message.
+        Args:
+            sender (str): Email address of the message sender.
+            to (str): Email address of the recipient.
+            subject (str): Subject line of the email.
+            html (Optional[str], optional): HTML content of the email body. Defaults to None.
+            text (Optional[str], optional): Plain text content of the email body. Defaults to None.
+            cc (Optional[List[str] | str], optional): List of email addresses to carbon copy. Defaults to None.
+            bcc (Optional[List[str] | str], optional): List of email addresses to blind carbon copy. Defaults to None.
+            attachments (Optional[List[str] | str], optional): List of file paths to attach to the email. Defaults to None.
+            signature (bool, optional): Whether to include a signature (if configured). Defaults to True.
+        Returns:
+            Optional[Message]: An object representing the sent message, or None on error.
+    """
+```
+
+### Get messages
+```
+    messages = GmailApi().get_messages(
+        includeSpamTrash: bool = False,
+        max_results: int = 10,
+        labels: Union[List[Labels], List[str], None] = None,
+        next_page_token: str = None,
+        existing_pages: Optional[List[str] | str] = None,
+        previous_page_token: Optional[str] = None,
+        query: Union[SearchParams, str] = None,
+    )
+    """Retrieves messages from a user's mailbox.
+        Args:
+            includeSpamTrash (bool, optional): If True, includes messages from spam and trash folders. Defaults to False.
+            max_results (int, optional): Maximum number of messages to return. Defaults to MAX_RESULTS (10).
+            labels (Union[List[Labels], List[str], None], optional): List of label IDs or strings to filter by. Defaults to None (all labels).
+            next_page_token (str, optional): Page token for fetching the next page of results.
+            existing_pages (Optional[List[str] | str], optional): Used internally for pagination. Defaults to None.
+            previous_page_token (Optional[str], optional): Page token for fetching the previous page of results.
+            query (Union[SearchParams, str], optional): Search query to filter messages. Can be a string or a SearchParams object. 
+        Returns:
+            GetMessagesResponse: An object containing the retrieved messages and pagination information.
+    """
+```
+
+### Get INBOX/SPAM/TRASH messages
+```
+    messages = GmailApi().get_inbox_messages(
+        max_results: int = MAX_RESULTS,
+        next_page_token: str = None,
+        existing_pages: Optional[List[str] | str] = None,
+        previous_page_token: Optional[str] = None,
+        query: Union[SearchParams, str] = None
+    )
+
+    # helpers for spam or trash
+    messages = GmailApi().get_spam_messages()
+    messages = GmailApi().get_trash_messages()
+```
+
+### GET message
+```
+    message = GmailApi().get_message(id)
+    # returns a Message object
+```
+
+### GET attachment
+```
+    message = GmailApi().get_message(id)
+    attachment_id = None
+    attachment_name = None
+    for attacment in message.attachments:
+        attachment_id = attachment.part_id
+        attachment_name = attachment.filename
+
+    # get attachment by id
+    by_id = message.get_attachment(id=attachment_id)
+    # or by filename
+    by_name = message.get_attachment(filename=attachment_name) # returns an Attachment object
+
+    # save file to disk
+    by_id.save(filepath=f"/tmp/{attachment.filename}", overwrite=True)
+```
+
+### Message actions
+```
+    message = GmailApi().get_message(id)
+
+    # mark read or unread
+    message.toggle_read_unread
+    # or
+    message.mark_as_read
+    # or
+    message.mark_as_unread
+
+    # spam
+    message.toggle_spam
+    # or
+    message.mark_spam
+    message.mark_not_spam
+
+    # trash
+    message.toggle_trash
+    # or
+    message.move_to_trash
+    message.move_from_trash
+
+    # starred
+    message.toggle_starred
+    message.mark_starred
+    message.mark_not_starred
+
+    #important
+    message.toggle_important
+    message.mark_important
+    message.mark_not_important
+
+    # other properties
+    message.body
+    message.html
+    message.plain
+    message.recipient
+    message.subject
+    message.sender
+    message.snippet
+    message.is_starred
+    message.is_important
+    message.is_spam
+    message.is_unread
+    ...
+
+```
+
+---
+
+## Classes:
+
+### class GmailApi:
+###### Attributes:
+
+- **credentials (Optional[Credentials])**: Stores user credentials (OAuth tokens) for accessing Gmail.
+- **google_service (GoogleService)**: An instance of GoogleService used for making API requests.
+- **max_results (int)**: Maximum number of messages to retrieve per request (default 10).
+- **SEPARATOR_SYMBOL (str)**: String used for separating page tokens during pagination.
+- **profile_data (Optional[GmailProfile])**: Caches the user's Gmail profile information.
+
+###### Constructor (__init__):
+- Initializes the GmailApi object.
+- Reads credentials from token and credentials files.
+- Handles refreshing expired tokens.
+- Creates a GoogleService instance for making API calls.
+
+###### Methods:
+###### Message Retrieval:
+- **get_message(id: str)-> Optional[Message]**: Retrieves a message by its ID.
+- **get_draft(id: str)-> Optional[Message]**: Retrieves a draft by its ID.
+###### Message Sending:
+- **send_message(sender, to, subject, ...)-> Optional[Message]**: Sends an email message with various options (text, HTML, attachments, signature).
+###### Inbox Management:
+- **get_inbox_messages()-> GetMessagesResponse**: Retrieves messages from the inbox.
+Similar methods exist for getting trash, spam, and all messages with various filtering options.
+###### Drafts Management:
+- **get_draft_messages()**: Retrieves draft messages.
+###### Attachment Management:
+- **get_attachment(message_id: str, attachment_id: str) -> Optional[MessagePartBody]**: Retrieves an attachment from a message.
+###### Profile and Label Management:
+- **labels**: Returns a list of user labels.
+- **profile**: Retrieves and caches the user's Gmail profile information.
+
+Overall, this code provides a well-structured and functional interface for interacting with Gmail using the Gmail API.
+
+---
+
+### class Message:
+###### Properties:
+- **id**: Unique identifier for the message.
+- **snippet**: Shortened summary of the message content.
+- **threadId**: Thread ID that groups related messages together.
+- **historyId**: Unique identifier for a specific message history change.
+- **sizeEstimate**: Approximate size of the message in bytes.
+- **internalDate**: Internal timestamp representing when the message was created.
+- **payload**: Object of type MessagePart containing the parsed content of the message body and attachments.
+- **raw**: Optional property containing the raw email data (if available).
+- **labelIds**: List of label IDs associated with the message.
+- **labels**: List of GmailLabel objects representing the message's labels (fetched on demand).
+
+###### Additional Message Properties:
+- **message_headers**: Returns a list of MessageHeader objects from the message's payload (if available).
+- **body**: Returns the message body content (combines plain text and HTML if both exist).
+- **html**: Returns the HTML content of the message body (if available).
+- **plain**: Returns the plain text content of the message body (if available).
+- **alternative**: Returns the text content of the most appropriate alternative part (if message uses multipart/alternative).
+- **recipient**: Extracts the recipient's email address from the "To" header (if available).
+- **message_id**: Extracts the message ID from the message headers (if available).
+- **subject**: Extracts the subject line from the message headers (if available).
+- **sender**: Extracts the sender's email address from the "From" header (if available).
+- **has_attachments**: Checks if the message or its nested parts contain attachments.
+- **attachments**: Returns a list of Attachment objects for all attachments within the message.
+- **is_unread, is_starred, is_important, etc.**: Boolean properties indicating the message's label status (unread, starred, important, spam, draft, trash).
+- **created_date**: Converts the internalDate to a datetime object representing the message creation time.
+- **date**: Parses the "Received" or "Date" header to get the message delivery date (if available).
+- **date_string**: Formats the delivery date according to a specified format string (defaults to "%a, %d %b %Y %H:%M:%S %z").
+
+---
+
+###### Methods:
+- **mark_as_read, mark_as_unread**: Toggles the unread flag for the message.
+- **toogle_read_unread**: Shortcut to toggle the unread flag based on the current state.
+- **mark_spam, mark_not_spam**: Toggles the spam label for the message.
+- **toggle_spam**: Shortcut to toggle the spam label based on the current state.
+- **move_to_trash, move_from_trash**: Toggles the trash label for the message.
+- **toggle_trash**: Shortcut to toggle the trash label based on the current state.
+- **mark_important, mark_not_important**: Toggles the important label for the message.
+- **toggle_important**: Shortcut to toggle the important label based on the current state.
+- **mark_starred, mark_not_starred**: Toggles the starred label for the message.
+- **toggle_starred**: Shortcut to toggle the starred label based on the current state.
+- **get_attachment(filename=None, id=None)**: Retrieves an attachment by filename or internal part ID.
+- **get_labels**: Fetches and returns a list of GmailLabel objects for all labels associated with the message.
+- **add_label(label), add_labels(labels)**: Adds labels to the message.
+- **remove_label(label), remove_labels(labels)**: Removes labels from the message.
+- **modify_labels(labels_to_add=None, labels_to_remove=None)**: Updates message labels by adding and/or removing labels.
+
+Overall, this Message class provides a comprehensive way to access and manage individual email messages within a Gmail account. It allows you to retrieve message details, content, attachments, labels, and perform various actions like marking as read/unread, starring, labeling, and trash management.
+
+---
+
+### class Attachment:
+###### Properties:
+- **filename (str)**: This attribute stores the filename of the attachment.
+- **mimeType (str)**: This attribute stores the MIME type of the attachment content, which specifies the format of the data (e.g., image/jpeg, text/plain).
+- **part_id (str)**: This attribute stores the internal identifier for the attachment within the message parts. This ID is used to download the attachment using the Gmail API.
+- **google_service (GoogleService)**: This attribute holds a reference to the GoogleService object used for downloading the attachment. This object likely encapsulates authentication and communication details with the Gmail API.
+- **id (Optional[str])**: This optional attribute stores the ID of the attachment generated by Gmail after a message is fetched using the .get() method. This ID might change for the same attachment across different fetches.
+- **data (Optional[str])**: This optional attribute stores the Base64 encoded content of the attachment data downloaded from the API.
+
+###### Methods:
+- **download() -> None**: This method downloads the attachment data from the Gmail API if it hasn't been downloaded already. It raises exceptions for errors like missing message ID or HTTP errors during download.
+- **save(filepath: Optional[str] = None, overwrite: bool = False) -> None**: This method saves the attachment data to a file. It allows specifying the filepath and whether to overwrite existing files. It raises an error if the file already exists and overwrite is set to False.
+
+Overall, the Attachment class provides functionality to manage attachments associated with Gmail messages. It handles downloading attachments from the API, storing downloaded data, and saving them to local files.
+
+---
+
+### class GetMessagesResponse:
+###### Attributes:
+- **next_page_token (Optional[str], optional)**: Token for fetching the next page of results. Defaults to None.
+- **existing_pages (Optional[str], optional)**: Used internally for pagination. Defaults to None. List like string of page tokens separated by GmailApi.SEPARATOR_SYMBOL
+- **previous_page_token (Optional[List[str | None]], optional)**: Token for fetching the previous page of results (may be empty list). Defaults to [].
+- **messages (List[Message])**: List of retrieved message objects.

fast_gmail-1.0.0/fast_gmail/fast_gmail.egg-info/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.1
+Name: fast_gmail
+Version: 1.0.0
+Summary: GmailApi wrapper
+Home-page: https://github.com/aleti1/fast_gmail
+Author: Aleti
+Author-email: aleti.open.source@gmail.com
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-api-python-client==2.125.0
+Requires-Dist: google-auth-httplib2==0.2.0
+Requires-Dist: google-auth-oauthlib==1.2.0
+Requires-Dist: typing-extensions==4.11.0
+
+# Fast-gmail a simple python wrapper for gmailapi
+
+[![PyPI Downloads](https://img.shields.io/pypi/dm/fast-gmail.svg?label=PyPI%20downloads)](
+https://pypi.org/project/fast-gmail/)
+
+---
+## Functionalities:
+- Send text/html messages
+- Send messages with signature & attachments
+- Get messages with pagination
+- Filter messages
+- Get drafts
+- Edit message labels
+- Get message attachments
+
+
+## Instalation:
+`pip install fast-gmail`
+
+---
+
+## Usage:
+
+### Initialization
+- Go to https://console.developers.google.com/apis/credentials and login to correct account
+- Setup Oauth consent screen
+- Create new credentials with OAuth client ID for web or installed app
+- Set Authorized Javascript origins to http://localhost:3000/
+- Set Authorized redirect URIs to http://localhost:3000/
+- Download the credentials.json file
+- Go to Enable APIs & services and enable GmailAPI
+
+With credentials.json file downloaded we can connect to Gmail
+```
+gmail = GmailApi(
+    credentials_file_path = __path_to_credentials_json_file__,
+    port = 3000, # default is 3000 but you can use any other port IMPORTANT: if you change this default value don't forget to also changed on Authorized Javascript origins & Authorized redirect URIs
+)
+```
+
+### Send message
+``` 
+    from fast_gmail import GmailApi
+
+    messages = GmailApi().send_message(
+        sender: str,
+        to: str,
+        subject: str,
+        html: Optional[str]=None,
+        text: Optional[str]=None,
+        cc: Optional[List[str] | str]=None,
+        bcc: Optional[List[str] | str]=None,
+        attachments: Optional[List[str] | str]=None,
+        signature: bool = True
+    )
+    """Sends an email message.
+        Args:
+            sender (str): Email address of the message sender.
+            to (str): Email address of the recipient.
+            subject (str): Subject line of the email.
+            html (Optional[str], optional): HTML content of the email body. Defaults to None.
+            text (Optional[str], optional): Plain text content of the email body. Defaults to None.
+            cc (Optional[List[str] | str], optional): List of email addresses to carbon copy. Defaults to None.
+            bcc (Optional[List[str] | str], optional): List of email addresses to blind carbon copy. Defaults to None.
+            attachments (Optional[List[str] | str], optional): List of file paths to attach to the email. Defaults to None.
+            signature (bool, optional): Whether to include a signature (if configured). Defaults to True.
+        Returns:
+            Optional[Message]: An object representing the sent message, or None on error.
+    """
+```
+
+### Get messages
+```
+    messages = GmailApi().get_messages(
+        includeSpamTrash: bool = False,
+        max_results: int = 10,
+        labels: Union[List[Labels], List[str], None] = None,
+        next_page_token: str = None,
+        existing_pages: Optional[List[str] | str] = None,
+        previous_page_token: Optional[str] = None,
+        query: Union[SearchParams, str] = None,
+    )
+    """Retrieves messages from a user's mailbox.
+        Args:
+            includeSpamTrash (bool, optional): If True, includes messages from spam and trash folders. Defaults to False.
+            max_results (int, optional): Maximum number of messages to return. Defaults to MAX_RESULTS (10).
+            labels (Union[List[Labels], List[str], None], optional): List of label IDs or strings to filter by. Defaults to None (all labels).
+            next_page_token (str, optional): Page token for fetching the next page of results.
+            existing_pages (Optional[List[str] | str], optional): Used internally for pagination. Defaults to None.
+            previous_page_token (Optional[str], optional): Page token for fetching the previous page of results.
+            query (Union[SearchParams, str], optional): Search query to filter messages. Can be a string or a SearchParams object. 
+        Returns:
+            GetMessagesResponse: An object containing the retrieved messages and pagination information.
+    """
+```
+
+### Get INBOX/SPAM/TRASH messages
+```
+    messages = GmailApi().get_inbox_messages(
+        max_results: int = MAX_RESULTS,
+        next_page_token: str = None,
+        existing_pages: Optional[List[str] | str] = None,
+        previous_page_token: Optional[str] = None,
+        query: Union[SearchParams, str] = None
+    )
+
+    # helpers for spam or trash
+    messages = GmailApi().get_spam_messages()
+    messages = GmailApi().get_trash_messages()
+```
+
+### GET message
+```
+    message = GmailApi().get_message(id)
+    # returns a Message object
+```
+
+### GET attachment
+```
+    message = GmailApi().get_message(id)
+    attachment_id = None
+    attachment_name = None
+    for attacment in message.attachments:
+        attachment_id = attachment.part_id
+        attachment_name = attachment.filename
+
+    # get attachment by id
+    by_id = message.get_attachment(id=attachment_id)
+    # or by filename
+    by_name = message.get_attachment(filename=attachment_name) # returns an Attachment object
+
+    # save file to disk
+    by_id.save(filepath=f"/tmp/{attachment.filename}", overwrite=True)
+```
+
+### Message actions
+```
+    message = GmailApi().get_message(id)
+
+    # mark read or unread
+    message.toggle_read_unread
+    # or
+    message.mark_as_read
+    # or
+    message.mark_as_unread
+
+    # spam
+    message.toggle_spam
+    # or
+    message.mark_spam
+    message.mark_not_spam
+
+    # trash
+    message.toggle_trash
+    # or
+    message.move_to_trash
+    message.move_from_trash
+
+    # starred
+    message.toggle_starred
+    message.mark_starred
+    message.mark_not_starred
+
+    #important
+    message.toggle_important
+    message.mark_important
+    message.mark_not_important
+
+    # other properties
+    message.body
+    message.html
+    message.plain
+    message.recipient
+    message.subject
+    message.sender
+    message.snippet
+    message.is_starred
+    message.is_important
+    message.is_spam
+    message.is_unread
+    ...
+
+```
+
+---
+
+## Classes:
+
+### class GmailApi:
+###### Attributes:
+
+- **credentials (Optional[Credentials])**: Stores user credentials (OAuth tokens) for accessing Gmail.
+- **google_service (GoogleService)**: An instance of GoogleService used for making API requests.
+- **max_results (int)**: Maximum number of messages to retrieve per request (default 10).
+- **SEPARATOR_SYMBOL (str)**: String used for separating page tokens during pagination.
+- **profile_data (Optional[GmailProfile])**: Caches the user's Gmail profile information.
+
+###### Constructor (__init__):
+- Initializes the GmailApi object.
+- Reads credentials from token and credentials files.
+- Handles refreshing expired tokens.
+- Creates a GoogleService instance for making API calls.
+
+###### Methods:
+###### Message Retrieval:
+- **get_message(id: str)-> Optional[Message]**: Retrieves a message by its ID.
+- **get_draft(id: str)-> Optional[Message]**: Retrieves a draft by its ID.
+###### Message Sending:
+- **send_message(sender, to, subject, ...)-> Optional[Message]**: Sends an email message with various options (text, HTML, attachments, signature).
+###### Inbox Management:
+- **get_inbox_messages()-> GetMessagesResponse**: Retrieves messages from the inbox.
+Similar methods exist for getting trash, spam, and all messages with various filtering options.
+###### Drafts Management:
+- **get_draft_messages()**: Retrieves draft messages.
+###### Attachment Management:
+- **get_attachment(message_id: str, attachment_id: str) -> Optional[MessagePartBody]**: Retrieves an attachment from a message.
+###### Profile and Label Management:
+- **labels**: Returns a list of user labels.
+- **profile**: Retrieves and caches the user's Gmail profile information.
+
+Overall, this code provides a well-structured and functional interface for interacting with Gmail using the Gmail API.
+
+---
+
+### class Message:
+###### Properties:
+- **id**: Unique identifier for the message.
+- **snippet**: Shortened summary of the message content.
+- **threadId**: Thread ID that groups related messages together.
+- **historyId**: Unique identifier for a specific message history change.
+- **sizeEstimate**: Approximate size of the message in bytes.
+- **internalDate**: Internal timestamp representing when the message was created.
+- **payload**: Object of type MessagePart containing the parsed content of the message body and attachments.
+- **raw**: Optional property containing the raw email data (if available).
+- **labelIds**: List of label IDs associated with the message.
+- **labels**: List of GmailLabel objects representing the message's labels (fetched on demand).
+
+###### Additional Message Properties:
+- **message_headers**: Returns a list of MessageHeader objects from the message's payload (if available).
+- **body**: Returns the message body content (combines plain text and HTML if both exist).
+- **html**: Returns the HTML content of the message body (if available).
+- **plain**: Returns the plain text content of the message body (if available).
+- **alternative**: Returns the text content of the most appropriate alternative part (if message uses multipart/alternative).
+- **recipient**: Extracts the recipient's email address from the "To" header (if available).
+- **message_id**: Extracts the message ID from the message headers (if available).
+- **subject**: Extracts the subject line from the message headers (if available).
+- **sender**: Extracts the sender's email address from the "From" header (if available).
+- **has_attachments**: Checks if the message or its nested parts contain attachments.
+- **attachments**: Returns a list of Attachment objects for all attachments within the message.
+- **is_unread, is_starred, is_important, etc.**: Boolean properties indicating the message's label status (unread, starred, important, spam, draft, trash).
+- **created_date**: Converts the internalDate to a datetime object representing the message creation time.
+- **date**: Parses the "Received" or "Date" header to get the message delivery date (if available).
+- **date_string**: Formats the delivery date according to a specified format string (defaults to "%a, %d %b %Y %H:%M:%S %z").
+
+---
+
+###### Methods:
+- **mark_as_read, mark_as_unread**: Toggles the unread flag for the message.
+- **toogle_read_unread**: Shortcut to toggle the unread flag based on the current state.
+- **mark_spam, mark_not_spam**: Toggles the spam label for the message.
+- **toggle_spam**: Shortcut to toggle the spam label based on the current state.
+- **move_to_trash, move_from_trash**: Toggles the trash label for the message.
+- **toggle_trash**: Shortcut to toggle the trash label based on the current state.
+- **mark_important, mark_not_important**: Toggles the important label for the message.
+- **toggle_important**: Shortcut to toggle the important label based on the current state.
+- **mark_starred, mark_not_starred**: Toggles the starred label for the message.
+- **toggle_starred**: Shortcut to toggle the starred label based on the current state.
+- **get_attachment(filename=None, id=None)**: Retrieves an attachment by filename or internal part ID.
+- **get_labels**: Fetches and returns a list of GmailLabel objects for all labels associated with the message.
+- **add_label(label), add_labels(labels)**: Adds labels to the message.
+- **remove_label(label), remove_labels(labels)**: Removes labels from the message.
+- **modify_labels(labels_to_add=None, labels_to_remove=None)**: Updates message labels by adding and/or removing labels.
+
+Overall, this Message class provides a comprehensive way to access and manage individual email messages within a Gmail account. It allows you to retrieve message details, content, attachments, labels, and perform various actions like marking as read/unread, starring, labeling, and trash management.
+
+---
+
+### class Attachment:
+###### Properties:
+- **filename (str)**: This attribute stores the filename of the attachment.
+- **mimeType (str)**: This attribute stores the MIME type of the attachment content, which specifies the format of the data (e.g., image/jpeg, text/plain).
+- **part_id (str)**: This attribute stores the internal identifier for the attachment within the message parts. This ID is used to download the attachment using the Gmail API.
+- **google_service (GoogleService)**: This attribute holds a reference to the GoogleService object used for downloading the attachment. This object likely encapsulates authentication and communication details with the Gmail API.
+- **id (Optional[str])**: This optional attribute stores the ID of the attachment generated by Gmail after a message is fetched using the .get() method. This ID might change for the same attachment across different fetches.
+- **data (Optional[str])**: This optional attribute stores the Base64 encoded content of the attachment data downloaded from the API.
+
+###### Methods:
+- **download() -> None**: This method downloads the attachment data from the Gmail API if it hasn't been downloaded already. It raises exceptions for errors like missing message ID or HTTP errors during download.
+- **save(filepath: Optional[str] = None, overwrite: bool = False) -> None**: This method saves the attachment data to a file. It allows specifying the filepath and whether to overwrite existing files. It raises an error if the file already exists and overwrite is set to False.
+
+Overall, the Attachment class provides functionality to manage attachments associated with Gmail messages. It handles downloading attachments from the API, storing downloaded data, and saving them to local files.
+
+---
+
+### class GetMessagesResponse:
+###### Attributes:
+- **next_page_token (Optional[str], optional)**: Token for fetching the next page of results. Defaults to None.
+- **existing_pages (Optional[str], optional)**: Used internally for pagination. Defaults to None. List like string of page tokens separated by GmailApi.SEPARATOR_SYMBOL
+- **previous_page_token (Optional[List[str | None]], optional)**: Token for fetching the previous page of results (may be empty list). Defaults to [].
+- **messages (List[Message])**: List of retrieved message objects.

fast_gmail-1.0.0/fast_gmail/fast_gmail.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+setup.py
+fast_gmail/fast_gmail.egg-info/PKG-INFO
+fast_gmail/fast_gmail.egg-info/SOURCES.txt
+fast_gmail/fast_gmail.egg-info/dependency_links.txt
+fast_gmail/fast_gmail.egg-info/requires.txt
+fast_gmail/fast_gmail.egg-info/top_level.txt

fast_gmail-1.0.0/fast_gmail/fast_gmail.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fast_gmail-1.0.0/fast_gmail/fast_gmail.egg-info/requires.txt

@@ -0,0 +1,4 @@
+google-api-python-client==2.125.0
+google-auth-httplib2==0.2.0
+google-auth-oauthlib==1.2.0
+typing-extensions==4.11.0

fast_gmail-1.0.0/fast_gmail/fast_gmail.egg-info/top_level.txt

@@ -0,0 +1 @@
+

fast_gmail-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fast_gmail-1.0.0/setup.py

@@ -0,0 +1,35 @@
+from setuptools import setup
+from setuptools import find_packages
+
+with open("README.md", "r") as f:
+    long_descrition=f.read()
+
+setup(
+    name="fast_gmail",
+    version="1.0.0",
+    description="GmailApi wrapper",
+    long_description=long_descrition,  # Load description from README
+    long_description_content_type='text/markdown',
+    author="Aleti",
+    author_email="aleti.open.source@gmail.com",
+    url="https://github.com/aleti1/fast_gmail",
+    license="MIT",
+    requires=[],
+    package_dir={"":"fast_gmail"},
+    packages=find_packages(where="fast_gmail"),
+    python_requires=">=3.10",
+    install_requires=[
+        "google-api-python-client == 2.125.0",
+        "google-auth-httplib2 == 0.2.0",
+        "google-auth-oauthlib == 1.2.0",
+        "typing-extensions == 4.11.0"
+    ],    
+    classifiers=[
+        'Development Status :: 5 - Production/Stable',
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+)