Metadata-Version: 2.4
Name: graphplug
Version: 0.4.2
Summary: Plug-and-play Graph API for Python: mail, calendar, files, teams, users and generic requests.
Author: Vikram Balaji
License-Expression: MIT
Project-URL: Homepage, https://github.com/VikramBalaji1/graphPlug
Project-URL: Documentation, https://github.com/VikramBalaji1/graphPlug#readme
Project-URL: Issues, https://github.com/VikramBalaji1/graphPlug/issues
Project-URL: Changelog, https://github.com/VikramBalaji1/graphPlug/releases
Keywords: microsoft-graph,entra-id,azure-ad,outlook,onedrive,teams,asyncio
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: azure-identity>=1.19
Requires-Dist: msgraph-core>=1.3
Requires-Dist: msal>=1.31
Requires-Dist: httpx>=0.28
Dynamic: license-file

# graphplug

**Microsoft Graph for Python, one call at a time.** Send a mail, book a Teams meeting, upload a
file or look someone up in the directory without writing Graph's JSON by hand. Sign-in, retries,
throttling, paging and batching are handled for you.

```bash
pip install graphplug
```

Python 3.10+ · async · built on Microsoft's `azure-identity` and `msgraph-core` · MIT licence

## Quick start

```python
import asyncio
from datetime import datetime, timedelta, timezone
from graphplug import GraphClient

MY_MAILBOX = "you@example.com"

async def main():
    # Reads AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET
    async with GraphClient.from_env() as graph:
        await graph.mail.send(to="team@example.com", subject="Nightly report",
                              body="All green.", user=MY_MAILBOX)

        start = datetime.now(timezone.utc) + timedelta(days=1)
        event = await graph.calendar.schedule(
            subject="Design review", start=start, end=start + timedelta(hours=1),
            attendees=["alice@example.com"], optional_attendees=["carol@example.com"],
            online=True, user=MY_MAILBOX,
        )
        print(event["onlineMeeting"]["joinUrl"])

asyncio.run(main())
```

## What it covers

| Area | Examples |
|---|---|
| `graph.mail` | Send with attachments, send many at once, read and search an inbox, reply, forward, move |
| `graph.calendar` | Organise Teams meetings with required and optional attendees, auto-record, block time, check availability |
| `graph.files` | Upload and download OneDrive files of any size, create folders, share links, search |
| `graph.teams` | Post to channels, reply in threads, send chat messages |
| `graph.users` | Find people, look up managers, reports, groups and photos |
| Any other endpoint | `get`, `post`, `patch`, `delete`, paging and batching for every Graph `v1.0` and `beta` API |

It works with both access models: **application access**, where your code runs as the app and
names the mailbox with `user=`, and **delegated access**, where a person signs in.

## Documentation

**Getting started**

- [Signing in](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/signing-in.md): access models, every constructor, Entra app registration
- [Application access](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/application-access.md): acting for a mailbox with `user=`, required permissions
- [Permissions (`Scopes`)](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/permissions.md): delegated permission names

**Resources**

- [Mail](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/mail.md)
- [Calendar and meetings](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/calendar.md)
- [Files (OneDrive)](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/files.md)
- [Teams and chats](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/teams.md)
- [People and the directory](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/users.md)
- [Methods every resource has](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/shared-methods.md)

**Everything else**

- [Any Graph endpoint and OData options](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/requests.md)
- [Paging](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/paging.md)
- [Batching](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/batching.md)
- [Downloads and uploads](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/transfers.md)
- [Errors](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/errors.md)
- [Logging](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/logging.md)
- [Client lifetime and concurrency](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/client-lifetime.md)
- [Troubleshooting](https://github.com/VikramBalaji1/graphPlug/blob/main/USAGE/troubleshooting.md)
- [Architecture](https://github.com/VikramBalaji1/graphPlug/blob/main/ARCHITECTURE.md): how the package is built
- [Samples](https://github.com/VikramBalaji1/graphPlug/tree/main/samples): runnable scripts

## Security

- Tokens are fetched, cached in memory and refreshed by `azure-identity`; nothing is written to disk.
- The bearer token is sent only to `graph.microsoft.com`.
- Delegated sign-ins must name their permissions; there is no catch-all default.
- A caller-supplied `Authorization` header is refused.
- Logging is off by default and never records tokens, secrets, headers or bodies.

## Development

```bash
pip install -e .
python -m unittest discover -s tests
python -m build
```

Releases are published to PyPI by GitHub Actions when a version tag is pushed; see
[CLAUDE.md](https://github.com/VikramBalaji1/graphPlug/blob/main/CLAUDE.md#releasing).

## Licence

[MIT](https://github.com/VikramBalaji1/graphPlug/blob/main/LICENSE)
