Metadata-Version: 2.4
Name: ms-graph
Version: 1.5.2
Summary: A Python Client Application that allows interaction with the Microsoft Graph API.
License: MIT
License-File: LICENSE
Keywords: microsoft,graph,api,onedrive,outlook,sharepoint,excel,onenote
Author: bek42
Author-email: bharani.nitturi@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: azkees (>=6.1.0,<7.0.0)
Requires-Dist: msal (>=1.29.0,<2.0.0)
Requires-Dist: pylogpy (>=1.5.2,<2.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Project-URL: Changelog, https://github.com/bek42/ms_graph/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/bek42/ms_graph
Project-URL: Repository, https://github.com/bek42/ms_graph
Description-Content-Type: text/markdown

# ms-graph

[![PyPI version](https://img.shields.io/pypi/v/ms-graph.svg)](https://pypi.org/project/ms-graph/)
[![Python Versions](https://img.shields.io/pypi/pyversions/ms-graph.svg)](https://pypi.org/project/ms-graph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Python client for the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview), covering OneDrive, SharePoint, Outlook Mail, OneNote, Contacts, Excel Workbooks, Users, Groups, and Search.

---

## Installation

```bash
pip install ms-graph
```

Or with Poetry:

```bash
poetry add ms-graph
```

---

## Prerequisites

Register an application in the [Azure Portal](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) to obtain:

- **Client ID**
- **Client Secret**
- **Redirect URI**

Grant the required [Microsoft Graph API permissions](https://learn.microsoft.com/en-us/graph/permissions-reference) for the services you intend to use.

---

## Quick Start

```python
from ms_graph import MicrosoftGraphClient

client = MicrosoftGraphClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="YOUR_REDIRECT_URI",
    scope=["Files.Read", "Files.ReadWrite", "Mail.Read"],
    account_type="consumers",  # or "organizations" / "common"
)

# Opens a browser prompt on first run to complete OAuth2 flow.
# Subsequent runs use a saved token / refresh token automatically.
client.login()
```

Credentials are persisted to a local JSON file (or Azure Key Vault — see below). On subsequent runs, tokens are refreshed silently.

---

## Services

### OneDrive — Drives

```python
drives = client.drives()

# Root drive
root = drives.get_root_drive()

# Children of root
children = drives.get_root_drive_children()

# Recent files
recent = drives.get_recent_files()

# Shared with me
shared = drives.get_shared_files()
```

### OneDrive — Drive Items

```python
items = client.drive_item()

# By item ID
item = items.get_drive_item(drive_id="DRIVE_ID", item_id="ITEM_ID")

# By path
item = items.get_drive_item_by_path(drive_id="DRIVE_ID", item_path="Documents/report.xlsx")

# Group drive item
item = items.get_group_drive_item(group_id="GROUP_ID", item_id="ITEM_ID")
```

### Outlook Mail

```python
mail = client.mail()

# List messages for signed-in user
messages = mail.list_my_messages()

# List messages for a specific user
messages = mail.list_user_messages(user_id="user@example.com")

# Get a specific message
msg = mail.get_my_messages(message_id="MESSAGE_ID")

# Create a draft
draft = mail.create_my_message(message={
    "subject": "Hello",
    "body": {"contentType": "Text", "content": "Hi there"},
    "toRecipients": [{"emailAddress": {"address": "recipient@example.com"}}]
})
```

### OneNote

```python
notes = client.notes()

# My notebooks
notebooks = notes.list_my_notebooks()

# Notebooks for a specific user
notebooks = notes.list_user_notebooks(user_id="user@example.com")

# Notebooks for a group
notebooks = notes.list_group_notebooks(group_id="GROUP_ID")
```

### Personal Contacts

```python
contacts = client.personal_contacts()

# All contacts
all_contacts = contacts.list_my_contacts()

# Contact folders
folders = contacts.list_my_contacts_folder()

# Folder by ID
folder = contacts.list_contacts_folder_by_id(user_id="USER_ID", folder_id="FOLDER_ID")
```

### Users

```python
users = client.users()

all_users = users.list_users()
```

### Groups

```python
groups = client.groups()

all_groups = groups.list_groups()
```

### Search

```python
search = client.search()

results = search.query(search_request={
    "requests": [{
        "entityTypes": ["driveItem"],
        "query": {"queryString": "quarterly report"}
    }]
})
```

### Excel Workbooks

```python
workbooks = client.workbooks()

# Create a session (enables batching edits)
session = workbooks.create_session(item_path="Documents/report.xlsx")
session_id = session["id"]

# Refresh the session
workbooks.refresh_session(session_id=session_id, item_path="Documents/report.xlsx")

# Close the session
workbooks.close_session(session_id=session_id, item_path="Documents/report.xlsx")
```

### Excel Worksheets

```python
from ms_graph.workbooks_and_charts import Worksheet

worksheet = Worksheet(session=client.graph_session)

# Add a new sheet
worksheet.add_worksheet(item_path="Documents/report.xlsx", name="Summary")
```

### Excel Range

```python
range_svc = client.range()

# Get a range by address
data = range_svc.get_range(
    item_path="Documents/report.xlsx",
    worksheet_name_or_id="Sheet1",
    address="A1:C5"
)
```

### Excel Tables

```python
table_svc = client.table()
```

---

## Credential Storage Options

### Option 1 — JSON file (default)

Pass a file path as `credentials`. The token is saved/loaded automatically:

```python
client = MicrosoftGraphClient(
    client_id="...",
    client_secret="...",
    redirect_uri="...",
    scope=[...],
    credentials="./ms_graph_state.json",
)
```

### Option 2 — Azure Key Vault

Pass an `Az` client from [`azkees`](https://pypi.org/project/azkees/) and set the env var `key_msgraph_credentials_state` to the Key Vault secret name where the token JSON will be stored:

```python
import os
from azkees import Az
from ms_graph import MicrosoftGraphClient

os.environ["key_msgraph_credentials_state"] = "msgraphstate"

az_client = Az(config_section="production", keys_config_path="/app/config/api_keys.ini")

client = MicrosoftGraphClient(
    client_id="...",
    client_secret="...",
    redirect_uri="...",
    scope=[...],
    az_client=az_client,
)
```

---

## Enums

```python
from ms_graph.workbooks_and_charts.enums import (
    CalculationTypes,
    WorksheetVisibility,
    RangeShift,
    Underline,
)

CalculationTypes.RECALCULATE.value   # "Recalculate"
WorksheetVisibility.HIDDEN.value     # "Hidden"
RangeShift.DOWN.value                # "Down"
```

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## License

[MIT](LICENSE)

## Author

[Bharani Nitturi](https://github.com/bek42)

