Metadata-Version: 2.4
Name: adsk-platform-httpclient
Version: 0.2.10
Summary: Autodesk Platform Services: shared HTTP client and authentication utilities for Kiota-based SDKs
Author: duszykf
License-Expression: MIT
Project-URL: Homepage, https://github.com/Autodesk/APS-SDK-Kiota
Project-URL: Repository, https://github.com/Autodesk/APS-SDK-Kiota
Project-URL: Issues, https://github.com/Autodesk/APS-SDK-Kiota/issues
Keywords: autodesk,aps,kiota,sdk,httpclient
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: microsoft-kiota-abstractions<2.0.0,>=1.9.0
Requires-Dist: microsoft-kiota-http<2.0.0,>=1.9.0
Requires-Dist: httpx<1.0.0,>=0.27.0

# adsk-platform-httpclient

Shared HTTP client, authentication, and middleware utilities for [Autodesk Platform Services](https://aps.autodesk.com/) Python SDKs.

This package provides the foundational components used by all `adsk-platform-*` SDK packages.

## Installation

```bash
pip install adsk-platform-httpclient
```

> **Note:** You typically don't need to install this package directly. It's automatically included as a dependency of the SDK packages (e.g., `adsk-platform-acc`, `adsk-platform-data-management`).

## Components

### HttpClientFactory

Creates pre-configured `httpx.AsyncClient` instances and Kiota request adapters with bearer-token authentication and the custom middleware pipeline.

```python
from autodesk_common_httpclient import HttpClientFactory

async def get_access_token() -> str:
    return "YOUR_ACCESS_TOKEN"

# Create a Kiota request adapter with authentication + middleware
adapter = HttpClientFactory.create_adapter(get_access_token)

# Or provide your own httpx client
import httpx
custom_client = httpx.AsyncClient(timeout=60.0)
adapter = HttpClientFactory.create_adapter(get_access_token, http_client=custom_client)
```

### AccessTokenProviderCallback

Wraps an async callback into a Kiota-compatible `AccessTokenProvider`.

```python
from autodesk_common_httpclient import AccessTokenProviderCallback

provider = AccessTokenProviderCallback(get_access_token)
```

## Custom Middleware

The package includes three custom middleware handlers that are automatically added to the HTTP pipeline, matching the C# `Autodesk.Common.HttpClientLibrary.Middleware`:

### ErrorHandler

Raises an `httpx.HTTPStatusError` when the HTTP response has a non-success status code (4xx/5xx). Enabled by default.

```python
from autodesk_common_httpclient import ErrorHandlerOption

# Disable for a specific request
error_option = ErrorHandlerOption(enabled=False)
```

### QueryParameterHandler

Appends or overwrites query parameters on every outgoing request. Useful for injecting API versions, region codes, or tracking identifiers.

```python
from autodesk_common_httpclient import QueryParameterHandlerOption

query_option = QueryParameterHandlerOption(query_parameters={"region": "US"})
```

### RateLimitingHandler

Limits the number of concurrent requests per endpoint within a sliding time window. Disabled by default.

```python
from autodesk_common_httpclient import RateLimitingHandlerOption

# Allow max 10 requests per endpoint per 60 seconds
rate_option = RateLimitingHandlerOption()
rate_option.set_rate_limit(max_requests=10, time_window_seconds=60.0)
```

### Creating a client with rate limiting

```python
from autodesk_common_httpclient import HttpClientFactory

# Create an HTTP client with rate limiting enabled
client = HttpClientFactory.create_with_rate_limit(
    max_requests=10,
    time_window_seconds=60.0,
)

# Use it with any SDK client
adapter = HttpClientFactory.create_adapter(get_access_token, http_client=client)
```

### Middleware Pipeline Order

The middleware is executed in this order (matching the C# implementation):

1. **Kiota defaults** — Redirect, Retry, Parameters Name Decoding, URL Replace, User Agent, Headers Inspection
2. **RateLimitingHandler** — Per-endpoint rate limiting
3. **QueryParameterHandler** — Query parameter injection
4. **ErrorHandler** — Error response detection

## Requirements

- Python 3.10 or later

## License

This project is licensed under the MIT License.
