feat(http): implement body inspection handler

[RKS (rksharma-owg)]

Resolves #418

Description

Implements the BodyInspectionHandler middleware and BodyInspectionHandlerOption for Kiota Python, following the shared middleware specification in microsoftgraph/msgraph-sdk-design#116.

Summary of Changes

• Adds opt-in request and response body capture with byte and rewound BytesIO accessors.
• Registers BodyInspectionHandler in the default middleware pipeline.
• Preserves request and response payloads for downstream consumers, including replayable raw streamed responses.
• Carries request options through redirects using native HTTPX request extensions, while retaining the existing middleware compatibility bridge.
• Clears captured state before each use and isolates captures by execution context when concurrent requests share a handler-level option.
• Restores HTTPX download-byte accounting, decoded-content state, and decoder lifecycle so replayed compressed streams are consumed and counted normally.
• Leaves already-consumed responses without cached content and closed unreadable responses unchanged instead of raising during inspection.
• Avoids initializing or copying capture state on the default-disabled path while still clearing reused captures.
• Retains the original lifecycle state for already-buffered responses instead of exposing decoded bytes as a raw stream.
• Rejects a null request with an intentional TypeError before option or span access.
• Emits the standardized com.microsoft.kiota.handler.bodyInspection.enable telemetry attribute and keeps the span open through inspection, transport execution, response handling, and exception cleanup.
• Adds regression coverage for capture behavior, concurrent requests, byte accounting, request and response streaming, redirect propagation, state reset, null-request validation, span lifecycle, telemetry, and client factory integration.

Documentation

• docs(kiota): mark Python body inspection as default MicrosoftDocs/openapi-docs#175 updates the Microsoft Learn support table and is gated on this PR.

Verification

• pytest in packages/http/httpx: 154 passed.
• Focused body-inspection tests: 25 passed.
• Redirect, adapter, and body-inspection tests: 102 passed.
• YAPF and targeted isort checks passed for changed files.
• Pylint rated the package 10.00/10; the repository emits its existing suggestion-mode configuration warning.
• Mypy reported no issues in 26 source files.
• Fork preflight passed the full Python 3.10-3.14 matrix for commit eaa50db: https://github.com/rksharma-owg/kiota-python/actions/runs/35131242553
• SonarCloud reports 0 open or confirmed new issues for commit eaa50db.

[Vincent Biret (baywet)]

RKS (@rksharma-owg) would you mind addressing the copilot comments please?

[RKS (rksharma-owg)]

Addressed the review findings in ee0ea54: standardized the telemetry key, preserved per-request options across redirects, restored replayable raw response streams after inspection, and added regressions for each behavior. The full Python 3.10-3.14 fork preflight passed, and the linked documentation update is MicrosoftDocs/openapi-docs#175.

[RKS (rksharma-owg)]

Addressed the new review in 1dc4c07. Reused per-request options now clear stale captures, and already-buffered responses retain their original consumed/closed raw-stream state. The request-stream concern was verified against HTTPX 0.25.0-0.28.1 and is already handled by Request.aread(); the regression now exercises request.stream directly at the transport boundary. Local validation reports 133 tests passing, and the full Python 3.10-3.14 fork preflight passed: https://github.com/rksharma-owg/kiota-python/actions/runs/35100712297

[RKS (rksharma-owg)]

Addressed both findings from the latest Copilot review in b80f4fc:

• handler-level capture state is now isolated per execution context, with a concurrent forced-overlap regression test;
• response restoration now also restores HTTPX byte accounting, with coverage confirming the count stays at its pre-inspection value until the caller consumes the replayed stream.

Local validation is green (136 HTTP package tests; 21 focused tests), and the full Python 3.10–3.14 fork preflight passed: https://github.com/rksharma-owg/kiota-python/actions/runs/35104897911

[RKS (rksharma-owg)]

Thanks for the extra pass — both moderate findings are addressed in 22d08e5:\n\n- capture state is now cleared only when a prior request/response body actually exists, so the default-disabled handler leaves the context map uninitialized while reused options still reset correctly;\n- response inspection now skips closed, uncached streams just as it skips consumed, uncached streams, preserving the original response instead of raising StreamClosed.\n\nI added focused regressions for both paths. Validation is green: 140 HTTP package tests, 25 focused body-inspection tests, and the full Python 3.10–3.14 fork preflight: https://github.com/rksharma-owg/kiota-python/actions/runs/35113744365

[Vincent Biret (baywet)]

RKS (@rksharma-owg) can you run the formatting command please?

[RKS (rksharma-owg)]

okay

[Copilot]

🔵 Needs a closer look

The change set touches core request/response streaming semantics and migrates the per-request options mechanism, which is subtle and warrants final human verification for compatibility expectations.

Review details

• Files reviewed: 16/16 changed files
• Comments generated: 1
• Review effort level: Lite

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[RKS (rksharma-owg)]

Done, I ran the repository formatting command (yapf -ir kiota_http) and pushed the resulting formatting changes. I also reran the validation suite and confirmed everything is green:

• YAPF check: poetry run yapf -dr kiota_http passed cleanly (0 differences)
• Pylint: 10.00/10 rating
• Mypy: 0 issues across 26 source files
• pytest: 154 passed (including all 25 BodyInspectionHandler tests)
• CI Preflight: Full Python 3.10–3.14 matrix passed on fork run 35360699982

[Vincent Biret (baywet)]

Thank you for making the changes!