httpware 0.1.0__tar.gz

httpware-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: httpware
+Version: 0.1.0
+Summary: Resilience-first async HTTP client framework for Python
+Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
+Author: Artur Shiriev
+Author-email: Artur Shiriev <me@shiriev.ru>
+License-Expression: MIT
+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: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Framework :: AsyncIO
+Requires-Dist: httpx2>=2.0.0,<3.0
+Requires-Dist: pydantic>=2.0,<3.0
+Requires-Dist: httpware[msgspec,otel,niquests] ; extra == 'all'
+Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
+Requires-Dist: niquests>=3.18 ; extra == 'niquests'
+Requires-Dist: opentelemetry-api>=1.20 ; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20 ; extra == 'otel'
+Requires-Python: >=3.11, <4
+Project-URL: repository, https://github.com/modern-python/httpware
+Project-URL: docs, https://httpware.readthedocs.io
+Provides-Extra: all
+Provides-Extra: msgspec
+Provides-Extra: niquests
+Provides-Extra: otel
+Description-Content-Type: text/markdown
+
+# httpware
+
+[![Test](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/httpware.svg)](https://pypi.org/project/httpware/)
+[![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Async HTTP client framework for Python.**
+
+`httpware` is a typed, async HTTP client library built on `httpx2` with a protocol-based seam so the transport is swappable. Middleware composes via an onion model. Pydantic and msgspec response decoding ship out of the box. `RecordedTransport` replaces respx for transport-level tests.
+
+> **Status:** Pre-1.0 (0.1.0 alpha). Public API is subject to change between minor releases until v1.0. Resilience middleware (retry / timeout / bulkhead), streaming, and observability are not yet shipped — track progress on GitHub.
+
+## Install
+
+```bash
+pip install httpware
+```
+
+Optional extras:
+
+```bash
+pip install httpware[msgspec]    # MsgspecDecoder
+```
+
+(`otel`, `niquests`, and `all` extras are declared but their integrations have not shipped yet.)
+
+## Quickstart
+
+```python
+from httpware import AsyncClient
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    id: int
+    name: str
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)
+```
+
+## What ships in 0.1.0
+
+- **`AsyncClient`** — eight HTTP method shortcuts (`get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `request`) with typed `response_model` overloads; per-call overrides for `headers`, `params`, `cookies`, `timeout`, `json`, `content`; httpx-style `base_url` join; `with_options(...)` returns a view sharing the same transport.
+- **Transport-agnostic seam.** `httpx2` is confined to `httpware.transports.httpx2.Httpx2Transport`. Implement the `Transport` protocol to swap backends.
+- **Middleware foundation.** `Middleware` protocol, `Next` type alias, recursive-closure `compose()` chain composition, and phase decorators (`@before_request`, `@after_response`, `@on_error`).
+- **Pluggable response decoding.** `PydanticDecoder` (default) with cached `TypeAdapter`; `MsgspecDecoder` via `httpware[msgspec]`.
+- **`RecordedTransport`** — built-in test double with a route table, observed-request list, and `aclose_calls` counter.
+- **Status-keyed exception hierarchy** — `StatusError`, 4xx / 5xx subclasses, plain typed fields (`status: int`, `body: bytes`, `headers`, `json`, `request_method`, `request_url`). Pickleable; userinfo redacted in `__repr__`.
+- **No `httpx2` exception types** leak through `httpware`. The transport seam maps them to `httpware` exceptions.
+
+## Part of `modern-python`
+
+Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

httpware-0.1.0/README.md

@@ -0,0 +1,62 @@
+# httpware
+
+[![Test](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/httpware.svg)](https://pypi.org/project/httpware/)
+[![Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Async HTTP client framework for Python.**
+
+`httpware` is a typed, async HTTP client library built on `httpx2` with a protocol-based seam so the transport is swappable. Middleware composes via an onion model. Pydantic and msgspec response decoding ship out of the box. `RecordedTransport` replaces respx for transport-level tests.
+
+> **Status:** Pre-1.0 (0.1.0 alpha). Public API is subject to change between minor releases until v1.0. Resilience middleware (retry / timeout / bulkhead), streaming, and observability are not yet shipped — track progress on GitHub.
+
+## Install
+
+```bash
+pip install httpware
+```
+
+Optional extras:
+
+```bash
+pip install httpware[msgspec]    # MsgspecDecoder
+```
+
+(`otel`, `niquests`, and `all` extras are declared but their integrations have not shipped yet.)
+
+## Quickstart
+
+```python
+from httpware import AsyncClient
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    id: int
+    name: str
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)
+```
+
+## What ships in 0.1.0
+
+- **`AsyncClient`** — eight HTTP method shortcuts (`get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `request`) with typed `response_model` overloads; per-call overrides for `headers`, `params`, `cookies`, `timeout`, `json`, `content`; httpx-style `base_url` join; `with_options(...)` returns a view sharing the same transport.
+- **Transport-agnostic seam.** `httpx2` is confined to `httpware.transports.httpx2.Httpx2Transport`. Implement the `Transport` protocol to swap backends.
+- **Middleware foundation.** `Middleware` protocol, `Next` type alias, recursive-closure `compose()` chain composition, and phase decorators (`@before_request`, `@after_response`, `@on_error`).
+- **Pluggable response decoding.** `PydanticDecoder` (default) with cached `TypeAdapter`; `MsgspecDecoder` via `httpware[msgspec]`.
+- **`RecordedTransport`** — built-in test double with a route table, observed-request list, and `aclose_calls` counter.
+- **Status-keyed exception hierarchy** — `StatusError`, 4xx / 5xx subclasses, plain typed fields (`status: int`, `body: bytes`, `headers`, `json`, `request_method`, `request_url`). Pickleable; userinfo redacted in `__repr__`.
+- **No `httpx2` exception types** leak through `httpware`. The transport seam maps them to `httpware` exceptions.
+
+## Part of `modern-python`
+
+Browse the full list of templates and libraries in [`modern-python`](https://github.com/modern-python) — see the org profile for the categorized index.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

httpware-0.1.0/pyproject.toml

@@ -0,0 +1,113 @@
+[project]
+name = "httpware"
+description = "Resilience-first async HTTP client framework for Python"
+authors = [{ name = "Artur Shiriev", email = "me@shiriev.ru" }]
+requires-python = ">=3.11,<4"
+license = "MIT"
+readme = "README.md"
+keywords = [
+    "http",
+    "async",
+    "client",
+    "resilience",
+    "retry",
+    "circuit-breaker",
+    "middleware",
+    "httpx",
+    "pydantic",
+]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Internet :: WWW/HTTP",
+    "Framework :: AsyncIO",
+]
+version = "0.1.0"
+dependencies = [
+    "httpx2>=2.0.0,<3.0",
+    "pydantic>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+msgspec = ["msgspec>=0.18"]
+otel = [
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+]
+niquests = ["niquests>=3.18"]
+all = ["httpware[msgspec,otel,niquests]"]
+
+[project.urls]
+repository = "https://github.com/modern-python/httpware"
+docs = "https://httpware.readthedocs.io"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "httpware"
+module-root = "src"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "pytest-asyncio",
+    "pytest-repeat",
+    "pytest-benchmark",
+    "hypothesis",
+]
+lint = [
+    "ruff",
+    "ty",
+    "eof-fixer",
+    "typing-extensions",
+]
+
+[tool.ruff]
+fix = true
+unsafe-fixes = true
+line-length = 120
+target-version = "py311"
+extend-exclude = ["docs"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D1",     # allow missing docstrings
+    "S101",   # allow asserts
+    "TCH",    # ignore flake8-type-checking
+    "FBT",    # allow boolean args
+    "D203",   # "one-blank-line-before-class" conflicting with D211
+    "D213",   # "multi-line-summary-second-line" conflicting with D212
+    "COM812", # flake8-commas "Trailing comma missing"
+    "ISC001", # flake8-implicit-str-concat
+]
+isort.lines-after-imports = 2
+isort.no-lines-before = ["standard-library", "local-folder"]
+pylint.max-args = 10  # HTTP-method APIs are kwarg-rich (headers, params, cookies, timeout, json, content, response_model, …); default 5 is too strict.
+
+[tool.ruff.lint.per-file-ignores]
+# AsyncClient's HTTP-method `timeout=` is a config-value parameter forwarded to the transport,
+# not asyncio.timeout territory. The rule fires on 24+ method signatures in this one file with
+# the same false-positive justification; per-file disable is cleaner than 24 per-line noqa.
+"src/httpware/client.py" = ["ASYNC109"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=src/httpware --cov-report term-missing -m 'not perf'"
+asyncio_mode = "auto"
+pythonpath = ["src"]
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "perf: assertive performance tests (skipped by default; run with `pytest -m perf`)",
+]
+
+[tool.coverage]
+run.concurrency = ["thread"]
+run.omit = ["benchmarks/*"]
+report.exclude_also = ["if typing.TYPE_CHECKING:"]

httpware-0.1.0/src/httpware/__init__.py

@@ -0,0 +1,67 @@
+"""httpware — resilience-first async HTTP client framework for Python."""
+
+from httpware.client import AsyncClient
+from httpware.config import ClientConfig, Limits, Timeout
+from httpware.decoders import ResponseDecoder
+from httpware.decoders.pydantic import PydanticDecoder
+from httpware.errors import (
+    STATUS_TO_EXCEPTION,
+    BadRequestError,
+    ClientError,
+    ClientStatusError,
+    ConflictError,
+    ForbiddenError,
+    InternalServerError,
+    NotFoundError,
+    RateLimitedError,
+    ServerStatusError,
+    ServiceUnavailableError,
+    StatusError,
+    TimeoutError,  # noqa: A004
+    TransportError,
+    UnauthorizedError,
+    UnprocessableEntityError,
+)
+from httpware.middleware import Middleware, Next, after_response, before_request, on_error
+from httpware.request import Request
+from httpware.response import Response, StreamResponse
+from httpware.transports import Transport
+from httpware.transports.httpx2 import Httpx2Transport
+from httpware.transports.recorded import RecordedTransport
+
+
+__all__ = [
+    "STATUS_TO_EXCEPTION",
+    "AsyncClient",
+    "BadRequestError",
+    "ClientConfig",
+    "ClientError",
+    "ClientStatusError",
+    "ConflictError",
+    "ForbiddenError",
+    "Httpx2Transport",
+    "InternalServerError",
+    "Limits",
+    "Middleware",
+    "Next",
+    "NotFoundError",
+    "PydanticDecoder",
+    "RateLimitedError",
+    "RecordedTransport",
+    "Request",
+    "Response",
+    "ResponseDecoder",
+    "ServerStatusError",
+    "ServiceUnavailableError",
+    "StatusError",
+    "StreamResponse",
+    "Timeout",
+    "TimeoutError",
+    "Transport",
+    "TransportError",
+    "UnauthorizedError",
+    "UnprocessableEntityError",
+    "after_response",
+    "before_request",
+    "on_error",
+]

httpware-0.1.0/src/httpware/_internal/__init__.py

@@ -0,0 +1 @@
+"""Private cross-module helpers (not part of the public API)."""

httpware-0.1.0/src/httpware/_internal/chain.py

@@ -0,0 +1,39 @@
+"""Middleware chain composition — wires a middleware list against a Transport.
+
+Private helper. AsyncClient calls `compose` at construction time and stores the
+returned `Next` callable; per-request dispatch awaits that callable.
+"""
+
+from collections.abc import Sequence
+
+from httpware.middleware import Middleware, Next
+from httpware.request import Request
+from httpware.response import Response
+from httpware.transports import Transport
+
+
+def compose(middlewares: Sequence[Middleware], transport: Transport) -> Next:
+    """Fold `middlewares` into a single `Next` callable terminating at `transport`.
+
+    The outermost middleware in the input sequence is the first to receive the
+    request; its `next` argument forwards to the next middleware, and so on,
+    until the innermost middleware's `next` calls `transport.__call__`. An
+    empty sequence returns `transport.__call__` directly.
+
+    The returned callable is reusable across many requests; it captures
+    references to `middlewares` and `transport` by closure.
+    """
+    chain: Next = transport.__call__
+    for middleware in reversed(middlewares):
+        chain = _wrap(middleware, chain)
+    return chain
+
+
+def _wrap(middleware: Middleware, next_call: Next) -> Next:
+    async def _call(request: Request) -> Response:
+        return await middleware(request, next_call)
+
+    return _call
+
+
+__all__ = ["compose"]

httpware-0.1.0/src/httpware/_internal/import_checker.py

@@ -0,0 +1,6 @@
+"""Detect optional extras without importing them. Used by adapter modules to gate hard imports."""
+
+from importlib.util import find_spec
+
+
+is_msgspec_installed = find_spec("msgspec") is not None