httpware 0.10.1__tar.gz → 0.12.0__tar.gz

httpware-0.12.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: httpware
+Version: 0.12.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: httpware[pydantic,msgspec,otel] ; extra == 'all'
+Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
+Requires-Dist: opentelemetry-api>=1.20 ; extra == 'otel'
+Requires-Dist: pydantic>=2.0,<3.0 ; extra == 'pydantic'
+Requires-Python: >=3.11, <4
+Project-URL: repository, https://github.com/modern-python/httpware
+Project-URL: docs, https://httpware.modern-python.org
+Provides-Extra: all
+Provides-Extra: msgspec
+Provides-Extra: otel
+Provides-Extra: pydantic
+Description-Content-Type: text/markdown
+
+# httpware
+
+[![PyPI version](https://img.shields.io/pypi/v/httpware.svg)](https://pypi.org/project/httpware/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![Downloads](https://img.shields.io/pypi/dm/httpware.svg)](https://pypistats.org/packages/httpware)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![CI](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/modern-python/httpware.svg)](https://github.com/modern-python/httpware/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/modern-python/httpware)](https://github.com/modern-python/httpware/stargazers)
+[![Context7](https://img.shields.io/badge/Context7-docs-blue)](https://context7.com/modern-python/httpware)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
+
+## Why httpware
+
+- **Typed errors, no `raise_for_status()`** — 4xx/5xx automatically raise a status-keyed exception tree (`NotFoundError`, `RateLimitedError`, …), all under `httpware.StatusError`.
+- **Typed response bodies** — `response_model=YourType` decodes the body straight to your pydantic or msgspec model; a missing decoder fails fast, *before* the request goes out.
+- **Production resilience as composable middleware** — retry + retry-budget, bulkhead, circuit breaker, and timeout, composed at construction — all over standard `httpx2`.
+
+Built on `httpx2`: httpware re-exports `httpx2.Request`/`httpx2.Response` and stays a thin wrapper, not a new HTTP abstraction.
+
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
+
+## Install
+
+```bash
+pip install httpware                # core only — no decoder
+pip install httpware[pydantic]      # + PydanticDecoder — BaseModel, dataclasses, primitives, generics
+pip install httpware[msgspec]       # + MsgspecDecoder — Struct, dataclasses, primitives, generics
+pip install httpware[pydantic,msgspec]   # both — BaseModel routes to pydantic, Struct to msgspec
+pip install httpware[all]           # everything (pydantic, msgspec, otel)
+```
+
+## Quickstart
+
+A typed GET against a live API (needs `pip install httpware[pydantic]`):
+
+```python
+import asyncio
+
+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://jsonplaceholder.typicode.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)  # Leanne Graham
+
+
+asyncio.run(main())
+```
+
+The sync `Client` is identical — swap `AsyncClient` → `Client` and drop the `await` / `async with`. A 4xx/5xx response raises a typed `StatusError`; a malformed body raises `DecodeError`. Both subclass `httpware.ClientError`.
+
+## Documentation
+
+Full guides live at **[httpware.modern-python.org](https://httpware.modern-python.org)**:
+
+- **[Quickstart & observability](https://httpware.modern-python.org/)** — resilience middleware, streaming, and the stable logger/event contract.
+- **[Middleware](https://httpware.modern-python.org/middleware/)** — write your own (auth, tracing, request-ID propagation).
+- **[Resilience](https://httpware.modern-python.org/resilience/)** — retry + retry-budget, bulkhead, circuit breaker, timeout.
+- **[Errors](https://httpware.modern-python.org/errors/)** — the exception tree and catching strategies.
+- **[Testing](https://httpware.modern-python.org/testing/)** — `httpx2.MockTransport` injection.
+- **[Recipes](https://httpware.modern-python.org/recipes/modern-di/)** — DI wiring, phase-decorator patterns, link-header pagination.
+
+## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases) · 📦 [PyPI](https://pypi.org/project/httpware) · 📝 [License](LICENSE)
+
+## 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.

httpware-0.12.0/README.md

@@ -0,0 +1,80 @@
+# httpware
+
+[![PyPI version](https://img.shields.io/pypi/v/httpware.svg)](https://pypi.org/project/httpware/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/httpware.svg)](https://pypi.org/project/httpware/)
+[![Downloads](https://img.shields.io/pypi/dm/httpware.svg)](https://pypistats.org/packages/httpware)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![CI](https://github.com/modern-python/httpware/actions/workflows/ci.yml/badge.svg)](https://github.com/modern-python/httpware/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/modern-python/httpware.svg)](https://github.com/modern-python/httpware/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/modern-python/httpware)](https://github.com/modern-python/httpware/stargazers)
+[![Context7](https://img.shields.io/badge/Context7-docs-blue)](https://context7.com/modern-python/httpware)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+**A Python HTTP client framework with sync and async clients for building resilient service clients.**
+
+## Why httpware
+
+- **Typed errors, no `raise_for_status()`** — 4xx/5xx automatically raise a status-keyed exception tree (`NotFoundError`, `RateLimitedError`, …), all under `httpware.StatusError`.
+- **Typed response bodies** — `response_model=YourType` decodes the body straight to your pydantic or msgspec model; a missing decoder fails fast, *before* the request goes out.
+- **Production resilience as composable middleware** — retry + retry-budget, bulkhead, circuit breaker, and timeout, composed at construction — all over standard `httpx2`.
+
+Built on `httpx2`: httpware re-exports `httpx2.Request`/`httpx2.Response` and stays a thin wrapper, not a new HTTP abstraction.
+
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
+
+## Install
+
+```bash
+pip install httpware                # core only — no decoder
+pip install httpware[pydantic]      # + PydanticDecoder — BaseModel, dataclasses, primitives, generics
+pip install httpware[msgspec]       # + MsgspecDecoder — Struct, dataclasses, primitives, generics
+pip install httpware[pydantic,msgspec]   # both — BaseModel routes to pydantic, Struct to msgspec
+pip install httpware[all]           # everything (pydantic, msgspec, otel)
+```
+
+## Quickstart
+
+A typed GET against a live API (needs `pip install httpware[pydantic]`):
+
+```python
+import asyncio
+
+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://jsonplaceholder.typicode.com") as client:
+        user = await client.get("/users/1", response_model=User)
+        print(user.name)  # Leanne Graham
+
+
+asyncio.run(main())
+```
+
+The sync `Client` is identical — swap `AsyncClient` → `Client` and drop the `await` / `async with`. A 4xx/5xx response raises a typed `StatusError`; a malformed body raises `DecodeError`. Both subclass `httpware.ClientError`.
+
+## Documentation
+
+Full guides live at **[httpware.modern-python.org](https://httpware.modern-python.org)**:
+
+- **[Quickstart & observability](https://httpware.modern-python.org/)** — resilience middleware, streaming, and the stable logger/event contract.
+- **[Middleware](https://httpware.modern-python.org/middleware/)** — write your own (auth, tracing, request-ID propagation).
+- **[Resilience](https://httpware.modern-python.org/resilience/)** — retry + retry-budget, bulkhead, circuit breaker, timeout.
+- **[Errors](https://httpware.modern-python.org/errors/)** — the exception tree and catching strategies.
+- **[Testing](https://httpware.modern-python.org/testing/)** — `httpx2.MockTransport` injection.
+- **[Recipes](https://httpware.modern-python.org/recipes/modern-di/)** — DI wiring, phase-decorator patterns, link-header pagination.
+
+## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases) · 📦 [PyPI](https://pypi.org/project/httpware) · 📝 [License](LICENSE)
+
+## 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.

{httpware-0.10.1 → httpware-0.12.0}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.10.1"
+version = "0.12.0"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]
@@ -97,4 +97,4 @@ asyncio_default_fixture_loop_scope = "function"
 
 [tool.coverage]
 run.concurrency = ["thread"]
-report.exclude_also = ["if typing.TYPE_CHECKING:"]
+report.exclude_also = ["if typing.TYPE_CHECKING:", 'pytest\.fail\(']

{httpware-0.10.1 → httpware-0.12.0}/src/httpware/__init__.py

@@ -17,6 +17,7 @@ from httpware.errors import (
     NetworkError,
     NotFoundError,
     RateLimitedError,
+    ResponseTooLargeError,
     RetryBudgetExhaustedError,
     ServerStatusError,
     ServiceUnavailableError,
@@ -78,6 +79,7 @@ __all__ = [
     "NotFoundError",
     "RateLimitedError",
     "ResponseDecoder",
+    "ResponseTooLargeError",
     "Retry",
     "RetryBudget",
     "RetryBudgetExhaustedError",

{httpware-0.10.1 → httpware-0.12.0}/src/httpware/_internal/observability.py

@@ -13,6 +13,7 @@ import logging
 import typing
 
 from httpware._internal import import_checker
+from httpware._internal.redaction import redact_url
 
 
 def _emit_event(
@@ -25,6 +26,12 @@ def _emit_event(
 ) -> None:
     """Emit one observability event to both channels.
 
+    The ``url`` attribute, when present, is run through
+    ``redaction.redact_url`` here — at the single emission boundary — so a
+    request URL's userinfo and known-sensitive query/fragment secrets never
+    reach a log record or span event, regardless of how a caller built the
+    attributes dict.
+
     1. Always emits a structured log record at ``level`` with ``extra=attributes``
        (so log aggregators that index ``extra`` see structured fields).
     2. If ``opentelemetry-api`` is installed, calls
@@ -39,7 +46,9 @@ def _emit_event(
     the optional-extras isolation invariant: ``import httpware`` must not pull
     ``opentelemetry`` into ``sys.modules`` when the extra is absent.
     """
-    logger.log(level, message, extra={**attributes, "event": event_name})
+    raw_url = attributes.get("url")
+    safe_attributes = {**attributes, "url": redact_url(raw_url)} if isinstance(raw_url, str) else attributes
+    logger.log(level, message, extra={**safe_attributes, "event": event_name})
     if import_checker.is_otel_installed:
         try:
             from opentelemetry import trace  # noqa: PLC0415 — lazy by design (optional-extras isolation)
@@ -52,4 +61,4 @@ def _emit_event(
         # The structured log record above has already fired; CancelledError/KeyboardInterrupt
         # are not Exception subclasses and will still propagate.
         with contextlib.suppress(Exception):
-            trace.get_current_span().add_event(event_name, attributes=attributes)
+            trace.get_current_span().add_event(event_name, attributes=safe_attributes)

httpware-0.12.0/src/httpware/_internal/redaction.py

@@ -0,0 +1,116 @@
+"""URL sanitation for logs, telemetry, and error messages.
+
+Strips ``user:pass@`` userinfo and masks the values of known-sensitive query
+parameters so secrets embedded in URLs do not leak into observability output.
+Shared by ``errors.py`` (StatusError messages) and the resilience middleware
+(event attributes).
+"""
+
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+
+SENSITIVE_QUERY_KEYS = frozenset(
+    {
+        "api_key",
+        "apikey",
+        "access_token",
+        "refresh_token",
+        "token",
+        "secret",
+        "client_secret",
+        "password",
+        "passwd",
+        "pwd",
+        "auth",
+        "authorization",
+        "sig",
+        "signature",
+        "key",
+        "private_key",
+        "session",
+        "sessionid",
+        "x-api-key",
+    }
+)
+
+_REDACTED = "REDACTED"
+
+
+def _reassemble(scheme: str, netloc: str, path: str, query: str, fragment: str) -> str:
+    """Like ``urlunsplit``, but avoid the spurious triple-slash for an empty authority.
+
+    ``urlunsplit(("http", "", "/path", ...))`` yields ``http:///path`` for a
+    netloc-using scheme. When userinfo stripping leaves no host (e.g.
+    ``http://user:pass@/path``) we want ``http:/path`` (scheme + path), not a
+    triple-slash. With a non-empty netloc this delegates to ``urlunsplit``, so
+    normal URLs are byte-identical.
+    """
+    if netloc:
+        return urlunsplit((scheme, netloc, path, query, fragment))
+    tail = path
+    if query:
+        tail += "?" + query
+    if fragment:
+        tail += "#" + fragment
+    return f"{scheme}:{tail}" if scheme else tail
+
+
+def _strip_userinfo(url: str) -> str:
+    if "@" not in url or "://" not in url:
+        return url
+    parts = urlsplit(url)
+    if parts.username is None and parts.password is None:
+        return url
+    # Strip the "user:pass@" prefix from the raw netloc to preserve host:port
+    # exactly (including IPv6 brackets), rather than reconstructing from parts.
+    netloc = parts.netloc.split("@", 1)[1] if "@" in parts.netloc else parts.netloc
+    return _reassemble(parts.scheme, netloc, parts.path, parts.query, parts.fragment)
+
+
+def _mask_component(component: str) -> tuple[str, bool]:
+    """Mask sensitive key=value pairs in a query or fragment string.
+
+    Returns ``(masked_component, was_changed)``; when no sensitive key is
+    found the original string is returned unchanged (``was_changed=False``).
+    """
+    pairs = parse_qsl(component, keep_blank_values=True)
+    if not any(key.strip().lower() in SENSITIVE_QUERY_KEYS for key, _ in pairs):
+        return component, False
+    masked = [(key, _REDACTED if key.strip().lower() in SENSITIVE_QUERY_KEYS else value) for key, value in pairs]
+    return urlencode(masked), True
+
+
+def _mask_query(url: str) -> str:
+    parts = urlsplit(url)
+    has_query = bool(parts.query)
+    has_fragment = bool(parts.fragment)
+
+    if not has_query and not has_fragment:
+        return url
+
+    new_query = parts.query
+    new_fragment = parts.fragment
+    changed = False
+
+    if has_query:
+        new_query, q_changed = _mask_component(parts.query)
+        changed = changed or q_changed
+
+    if has_fragment:
+        new_fragment, f_changed = _mask_component(parts.fragment)
+        changed = changed or f_changed
+
+    if not changed:
+        return url  # common-path guard: nothing sensitive, leave bytes untouched
+
+    return _reassemble(parts.scheme, parts.netloc, parts.path, new_query, new_fragment)
+
+
+def redact_url(url: str) -> str:
+    """Return ``url`` safe for logs/telemetry/errors.
+
+    Userinfo is stripped and the values of known-sensitive query parameters are
+    replaced with ``REDACTED`` (keys preserved). URLs with no sensitive query
+    key are returned byte-identical to the userinfo-stripped input.
+    """
+    return _mask_query(_strip_userinfo(url))

{httpware-0.10.1 → httpware-0.12.0}/src/httpware/_internal/status.py

@@ -29,19 +29,24 @@ def _raise_on_status_error(response: httpx2.Response) -> None:
         raise exc_class(response)
 
 
+def _is_replayable_type(value: object) -> bool:
+    """Return True if value is a replayable type (safe to replay across retry attempts)."""
+    return isinstance(value, (bytes, bytearray, memoryview, str, dict, list, tuple))
+
+
 def _is_streaming_body_async(value: object) -> bool:
-    """Return True if value is an async-iterable that cannot be safely replayed for retry."""
+    """Return True if value is a non-replayable body (async-iterable or sync non-replayable iterable)."""
     if value is None:
         return False
-    if isinstance(value, (bytes, bytearray, memoryview, str, dict)):
+    if _is_replayable_type(value):
         return False
-    return hasattr(value, "__aiter__")
+    return hasattr(value, "__aiter__") or hasattr(value, "__iter__")
 
 
 def _is_streaming_body_sync(value: object) -> bool:
     """Return True if value is a sync iterable body that cannot be safely replayed for retry."""
     if value is None:
         return False
-    if isinstance(value, (bytes, bytearray, memoryview, str, dict, list, tuple)):
+    if _is_replayable_type(value):
         return False
     return hasattr(value, "__iter__")