Skip to main content

Production-ready async-first Microsoft Graph API library with clean architecture

Project description

AI-Prishtina Logo

๐Ÿš€ AI-Prishtina Microsoft Graph API

PyPI Downloads Python 3.10+ License: Proprietary Code style: black Type Checked: mypy Coverage: 90%+ Architecture: Clean

The most comprehensive, production-ready Python library for Microsoft Graph API

Async-first โ€ข Type-safe โ€ข Enterprise-grade โ€ข Clean Architecture

Quick Start โ€ข Installation โ€ข Features โ€ข Architecture โ€ข API Coverage โ€ข Documentation


โ˜• Support This Project

If you find this project helpful, please consider supporting it:

Donate


๐Ÿ“‹ Table of Contents


๐Ÿ“ฆ Installation

From PyPI (Recommended)

pip install ai-prishtina-microsoft-graph-api

From Source

git clone https://github.com/ai-prishtina/ai-prishtina-microsoft-graph-api.git
cd ai-prishtina-microsoft-graph-api
pip install -e .

Verify Installation

from ai_prishtina_microsoft_graph_api import GraphAPIClient, __version__
print(f"Installed version: {__version__}")

๐ŸŽฏ Why This Library?

AI-Prishtina Microsoft Graph API is a production-ready, async-first Python library that provides the most comprehensive Microsoft Graph API integration available. Built with Clean Architecture principles, it offers enterprise-grade features that alternatives lack.

Key Differentiators

Feature AI-Prishtina msgraph-sdk-python O365 python-o365
Async-First Design โœ… Native โš ๏ธ Sync wrapper โŒ Sync only โŒ Sync only
Clean Architecture โœ… Full โŒ Monolithic โŒ Monolithic โŒ Monolithic
Type Safety (Pydantic) โœ… Complete โš ๏ธ Partial โŒ No โŒ No
Circuit Breaker โœ… Built-in โŒ No โŒ No โŒ No
Rate Limiting โœ… Token bucket โš ๏ธ Basic โŒ No โŒ No
Retry Logic โœ… Exponential โš ๏ธ Basic โŒ No โš ๏ธ Basic
Redis Caching โœ… Built-in โŒ No โŒ No โŒ No
Prometheus Metrics โœ… Built-in โŒ No โŒ No โŒ No
Batch Operations โœ… Full โš ๏ธ Limited โŒ No โŒ No
Delta Queries โœ… Full โš ๏ธ Limited โŒ No โŒ No
Query Builder โœ… Fluent API โŒ Manual โŒ Manual โŒ Manual
12 API Coverage โœ… Complete โš ๏ธ Partial โš ๏ธ Partial โš ๏ธ Partial

โšก Quick Start (5 minutes)

Installation

# Basic installation
pip install ai-prishtina-microsoft-graph-api

# With Redis caching support
pip install ai-prishtina-microsoft-graph-api[redis]

# With all optional dependencies
pip install ai-prishtina-microsoft-graph-api[all]

Minimal Working Example (5 lines)

import asyncio
from ai_prishtina_microsoft_graph_api import GraphAPIClient

async def main():
    async with GraphAPIClient(
        tenant_id="your-tenant-id",
        client_id="your-client-id",
        client_secret="your-client-secret"
    ) as client:
        users = await client.users.list_users()
        print(f"Found {len(users)} users")

asyncio.run(main())

Common Use Cases

๐Ÿ“ง Send Email
await client.mail.send_message(
    subject="Hello from Graph API",
    body="<h1>Welcome!</h1><p>This is a test email.</p>",
    to_addresses=["recipient@example.com"],
    is_html=True
)
๐Ÿ“… Create Calendar Event
from datetime import datetime, timedelta

event = await client.calendar.create_event(
    subject="Team Meeting",
    start=datetime.now() + timedelta(hours=1),
    end=datetime.now() + timedelta(hours=2),
    attendees=["colleague@example.com"],
    location="Conference Room A"
)
๐Ÿ‘ฅ List Users with Filters
from ai_prishtina_microsoft_graph_api.infrastructure.query import FilterBuilder, QueryParameters

# Build filter: department = 'Engineering' AND accountEnabled = true
filter_expr = (FilterBuilder()
    .equals("department", "Engineering")
    .and_()
    .equals("accountEnabled", True)
    .build())

params = QueryParameters(filter=filter_expr, top=50)
engineers = await client.users.list_users(query_params=params)
๐Ÿ“ Upload File to OneDrive
# Upload a file
with open("report.pdf", "rb") as f:
    file = await client.files.upload_file(
        folder_path="/Documents/Reports",
        filename="report.pdf",
        content=f.read()
    )
print(f"Uploaded: {file.web_url}")

๐ŸŽฏ Feature Overview

Core Capabilities

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                        AI-PRISHTINA GRAPH API INGESTOR                       โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                                             โ”‚
โ”‚  โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—  โ”‚
โ”‚  โ•‘  ๐Ÿ”Œ 12 COMPLETE API INTEGRATIONS                                      โ•‘  โ”‚
โ”‚  โ•‘  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ“ง Mail        ๐Ÿ“… Calendar     ๐Ÿ‘ฅ Users       ๐Ÿ‘” Groups              โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ’ฌ Teams       ๐Ÿ“ Files        ๐ŸŒ Sites       ๐Ÿ“‹ Planner             โ•‘  โ”‚
โ”‚  โ•‘  โœ… To Do       ๐Ÿ“‡ Contacts     ๐Ÿ““ Notes       ๐Ÿข Directory           โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ“Š Reports                                                           โ•‘  โ”‚
โ”‚  โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•  โ”‚
โ”‚                                                                             โ”‚
โ”‚  โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—  โ”‚
โ”‚  โ•‘  โšก ADVANCED FEATURES                                                 โ•‘  โ”‚
โ”‚  โ•‘  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ” Query Parameters    โ”‚ OData $filter, $orderby, $select, $expand   โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ“ฆ Batch Operations    โ”‚ Combine up to 20 API calls in one request  โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ”„ Delta Queries       โ”‚ Incremental sync for change tracking        โ•‘  โ”‚
โ”‚  โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•  โ”‚
โ”‚                                                                             โ”‚
โ”‚  โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—  โ”‚
โ”‚  โ•‘  ๐Ÿข ENTERPRISE FEATURES                                               โ•‘  โ”‚
โ”‚  โ•‘  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ” OAuth2 Auth    โ”‚ Client credentials, auth code, device code       โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ”„ Retry Logic    โ”‚ Exponential backoff with configurable attempts   โ•‘  โ”‚
โ”‚  โ•‘  โšก Rate Limiting  โ”‚ Token bucket algorithm prevents throttling       โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ›ก๏ธ Circuit Breakerโ”‚ Fault tolerance, prevents cascading failures    โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ’พ Redis Cache    โ”‚ Token & response caching with auto-refresh       โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ“Š Prometheus     โ”‚ Full metrics for requests, errors, latency       โ•‘  โ”‚
โ”‚  โ•‘  ๐Ÿ“ Structured Logsโ”‚ JSON logging with correlation IDs                โ•‘  โ”‚
โ”‚  โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•  โ”‚
โ”‚                                                                             โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

๐Ÿ—๏ธ Clean Architecture

This library is built on Clean Architecture principles, ensuring separation of concerns, testability, and maintainability.

Architecture Diagram

graph TB
    subgraph "Presentation Layer"
        A[Pydantic Models]
        B[DTOs]
        C[API Contracts]
    end

    subgraph "Application Layer"
        D[Services]
        E[Use Cases]
        F[Workflows]
    end

    subgraph "Domain Layer"
        G[Entities]
        H[Value Objects]
        I[Repository Interfaces]
        J[Domain Exceptions]
    end

    subgraph "Infrastructure Layer"
        K[HTTP Client]
        L[Authentication]
        M[Cache - Redis/Memory]
        N[Rate Limiter]
        O[Circuit Breaker]
        P[Retry Handler]
        Q[Prometheus Metrics]
        R[Structured Logging]
    end

    A --> D
    B --> D
    D --> G
    D --> I
    E --> I
    I --> K
    K --> L
    K --> M
    K --> N
    K --> O
    K --> P
    K --> Q
    K --> R

    style A fill:#e1f5fe
    style B fill:#e1f5fe
    style C fill:#e1f5fe
    style D fill:#e8f5e9
    style E fill:#e8f5e9
    style F fill:#e8f5e9
    style G fill:#fff3e0
    style H fill:#fff3e0
    style I fill:#fff3e0
    style J fill:#fff3e0
    style K fill:#fce4ec
    style L fill:#fce4ec
    style M fill:#fce4ec
    style N fill:#fce4ec
    style O fill:#fce4ec
    style P fill:#fce4ec
    style Q fill:#fce4ec
    style R fill:#fce4ec

Layer Responsibilities

Layer Purpose Components
Presentation API contracts and data transfer Pydantic models, DTOs, request/response schemas
Application Business logic orchestration Services, use cases, workflows
Domain Core business entities Entities, value objects, repository interfaces
Infrastructure External integrations HTTP client, auth, cache, monitoring

Directory Structure

ai_prishtina_microsoft_graph_api/
โ”œโ”€โ”€ __init__.py              # Package exports
โ”œโ”€โ”€ client.py                # Main GraphAPIClient
โ”œโ”€โ”€ application/
โ”‚   โ””โ”€โ”€ services/            # Business logic services (12 APIs)
โ”œโ”€โ”€ domain/
โ”‚   โ”œโ”€โ”€ entities/            # Domain entities (User, Event, etc.)
โ”‚   โ”œโ”€โ”€ exceptions/          # Domain exceptions
โ”‚   โ””โ”€โ”€ repositories/        # Repository interfaces
โ”œโ”€โ”€ infrastructure/
โ”‚   โ”œโ”€โ”€ auth/                # OAuth2 token providers
โ”‚   โ”œโ”€โ”€ batch/               # Batch request handling
โ”‚   โ”œโ”€โ”€ cache/               # Redis & memory cache
โ”‚   โ”œโ”€โ”€ http/                # HTTP client with retry
โ”‚   โ”œโ”€โ”€ monitoring/          # Prometheus & logging
โ”‚   โ”œโ”€โ”€ pagination/          # Auto-pagination
โ”‚   โ”œโ”€โ”€ query/               # Query parameters & delta
โ”‚   โ”œโ”€โ”€ rate_limiting/       # Rate limiter & circuit breaker
โ”‚   โ””โ”€โ”€ repositories/        # Repository implementations
โ”œโ”€โ”€ presentation/
โ”‚   โ””โ”€โ”€ models/              # Pydantic models
โ””โ”€โ”€ config/                  # Configuration management

๐Ÿ“Š Complete API Coverage

All 12 Microsoft Graph API categories are fully implemented with CRUD operations, query parameters, batch operations, and (where applicable) delta queries.

API Description Query Params Batch Delta Key Operations
๐Ÿ“ง Mail Email operations โœ… โœ… โŒ Send, list, search, attachments, folders
๐Ÿ“… Calendar Calendar & events โœ… โœ… โœ… Create events, manage attendees, recurring
๐Ÿ‘ฅ Users User management โœ… โœ… โœ… CRUD, profiles, licenses, photos
๐Ÿ‘” Groups Groups & teams โœ… โœ… โœ… CRUD, members, owners, conversations
๐Ÿ’ฌ Teams Microsoft Teams โœ… โœ… โŒ Channels, messages, tabs, apps
๐Ÿ“ Files OneDrive/SharePoint โœ… โœ… โœ… Upload, download, share, permissions
๐ŸŒ Sites SharePoint sites โœ… โœ… โŒ Lists, items, permissions
๐Ÿ“‹ Planner Task management โœ… โœ… โŒ Plans, tasks, buckets, assignments
โœ… To Do Personal tasks โœ… โœ… โŒ Lists, tasks, reminders
๐Ÿ“‡ Contacts Contact management โœ… โœ… โŒ CRUD, folders, photos
๐Ÿ““ Notes OneNote notebooks โœ… โœ… โŒ Notebooks, sections, pages
๐Ÿข Directory Azure AD objects โœ… โœ… โŒ Roles, apps, service principals
๐Ÿ“Š Reports Usage analytics โœ… โœ… โŒ Activity, usage, audit logs

๐Ÿ”ฅ Advanced Features

1. Query Parameters (OData Support)

Build complex queries with a fluent, type-safe API:

from ai_prishtina_microsoft_graph_api.infrastructure.query import (
    FilterBuilder, QueryParameters, OrderDirection
)

# Build complex filter expression
filter_expr = (FilterBuilder()
    .equals("department", "Engineering")
    .and_()
    .startswith("displayName", "A")
    .and_()
    .equals("accountEnabled", True)
    .build())
# Result: "department eq 'Engineering' and startswith(displayName, 'A') and accountEnabled eq true"

# Create query with all parameters
params = QueryParameters(
    filter=filter_expr,
    orderby=[("displayName", OrderDirection.ASC), ("createdDateTime", OrderDirection.DESC)],
    select=["id", "displayName", "mail", "department", "jobTitle"],
    expand=["manager", "directReports"],
    top=50,
    skip=0,
    count=True
)

# Execute query
users = await client.users.list_users(query_params=params)

2. Batch Operations

Combine up to 20 API calls in a single HTTP request:

from ai_prishtina_microsoft_graph_api.infrastructure.batch import BatchRequest

# Create batch with multiple operations
batch = BatchRequest()
id1 = batch.add_get("/users/user1@example.com")
id2 = batch.add_get("/users/user2@example.com")
id3 = batch.add_post("/users", {"displayName": "New User", "mailNickname": "newuser"})
id4 = batch.add_patch("/users/user3@example.com", {"department": "Engineering"})

# Execute all at once
response = await client.users.batch(batch)

# Process results
print(f"Success: {response.success_count}, Errors: {response.error_count}")
for item in response.responses:
    if item.is_success:
        print(f"โœ… {item.id}: {item.status}")
    else:
        print(f"โŒ {item.id}: {item.status} - {item.body}")

3. Delta Queries (Change Tracking)

Efficiently sync changes with incremental updates:

from ai_prishtina_microsoft_graph_api.infrastructure.query import DeltaState

# Initial sync - get all users
state = DeltaState(resource_type="users")
result = await client.users.delta()
state.update(result.delta_token, len(result.items))
print(f"Initial sync: {len(result.items)} users")

# Save delta_token to persistent storage...

# Later: Incremental sync - only changes since last sync
result = await client.users.delta(delta_token=state.delta_token)
print(f"Changes since last sync: {len(result.items)}")
for user in result.items:
    if user.is_deleted:
        print(f"  Deleted: {user.id}")
    else:
        print(f"  Modified: {user.display_name}")

๐Ÿข Enterprise Features

Authentication Flow

sequenceDiagram
    participant App as Your Application
    participant Client as GraphAPIClient
    participant TokenProvider as Token Provider
    participant Cache as Redis/Memory Cache
    participant AzureAD as Azure AD
    participant GraphAPI as Microsoft Graph API

    App->>Client: Initialize with credentials
    Client->>TokenProvider: Create provider

    App->>Client: Make API request
    Client->>TokenProvider: Get token
    TokenProvider->>Cache: Check cached token

    alt Token cached and valid
        Cache-->>TokenProvider: Return cached token
    else Token missing or expired
        TokenProvider->>AzureAD: Request new token
        AzureAD-->>TokenProvider: Return token
        TokenProvider->>Cache: Store token
    end

    TokenProvider-->>Client: Return token
    Client->>GraphAPI: API request with token
    GraphAPI-->>Client: Response
    Client-->>App: Return result

Request Lifecycle with Resilience

flowchart TD
    A[API Request] --> B{Rate Limiter}
    B -->|Allowed| C{Circuit Breaker}
    B -->|Throttled| D[Wait & Retry]
    D --> B

    C -->|Closed| E[Make HTTP Request]
    C -->|Open| F[Fail Fast]
    C -->|Half-Open| G[Test Request]

    E --> H{Response?}
    G --> H

    H -->|Success| I[Return Response]
    H -->|Transient Error| J{Retry Handler}
    H -->|Permanent Error| K[Throw Exception]

    J -->|Retry Available| L[Exponential Backoff]
    J -->|Max Retries| K
    L --> E

    I --> M[Update Metrics]
    K --> M
    F --> M

    style A fill:#e3f2fd
    style I fill:#c8e6c9
    style K fill:#ffcdd2
    style F fill:#ffcdd2

Circuit Breaker States

from ai_prishtina_microsoft_graph_api import GraphAPIClient

async with GraphAPIClient(...) as client:
    # Access circuit breaker stats
    stats = client.container.circuit_breaker().get_stats()
    print(f"""
    Circuit State: {stats['state']}
    Failure Count: {stats['failure_count']}
    Failure Threshold: {stats['failure_threshold']}
    Recovery Timeout: {stats['recovery_timeout']}s
    Last Failure: {stats['last_failure_time']}
    """)
State Description Behavior
CLOSED Normal operation Requests pass through
OPEN Too many failures Requests fail fast
HALF-OPEN Testing recovery Limited requests allowed

Rate Limiting

Token bucket algorithm prevents API throttling:

# Configuration (in GraphAPIClient or config file)
# Default: 10 requests/second with burst of 20

# Access rate limiter stats
rate_limiter = client.container.rate_limiter()
# Rate limiter automatically manages request flow

โš™๏ธ Configuration

Option 1: Environment Variables

# Required: Azure AD credentials
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"

# Optional: API configuration
export GRAPH_API_BASE_URL="https://graph.microsoft.com/v1.0"
export GRAPH_API_TIMEOUT="30"

# Optional: Redis caching
export REDIS_ENABLED="true"
export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_PASSWORD=""

# Optional: Rate limiting
export RATE_LIMIT_REQUESTS_PER_SECOND="10"
export RATE_LIMIT_BURST_SIZE="20"

# Optional: Circuit breaker
export CIRCUIT_BREAKER_FAILURE_THRESHOLD="5"
export CIRCUIT_BREAKER_RECOVERY_TIMEOUT="60"

Option 2: Configuration File (YAML)

# config.yaml
authentication:
  tenant_id: "your-tenant-id"
  client_id: "your-client-id"
  client_secret: "your-client-secret"

api:
  base_url: "https://graph.microsoft.com/v1.0"
  timeout_seconds: 30

redis:
  enabled: true
  host: "localhost"
  port: 6379
  db: 0
  password: null
  ttl_seconds: 3600

rate_limiting:
  enabled: true
  requests_per_second: 10.0
  burst_size: 20

circuit_breaker:
  enabled: true
  failure_threshold: 5
  recovery_timeout_seconds: 60

retry:
  enabled: true
  max_attempts: 5
  backoff_multiplier: 2.0
  max_wait_seconds: 60

monitoring:
  prometheus_enabled: true
  log_level: "INFO"
  log_format: "json"
# Load from config file
client = GraphAPIClient.from_config("config.yaml")

Option 3: Constructor Parameters

client = GraphAPIClient(
    # Authentication (required)
    tenant_id="your-tenant-id",
    client_id="your-client-id",
    client_secret="your-client-secret",

    # API configuration
    base_url="https://graph.microsoft.com/v1.0",

    # Redis caching
    use_redis=True,
    redis_host="localhost",
    redis_port=6379,
    redis_db=0,
    redis_password=None,
)

๐Ÿ“Š Monitoring & Observability

Prometheus Metrics

from prometheus_client import start_http_server

# Start metrics server on port 8000
start_http_server(8000)

# Metrics available at http://localhost:8000/metrics
Metric Type Description
graph_api_requests_total Counter Total API requests by endpoint
graph_api_request_duration_seconds Histogram Request latency distribution
graph_api_errors_total Counter Errors by type (rate_limit, auth, etc.)
graph_api_rate_limit_hits_total Counter Rate limit throttle events
graph_api_cache_hits_total Counter Cache hits vs misses
graph_api_cache_hit_ratio Gauge Current cache hit ratio
graph_api_circuit_breaker_state Gauge Circuit breaker state (0=closed, 1=open)
graph_api_circuit_breaker_failures Counter Circuit breaker failure count

Structured Logging

from ai_prishtina_microsoft_graph_api.infrastructure.monitoring import configure_logging

# JSON logs for production (ELK, Splunk, etc.)
configure_logging(level="INFO", json_logs=True)

# Human-readable logs for development
configure_logging(level="DEBUG", json_logs=False)

Example JSON log output:

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "info",
  "logger": "ai_prishtina_microsoft_graph_api.infrastructure.http",
  "message": "graph_api_request",
  "method": "GET",
  "url": "/users",
  "status_code": 200,
  "duration_ms": 145,
  "correlation_id": "abc-123-def-456"
}

๐Ÿ† Competitive Advantages

vs. msgraph-sdk-python (Microsoft Official)

Aspect AI-Prishtina msgraph-sdk-python
Architecture Clean Architecture with clear layers Monolithic, auto-generated
Async Support Native async/await throughout Sync-first with async wrappers
Type Safety Full Pydantic validation Generated types, less validation
Enterprise Features Circuit breaker, rate limiting, caching Basic retry only
Observability Prometheus + structured logging Minimal logging
Learning Curve Intuitive, well-documented Complex, auto-generated code

vs. O365 / python-o365

Aspect AI-Prishtina O365/python-o365
Performance Async I/O, high throughput Synchronous, blocking
Reliability Circuit breaker, retry, rate limiting No resilience patterns
Caching Redis + memory cache No caching
Batch Operations Full support (20 requests) Not supported
Delta Queries Full support Not supported
Monitoring Prometheus metrics No metrics

Why Choose AI-Prishtina?

  1. ๐Ÿš€ Performance: Native async design handles thousands of concurrent requests
  2. ๐Ÿ›ก๏ธ Reliability: Enterprise patterns (circuit breaker, retry, rate limiting) ensure stability
  3. ๐Ÿ“Š Observability: Full Prometheus metrics and structured logging for production
  4. ๐Ÿงฉ Maintainability: Clean Architecture makes code testable and extensible
  5. โšก Efficiency: Batch operations and delta queries minimize API calls
  6. ๐Ÿ”’ Type Safety: Pydantic models catch errors at compile time

๐Ÿ“– Documentation

Quick Links

Document Description
Advanced Features Guide Complete guide to Query Parameters, Batch Operations, Delta Queries
Quick Reference Cheat sheet for common operations
Architecture System design and patterns
Configuration All configuration options

API Examples

API Examples Document
Calendar Calendar Examples (10 examples)
Users, Groups, Files Users/Groups/Files Examples (18 examples)
Teams, To Do, Planner Teams/ToDo/Planner Examples (21 examples)

Additional Resources


๐Ÿงช Testing

# Run all tests
pytest

# Run with coverage report
pytest --cov=ai_prishtina_microsoft_graph_api --cov-report=html

# Run specific test categories
pytest tests/unit/           # Unit tests only
pytest tests/integration/    # Integration tests only

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/unit/test_users_repository.py

Test Coverage Goals

  • Unit Tests: โ‰ฅ90% coverage of business logic
  • Integration Tests: All API endpoints tested
  • Performance Tests: Batch and concurrent operation benchmarks

๐Ÿ“„ License & Support

License

This is proprietary commercial software. See the LICENSE file for details.

Copyright ยฉ 2025 Alban Maxhuni, PhD. All rights reserved.

For licensing inquiries, contact: info@albanmaxhuni.com

Support

Channel Link
GitHub Issues Report bugs or request features
Documentation Full documentation
Commercial Support info@albanmaxhuni.com
Author alban.q.maxhuni@gmail.com

Acknowledgments

Built with industry-leading open source tools:


Made with โค๏ธ by Alban Maxhuni, PhD

โฌ† Back to Top

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

File details

Details for the file ai_prishtina_microsoft_graph_api-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for ai_prishtina_microsoft_graph_api-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 999a2946fc4f77dcab1aa2c5f71c5837b3d483595814eb56d51a205eb85a572d
MD5 f4199f82ff26311934fa37ef33acad3a
BLAKE2b-256 08491a0daa3fd04bc24939d25537f2c88ef57dfd2033e9ea76efd20c0717ee54

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page