msgraph-sdk-python-core

msgraph-core is the foundational package underneath the official Microsoft Graph Python SDK (msgraph-sdk-python). It doesn’t expose the generated, per-endpoint Graph API surface itself — that lives in the full SDK — but instead provides the shared HTTP plumbing every generated method relies on: a Kiota-based request adapter wired to httpx, a Graph-aware middleware pipeline (telemetry headers, national cloud routing, retry/redirect handling inherited from Kiota’s HTTP core), and higher-level task helpers for the two things a raw HTTP client makes tedious against Graph — resumable large-file uploads via upload sessions and OData @odata.nextLink pagination via PageIterator.

Because Microsoft Graph supports batching, the library also ships a full batch-request/response model (BatchRequestContent, BatchRequestItem, BatchResponseContentCollection) that groups up to 20 requests into a single HTTP call and resolves per-item responses and dependencies. The package targets Python 3.10+, is async-first (built on httpx.AsyncClient and asyncio), and is maintained directly by Microsoft’s Graph tooling team as a dependency of the generated SDK rather than something most developers install and call on its own.

What You Get

• BaseGraphRequestAdapter — a HttpxRequestAdapter subclass preconfigured with Graph-appropriate parse-node and serialization-writer registries
• GraphClientFactory — builds an httpx.AsyncClient with the default Graph middleware pipeline (or a custom one) already mounted, including national-cloud base URLs
• GraphTelemetryHandler middleware that stamps every Graph-bound request with SDK version, client-request-id, host OS, and runtime environment headers for supportability
• LargeFileUploadTask for resumable, chunked uploads against Graph’s upload-session endpoints, with expiry checks and a configurable chunk size
• PageIterator for walking OData @odata.nextLink/@odata.deltaLink paginated responses without hand-rolling next-page loops
• A complete JSON batch request/response model (BatchRequestContent, BatchRequestItem, BatchResponseContentCollection) supporting up to 20 requests per call with dependency ordering

Common Use Cases

• Consumed transitively as a dependency of msgraph-sdk-python — most developers never import it directly, they get it by installing the full Graph SDK
• Custom Graph API tooling that needs an authenticated, telemetry-compliant HTTP client without pulling in the full generated SDK surface
• Uploading large files (e.g. to OneDrive/SharePoint drive items) via resumable upload sessions instead of a single oversized PUT
• Iterating large Graph result sets (users, messages, directory objects) page by page without manually tracking @odata.nextLink
• Batching several independent Graph calls into one HTTP round trip to cut latency and stay under throttling limits

Under The Hood

Architecture The library layers cleanly on Kiota’s abstractions rather than reinventing them: BaseGraphRequestAdapter (src/msgraph_core/base_graph_request_adapter.py) subclasses kiota_http’s HttpxRequestAdapter, injecting default ParseNodeFactoryRegistry/SerializationWriterFactoryRegistry instances and an httpx.AsyncClient produced by GraphClientFactory. That factory (graph_client_factory.py) is where Graph-specific behavior actually attaches — it takes Kiota’s default middleware pipeline, appends a GraphTelemetryHandler, and swaps the client’s transport for a custom AsyncGraphTransport, all keyed off an APIVersion/NationalClouds enum pair rather than hardcoded URLs. Pagination (tasks/page_iterator.py) and large-file upload (tasks/large_file_upload.py) are deliberately standalone task classes that take a RequestAdapter as a constructor argument instead of depending on the adapter internals, so they work against any Kiota-compatible adapter, not just the Graph one. The batch subsystem (requests/) mirrors this same request/response duality with its own serializable Parsable implementations.

Tech Stack Built on httpx.AsyncClient for transport, microsoft-kiota-abstractions/microsoft-kiota-authentication-azure/microsoft-kiota-http (all pinned >=1.11.6,<2.0.0) for the underlying request-adapter/middleware contracts, and azure-identity’s async credential classes for auth at the call site. Requires Python 3.10+ and is packaged with a standard setuptools-based pyproject.toml (no Poetry/Hatch). Dev tooling runs yapf for formatting, isort for import order, mypy for static typing, and pylint against a repo-specific .pylintrc.

Code Quality Tests live under tests/, mirroring the src/msgraph_core package layout one-to-one (tests/tasks/test_page_iterator.py, tests/requests/test_batch_request_content.py, etc.) and use pytest with pytest-asyncio-style async test functions and mocked request adapters rather than live Graph calls. CI (.github/workflows/build.yml) runs the full matrix — format check, import-order check, mypy, pylint, and pytest — across Python 3.10 through 3.14 on every push and PR, which is a notably wide support matrix for a library this size. Error handling favors explicit ValueError/RuntimeError raises over silent failures (e.g. expired upload sessions, missing upload URLs), though LargeFileUploadTask.upload() does swallow per-chunk exceptions into a log statement inside a broad except Exception before continuing the chunk loop.

What Makes It Unique It isn’t a general-purpose HTTP or Graph client on its own — it’s the specific seam Microsoft carved out so the code-generated per-endpoint SDK (msgraph-sdk-python) doesn’t have to hand-roll batching, pagination, or resumable uploads, none of which Kiota’s generator produces automatically. The telemetry middleware is similarly narrow but deliberate: it only attaches SDK/version/runtime headers when the request target matches a known Graph national-cloud endpoint, leaving non-Graph requests made through the same client untouched.