Metadata-Version: 2.4
Name: mgf-http
Version: 0.1.0
Summary: Async HTTP client for mgf-common consumers — typed httpx wrapper with retries, timeouts, header redaction, OTel-aware logging. Sibling of mgf-common under the mgf.* namespace.
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-http
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-http/issues
Project-URL: Changelog, https://codeberg.org/magogi-admin/mgf-http/src/branch/master/CHANGELOG.md
Author: Bassam Alsanie, mgf-http contributors
License: MIT
License-File: LICENSE
Keywords: async,http-client,httpx,otel,redaction,retry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mgf-common<0.30,>=0.29
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: test
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# `mgf-http` — typed async HTTP client for mgf-common consumers

[![PyPI](https://img.shields.io/pypi/v/mgf-http)](https://pypi.org/project/mgf-http/)
[![Python](https://img.shields.io/pypi/pyversions/mgf-http)](https://pypi.org/project/mgf-http/)

> **Sibling of [`mgf-common`](https://pypi.org/project/mgf-common/)
> under the `mgf.*` namespace.** Houses the typed httpx wrapper that
> previously lived under `mgf.common.http.*` — extracted at
> mgf-common v0.29 / mgf-http v0.1 per the
> [federation split plan](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md).

## What this provides

| Submodule | What |
|---|---|
| `mgf.http` | `AsyncHttpClient` — thin wrapper over `httpx.AsyncClient` with retries, timeouts, header redaction, OTel-aware logging, typed error translation. `RetryPolicy` — exponential backoff with jitter; per-request override. |
| `mgf.http.exceptions` | `HttpTransportError(OperationError)` — transport-layer failure (timeout, connect-refused, network unreachable). Renamed from `HttpClientError` at the v0.29 cutover to disambiguate from `mgf.common.exceptions.HttpClientError` (the HTTP-01 4xx-class hierarchy parent, which stays in mgf-common). |

## Install

```bash
pip install mgf-http
# Or with the test extra (respx for mocking httpx in your tests):
pip install 'mgf-http[test]'
```

Pulls in `mgf-common` and `httpx` automatically.

## Quick start

```python
import asyncio
from mgf.http import AsyncHttpClient, RetryPolicy

async def main() -> None:
    async with AsyncHttpClient(
        base_url="https://api.example.com",
        timeout=10.0,
        retry=RetryPolicy(max_attempts=3),
    ) as http:
        response = await http.get("/users", params={"page": 1})
        response.raise_for_status()
        users = response.json()

asyncio.run(main())
```

The client auto-derives a User-Agent of the shape
`<app>/<ver> mgf-http/<libver>` from `mgf.common.app_name()` /
`mgf.common.app_version()` (call `mgf.common.bootstrap()` at startup
for accurate identity). Authorization / Cookie / X-Api-Key family
headers are redacted in logs and OTel spans automatically.

## Documentation

- [`docs/recipes/http.md`](docs/recipes/http.md) — full HTTP-client walkthrough.
- [`docs/cutover/v0.1.0.md`](docs/cutover/v0.1.0.md) — maiden voyage migration story (the v0.29 split, including the `HttpClientError` → `HttpTransportError` rename).
- [`PUBLIC_API.md`](PUBLIC_API.md) — full public surface contract.
- [`CHANGELOG.md`](CHANGELOG.md) — release history.

For the federation-wide engineering standards (DESIGN_PRINCIPLES,
ERROR_HANDLING, SECURITY, etc.) see
[`mgf-common/docs/standards/`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/standards/).
This sibling inherits them by reference; the standards
source-of-truth lives in mgf-common.

## Status

🚧 **Experimental** — every public name is `experimental` per AP-09.
Promotion to `stable` happens release-by-release as consumer feedback
in [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
converges. The 0.x window applies. Pin tightly:
`mgf-http = ">=0.X.0,<0.Y"`.

## Cross-references

- **Filing process for sharp edges**: open an entry on
  [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/FEEDBACK.md)
  with `[mgf-http]` prefix, OR file directly on this repo's Issues →
  maintainer mirrors into the canonical FEEDBACK.md.
- **Federation pattern**:
  [`mgf-common/docs/design/federation.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/design/federation.md).
- **The split that created this sibling**:
  [`mgf-common/docs/release/federation_roadmap.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/master/docs/release/federation_roadmap.md).
