ms-graph-toolbox 0.1.0__tar.gz

ms_graph_toolbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 runway28R
+
+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.

ms_graph_toolbox-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: ms-graph-toolbox
+Version: 0.1.0
+Summary: A lightweight Python wrapper around Microsoft Graph for email, users, and SharePoint operations.
+Author: runway28R
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/runway28R/ms-graph-toolbox
+Project-URL: Source, https://github.com/runway28R/ms-graph-toolbox
+Project-URL: Issues, https://github.com/runway28R/ms-graph-toolbox/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: msal>=1.27.0
+Dynamic: license-file
+
+# Microsoft Graph Toolbox
+
+A lightweight Python wrapper around Microsoft Graph for sending email, retrieving users, and working with SharePoint files.
+
+## Features
+
+- Authenticate with Microsoft Graph using Microsoft Entra ID application credentials
+- Send email messages
+- Retrieve users from Microsoft Graph
+- List SharePoint sites and document libraries
+- Browse folders and upload files to SharePoint
+
+## Requirements
+
+- Python 3.12 or newer
+- A Microsoft Entra ID application registration
+- Microsoft Graph API permissions
+- A Microsoft 365 account with access to the required resources
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install ms-graph-toolbox
+```
+
+## Authentication
+
+The package uses application credentials:
+
+- Client ID
+- Client secret
+- Tenant ID
+
+Make sure the application has the required Microsoft Graph permissions and that administrator consent has been granted where necessary.
+
+## Basic Usage
+
+```python
+import logging
+import os
+
+from ms_graph_toolbox.ms_graph_toolbox import ms_graph_toolbox
+
+logger = logging.getLogger(__name__)
+
+graph = ms_graph_toolbox(
+    client_id=os.environ["MS_GRAPH_CLIENT_ID"],
+    client_secret=os.environ["MS_GRAPH_CLIENT_SECRET"],
+    tenant_id=os.environ["MS_GRAPH_TENANT_ID"],
+    logger=logger,
+)
+```
+
+The object automatically obtains an access token that is used by the other package functions.
+
+## Sending Email
+
+```python
+from ms_graph_toolbox.graph_email import send_email
+
+send_email(
+    gph_object=graph,
+    subject="Test message",
+    content_type="Text",
+    body="This message was sent using Microsoft Graph.",
+    sender="sender@example.com",
+    to_field="recipient@example.com",
+)
+```
+
+Additional options include carbon-copy recipients, blind-carbon-copy recipients, message priority, and file attachments.
+
+Multiple recipients can be provided as a comma-separated string:
+
+```python
+send_email(
+    gph_object=graph,
+    subject="Team update",
+    content_type="Text",
+    body="This message was sent to multiple recipients.",
+    sender="sender@example.com",
+    to_field="first@example.com, second@example.com",
+)
+```
+
+## Retrieving Users
+
+```python
+from ms_graph_toolbox.graph_users import get_users
+
+users = get_users(graph)
+
+for user in users:
+    print(user)
+```
+
+You can also filter the results by name, title, email address, alias, company, or selected fields:
+
+```python
+users = get_users(
+    graph,
+    select_data=["displayName", "mail", "jobTitle"],
+    search_name="Alex",
+)
+```
+
+## SharePoint Operations
+
+SharePoint functionality is available through the `graph_sharepoint` class:
+
+```python
+from ms_graph_toolbox.graph_sharepoint import graph_sharepoint
+
+sharepoint = graph_sharepoint(
+    access_token=graph.access_token,
+    logger=logger,
+)
+```
+
+The SharePoint tools support:
+
+- Finding a SharePoint site
+- Listing document libraries
+- Browsing folder contents
+- Uploading files
+
+See the [examples](https://github.com/runway28R/ms-graph-toolbox/tree/main/examples) directory for complete SharePoint usage examples.
+
+## Examples
+
+The repository contains complete examples for:
+
+- Sending email
+- Retrieving users
+- Uploading files to SharePoint
+
+The examples are available in the [examples](https://github.com/runway28R/ms-graph-toolbox/tree/main/examples) directory.
+
+## Configuration
+
+For local development, set these environment variables before running the examples.
+
+### PowerShell
+
+```powershell
+$env:MS_GRAPH_CLIENT_ID = "your-client-id"
+$env:MS_GRAPH_CLIENT_SECRET = "your-client-secret"
+$env:MS_GRAPH_TENANT_ID = "your-tenant-id"
+```
+
+### Bash
+
+```bash
+export MS_GRAPH_CLIENT_ID="your-client-id"
+export MS_GRAPH_CLIENT_SECRET="your-client-secret"
+export MS_GRAPH_TENANT_ID="your-tenant-id"
+```
+
+Do not commit client secrets or other credentials to the repository.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

ms_graph_toolbox-0.1.0/README.md

@@ -0,0 +1,165 @@
+# Microsoft Graph Toolbox
+
+A lightweight Python wrapper around Microsoft Graph for sending email, retrieving users, and working with SharePoint files.
+
+## Features
+
+- Authenticate with Microsoft Graph using Microsoft Entra ID application credentials
+- Send email messages
+- Retrieve users from Microsoft Graph
+- List SharePoint sites and document libraries
+- Browse folders and upload files to SharePoint
+
+## Requirements
+
+- Python 3.12 or newer
+- A Microsoft Entra ID application registration
+- Microsoft Graph API permissions
+- A Microsoft 365 account with access to the required resources
+
+## Installation
+
+Install the package from PyPI:
+
+```bash
+pip install ms-graph-toolbox
+```
+
+## Authentication
+
+The package uses application credentials:
+
+- Client ID
+- Client secret
+- Tenant ID
+
+Make sure the application has the required Microsoft Graph permissions and that administrator consent has been granted where necessary.
+
+## Basic Usage
+
+```python
+import logging
+import os
+
+from ms_graph_toolbox.ms_graph_toolbox import ms_graph_toolbox
+
+logger = logging.getLogger(__name__)
+
+graph = ms_graph_toolbox(
+    client_id=os.environ["MS_GRAPH_CLIENT_ID"],
+    client_secret=os.environ["MS_GRAPH_CLIENT_SECRET"],
+    tenant_id=os.environ["MS_GRAPH_TENANT_ID"],
+    logger=logger,
+)
+```
+
+The object automatically obtains an access token that is used by the other package functions.
+
+## Sending Email
+
+```python
+from ms_graph_toolbox.graph_email import send_email
+
+send_email(
+    gph_object=graph,
+    subject="Test message",
+    content_type="Text",
+    body="This message was sent using Microsoft Graph.",
+    sender="sender@example.com",
+    to_field="recipient@example.com",
+)
+```
+
+Additional options include carbon-copy recipients, blind-carbon-copy recipients, message priority, and file attachments.
+
+Multiple recipients can be provided as a comma-separated string:
+
+```python
+send_email(
+    gph_object=graph,
+    subject="Team update",
+    content_type="Text",
+    body="This message was sent to multiple recipients.",
+    sender="sender@example.com",
+    to_field="first@example.com, second@example.com",
+)
+```
+
+## Retrieving Users
+
+```python
+from ms_graph_toolbox.graph_users import get_users
+
+users = get_users(graph)
+
+for user in users:
+    print(user)
+```
+
+You can also filter the results by name, title, email address, alias, company, or selected fields:
+
+```python
+users = get_users(
+    graph,
+    select_data=["displayName", "mail", "jobTitle"],
+    search_name="Alex",
+)
+```
+
+## SharePoint Operations
+
+SharePoint functionality is available through the `graph_sharepoint` class:
+
+```python
+from ms_graph_toolbox.graph_sharepoint import graph_sharepoint
+
+sharepoint = graph_sharepoint(
+    access_token=graph.access_token,
+    logger=logger,
+)
+```
+
+The SharePoint tools support:
+
+- Finding a SharePoint site
+- Listing document libraries
+- Browsing folder contents
+- Uploading files
+
+See the [examples](https://github.com/runway28R/ms-graph-toolbox/tree/main/examples) directory for complete SharePoint usage examples.
+
+## Examples
+
+The repository contains complete examples for:
+
+- Sending email
+- Retrieving users
+- Uploading files to SharePoint
+
+The examples are available in the [examples](https://github.com/runway28R/ms-graph-toolbox/tree/main/examples) directory.
+
+## Configuration
+
+For local development, set these environment variables before running the examples.
+
+### PowerShell
+
+```powershell
+$env:MS_GRAPH_CLIENT_ID = "your-client-id"
+$env:MS_GRAPH_CLIENT_SECRET = "your-client-secret"
+$env:MS_GRAPH_TENANT_ID = "your-tenant-id"
+```
+
+### Bash
+
+```bash
+export MS_GRAPH_CLIENT_ID="your-client-id"
+export MS_GRAPH_CLIENT_SECRET="your-client-secret"
+export MS_GRAPH_TENANT_ID="your-tenant-id"
+```
+
+Do not commit client secrets or other credentials to the repository.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

ms_graph_toolbox-0.1.0/ms_graph_toolbox/graph_email.py

@@ -0,0 +1,173 @@
+import requests
+import base64
+import os
+import mimetypes
+
+
+def send_email(gph_object, 
+               subject, 
+               content_type, 
+               body, 
+               sender, 
+               to_field, 
+               cc_field=None, 
+               bcc_field=None, 
+               priority="Normal", 
+               attachments=None):
+    """
+    Send an email using Microsoft Graph on behalf of `sender`.
+
+    Parameters:
+        logger: logger instance to record actions (debug/error).
+        subject: email subject string.
+        content_type: one of 'text', 'html', 'text/plain', 'text/html', etc.
+        body: email body string.
+        to_field, cc_field, bcc_field: comma-separated recipient strings (e.g. "a@x.com, b@y.com").
+        priority: message importance, e.g. "Low", "Normal", "High".
+        attachments: optional list of attachment descriptors. Each descriptor may be:
+            - {'path': 'C:\\full\\path\\file.pdf', 'name': 'file.pdf', 'content_type': 'application/pdf', 'inline': False}
+            - {'content_bytes': b'...', 'name': 'image.png', 'content_type': 'image/png', 'inline': True, 'content_id': 'img1'}
+            For inline images set 'inline': True and reference them in an HTML body as <img src="cid:content_id">.
+            If content_type not provided it will be guessed from the filename.
+            The code will base64-encode file contents as required by Graph.
+
+    Returns:
+        0 on success (202 response), 1 on exception, 2 if no access token, 3 on non-202 HTTP response.
+    """
+    try:
+        # Ensure we have an access token before attempting to send
+        if not gph_object.access_token:
+            gph_object.logger.error("Invalid Access Token, email cannot be sent!")
+            return 2
+
+        # Parse recipient fields into Graph-friendly lists
+        to_recipients = parse_recipients(to_field)
+        cc_recipients = parse_recipients(cc_field)
+        bcc_recipients = parse_recipients(bcc_field)
+
+        # Normalize content type to one of Graph's expected values ("Text" or "HTML"), use "Text" as default
+        valid_types = {"text": "Text", "plain": "Text", "html": "HTML", "text/plain": "Text", "text/html": "HTML"}
+        content_type_normalized = valid_types.get(content_type.strip().lower(), "Text")
+
+        # Process attachments and if any contain inline items but the body is not HTML, log a warning
+        inline_found = False
+        attachments_payload = []
+        if attachments:
+            # Process all attachments in one pass
+            attachments_payload = [
+                att for desc in attachments 
+                if (att := build_attachment(descriptor=desc, logger=gph_object.logger)) is not None
+            ]
+            
+            # Check for inline attachments
+            inline_found = any(att.get("isInline") for att in attachments_payload)
+
+            # Log warning if inline attachments found with non-HTML content
+            if inline_found and content_type_normalized != "HTML":
+                gph_object.logger.warning("Inline attachments present but body is not HTML. Inline images require HTML body and <img src=\"cid:contentId\"> references.")
+
+        # Build sendMail endpoint for the configured sender user
+        endpoint = f"https://graph.microsoft.com/v1.0/users/{sender}/sendMail"
+
+        # Compose message payload according to Graph sendMail schema
+        email_msg = {
+            "message": {
+                "subject": subject,
+                "body": {
+                    "contentType": content_type_normalized,
+                    "content": body
+                },
+                "toRecipients": to_recipients,
+                "importance": priority
+            }
+        }
+
+        # Attach cc/bcc only if provided
+        if cc_recipients:
+            email_msg["message"]["ccRecipients"] = cc_recipients
+        if bcc_recipients:
+            email_msg["message"]["bccRecipients"] = bcc_recipients
+
+        # Attach attachments if any
+        if attachments_payload:
+            email_msg["message"]["attachments"] = attachments_payload
+
+        # Set authorization header with Bearer token
+        headers = {"Authorization": f"Bearer {gph_object.access_token}", "Content-Type": "application/json"}
+        gph_object.logger.debug(f"Sending email using MS Graph from {sender}")
+        response = requests.post(endpoint, headers=headers, json=email_msg)
+
+        # 202 Accepted indicates Graph accepted the send request
+        if response.status_code == 202:
+            gph_object.logger.debug("Sending successful!")
+            return 0
+        else:
+            # Log status and response body for debugging failures
+            gph_object.logger.error(f"Sending Failed: {response.status_code}, {response.text}")
+            return 3
+    except Exception as e:
+        # Any unexpected exception during send is logged
+        gph_object.logger.error(f"Sending Failed: {e}")
+        return 1
+
+
+# Convert a comma-separated string of addresses into the Graph recipient JSON format.
+def parse_recipients(field):
+    if not field:
+        return []
+    return [{"emailAddress": {"address": addr.strip()}} for addr in field.split(",") if addr.strip()]
+
+
+# Build Graph attachment payloads from descriptors
+def build_attachment(descriptor, logger):
+    """
+    Accepts either:
+        - {'path': 'C:\\file', ...}
+        - {'content_bytes': b'...', ...}
+    Returns a dict suitable for Graph message attachments.
+    """
+    try:
+        # Basic check
+        if "path" not in descriptor and "content_bytes" not in descriptor:
+            logger.error(f"build_attachment failed: Descriptor missing 'path' or 'content_bytes': {descriptor}")
+            return None
+        # Determine name
+        name = descriptor.get("name")
+        content_type_guess = None
+
+        # Load bytes from file path if provided
+        if "path" in descriptor and descriptor["path"]:
+            path = descriptor["path"]
+            with open(path, "rb") as f:
+                data = f.read()
+            if not name:
+                name = os.path.basename(path)
+            content_type_guess = mimetypes.guess_type(path)[0]
+        elif "content_bytes" in descriptor and descriptor["content_bytes"] is not None:
+            data = descriptor["content_bytes"]
+            if isinstance(data, str):
+                data = data.encode("utf-8")
+
+        # Determine contentType
+        content_type = descriptor.get("content_type") or content_type_guess or "application/octet-stream"
+
+        # Base64 encode content
+        content_bytes_b64 = base64.b64encode(data).decode("utf-8")
+
+        # Build attachment object (fileAttachment)
+        attachment = {
+            "@odata.type": "#microsoft.graph.fileAttachment",
+            "name": name or "attachment",
+            "contentType": content_type,
+            "contentBytes": content_bytes_b64
+        }
+
+        # Inline settings for images
+        if descriptor.get("inline"):
+            attachment["isInline"] = True
+            # contentId is used as cid reference in HTML body: <img src="cid:contentId">
+            attachment["contentId"] = descriptor.get("content_id") or (name or "inline")
+        return attachment
+    except Exception as e:
+        logger.error(f"build_attachment: failed for descriptor {descriptor}: {e}")
+        return None

ms_graph_toolbox-0.1.0/ms_graph_toolbox/graph_sharepoint.py

@@ -0,0 +1,109 @@
+from urllib.parse import quote
+import pathlib as pl
+import requests
+
+
+class graph_sharepoint:
+    def __init__(self, access_token:str, logger):
+        self.access_token = access_token
+        self.logger = logger
+
+
+    def get_site_id(self, site_url:str):
+        # Request site ID
+        try:
+            full_url = f'https://graph.microsoft.com/v1.0/sites/{site_url}'
+            response = requests.get(full_url, 
+                                    headers={'Authorization': f'Bearer {self.access_token}'})
+            self.logger.debug(f"get_site_id response: {response.status_code} - {response.text}")
+            return response.json().get('id')  # Return the site ID
+        except Exception as e:
+            self.logger.error(f"get_site_id failed: {e}")
+            return None
+
+
+    def get_document_libraries(self, site_id:str):
+        # Retrieve drive IDs and names associated with a site
+        try:
+            drives_url = f'https://graph.microsoft.com/v1.0/sites/{site_id}/drives'
+            response = requests.get(drives_url, headers={'Authorization': f'Bearer {self.access_token}'})
+            drives = response.json().get('value', [])
+            return [(drive['id'], drive['name']) for drive in drives]
+        except Exception as e:
+            self.logger.error(f"get_document_libraries failed: {e}")
+            return None
+
+
+    def get_folder_content(self, site_id:str, drive_id:str):
+        # Get the contents of a folder
+        try:
+            folder_url = f'https://graph.microsoft.com/v1.0/sites/{site_id}/drives/{drive_id}/root/children'
+            response = requests.get(folder_url, headers={'Authorization': f'Bearer {self.access_token}'})
+            return response.json().get('value', [])
+        except Exception as e:
+            self.logger.error(f"get_folder_content failed: {e}")
+            return None
+
+    def print_folder_content(self, folder_content):
+        # Display the contents of a SharePoint folder
+        folders = []
+        files = []
+        
+        for item in folder_content:
+            if "folder" in item:
+                folders.append(item["name"])
+            elif "file" in item:
+                files.append(item["name"])
+
+        print(f"Folders: {len(folders)}")
+        for f in sorted(folders):
+            print(f)
+
+        print(f"Files: {len(files)}")
+        for f in sorted(files):
+            print(f)
+
+
+    def upload_file_graph(self, site_id, drive_id:str, folder_path:str, local_file_path:str):
+        """
+        Uploads a file to a SharePoint folder using Microsoft Graph API.
+
+        :param site_id: The SharePoint site ID
+        :param drive_id: The drive ID for the desired folder
+        :param folder_path: Path inside taht folder
+        :param local_file_path: Local path of the file to be uploaded
+        :return: (file_url, success_file_count)
+        """
+        try:
+            file_path = pl.Path(local_file_path)
+            if not file_path.is_file():
+                raise FileNotFoundError(f"File not found: {file_path}")
+
+            with open(file_path, "rb") as file:
+                file_content = file.read()
+
+            # Build the upload URL
+            folder_path_encoded = quote(folder_path)
+            upload_url = (
+                f"https://graph.microsoft.com/v1.0/sites/{site_id}/drives/{drive_id}/root:/{folder_path_encoded}/{file_path.name}:/content"
+            )
+
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "Content-Type": "application/octet-stream"
+            }
+
+            response = requests.put(upload_url, headers=headers, data=file_content)
+            if response.status_code in [200, 201]:
+                file_info = response.json()
+                file_url = file_info.get("webUrl", "")
+                self.logger.debug(f"File uploaded to: {file_url}")
+                return file_url, 1
+            else:
+                self.logger.error(f"Upload to {upload_url} failed: {response.text}")
+                return response.text, 0
+        except FileNotFoundError as e:
+            return str(e), 0
+        except Exception as e:
+            self.logger.error(f"upload_file_graph failed: {e}")
+            return str(e), 0