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.

pip install graphplug

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

Quick start

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

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: access models, every constructor, Entra app registration
• Application access: acting for a mailbox with user=, required permissions
• Permissions (Scopes): delegated permission names

Resources

• Mail
• Calendar and meetings
• Files (OneDrive)
• Teams and chats
• People and the directory
• Methods every resource has

Everything else

• Any Graph endpoint and OData options
• Paging
• Batching
• Downloads and uploads
• Errors
• Logging
• Client lifetime and concurrency
• Troubleshooting
• Architecture: how the package is built
• 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

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.

Licence

MIT