headgate 0.2.0__py3-none-any.whl

headgate/__init__.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""headgate: an async HTTP base client with retry, rate limiting, circuit breaking and declared responses.
+
+Built on ``httpx2``; Python 3.14 or newer. A client subclasses :class:`AsyncBaseClient`, configures it with a
+:class:`Rate` (or a shared :class:`RateBudget`) and optionally :class:`TransportPolicy` and :class:`HttpOptions`, and
+picks a codec flavor by importing ``headgate.msgspec`` or ``headgate.pydantic``. Re-exported here:
+
+* the client and its options: :class:`AsyncBaseClient`, :data:`Method`, :class:`RequestOptions`,
+  :class:`TransportPolicy`, :class:`HttpOptions`, :class:`Timeouts`, :class:`IdempotencyKeys`, :class:`Route`,
+  :class:`Middleware`, :class:`Observer`;
+* declared responses: :class:`Expect`, :data:`Reader` and the readers, :data:`RefusalCheck`, :class:`RefusedError`;
+* auth: :class:`StaticHeaderAuth`, :class:`QueryParamAuth`, :class:`CachedTokenAuth`, :class:`Minted`,
+  :data:`MAX_MINT_RESPONSE_BYTES`;
+* the policy values: retry (:class:`RetryPolicy`, :class:`Backoff`, :class:`RetryBudget`, :class:`Hedge`,
+  :data:`NO_RETRY`), the breaker (:class:`BreakerPolicy`, :class:`BreakerRegistry`), rate limiting (:class:`Rate`,
+  :class:`RateBudget`, :class:`RateRule`, :class:`Adaptive`) and the cache (:class:`HttpCache`, its filters,
+  :class:`Partition`, :func:`conditional`);
+* streams and pages: :class:`Stream`, :meth:`AsyncBaseClient.paginate`'s :class:`Paginated` and its pagers;
+* the errors, all under :class:`ClientError`.
+
+The policy layers are subpackages with public paths of their own (:mod:`headgate.retry`, :mod:`headgate.breaker`,
+:mod:`headgate.ratelimit`, :mod:`headgate.cache`, :mod:`headgate.security`, :mod:`headgate.streaming`,
+:mod:`headgate.pagination`); events are in :mod:`headgate.events` and the testing kit in :mod:`headgate.testing`.
+"""
+
+from headgate._auth import MAX_MINT_RESPONSE_BYTES, CachedTokenAuth, Minted, QueryParamAuth, StaticHeaderAuth
+from headgate._client import AsyncBaseClient, Method, RequestOptions
+from headgate._core import Observer
+from headgate._middleware import Middleware
+from headgate._options import HttpOptions, IdempotencyKeys, Route, Timeouts, TransportPolicy
+from headgate._responses import Expect, Reader, RefusalCheck, RefusedError, as_bytes, event_stream, json_reader, nothing
+from headgate.breaker import BreakerPolicy, BreakerRegistry
+from headgate.cache import (
+    Fresh,
+    HttpCache,
+    MethodFilter,
+    NotModified,
+    Partition,
+    PathFragmentFilter,
+    StatusCodeFilter,
+    Validator,
+    conditional,
+)
+from headgate.errors import (
+    AuthError,
+    CircuitOpenError,
+    ClientConfigurationError,
+    ClientError,
+    ClientTimeoutError,
+    DecodeError,
+    ForbiddenDestinationError,
+    Problem,
+    RateLimitError,
+    ResponseParseError,
+    ResponseTooLargeError,
+    TransportError,
+    UpstreamStatusError,
+)
+from headgate.pagination import Cursor, LinkHeader, NextUrl, Offset, Pager, PageRequest, Paginated
+from headgate.ratelimit import Adaptive, Rate, RateBudget, RateRule
+from headgate.retry import NO_RETRY, Backoff, Hedge, RetryBudget, RetryPolicy
+from headgate.streaming import Stream
+
+__all__ = [
+    "MAX_MINT_RESPONSE_BYTES",
+    "NO_RETRY",
+    "Adaptive",
+    "AsyncBaseClient",
+    "AuthError",
+    "Backoff",
+    "BreakerPolicy",
+    "BreakerRegistry",
+    "CachedTokenAuth",
+    "CircuitOpenError",
+    "ClientConfigurationError",
+    "ClientError",
+    "ClientTimeoutError",
+    "Cursor",
+    "DecodeError",
+    "Expect",
+    "ForbiddenDestinationError",
+    "Fresh",
+    "Hedge",
+    "HttpCache",
+    "HttpOptions",
+    "IdempotencyKeys",
+    "LinkHeader",
+    "Method",
+    "MethodFilter",
+    "Middleware",
+    "Minted",
+    "NextUrl",
+    "NotModified",
+    "Observer",
+    "Offset",
+    "PageRequest",
+    "Pager",
+    "Paginated",
+    "Partition",
+    "PathFragmentFilter",
+    "Problem",
+    "QueryParamAuth",
+    "Rate",
+    "RateBudget",
+    "RateLimitError",
+    "RateRule",
+    "Reader",
+    "RefusalCheck",
+    "RefusedError",
+    "RequestOptions",
+    "ResponseParseError",
+    "ResponseTooLargeError",
+    "RetryBudget",
+    "RetryPolicy",
+    "Route",
+    "StaticHeaderAuth",
+    "StatusCodeFilter",
+    "Stream",
+    "Timeouts",
+    "TransportError",
+    "TransportPolicy",
+    "UpstreamStatusError",
+    "Validator",
+    "as_bytes",
+    "conditional",
+    "event_stream",
+    "json_reader",
+    "nothing",
+]

headgate/_attempts.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""The attempt layer: reports every send of a call to the client's observers as an ``AttemptFinished`` event.
+
+It sits directly under the retry layer (see :mod:`headgate._stack`), which begins each attempt on the call's context
+before sending it, so the attempt number is read when the send starts; and it is installed only on a client with
+observers.
+"""
+
+from __future__ import annotations
+
+from typing import override
+
+import httpx2
+
+from headgate._core import AttemptFinished, CallContext
+
+__all__ = ["AttemptTransport"]
+
+
+class AttemptTransport(httpx2.AsyncBaseTransport):
+    """Emit one ``AttemptFinished`` per send: the response head's status, or the type of what the send raised."""
+
+    def __init__(self, *, transport: httpx2.AsyncBaseTransport) -> None:
+        """Report the sends made through *transport*."""
+        self._transport = transport
+
+    @override
+    async def handle_async_request(self, request: httpx2.Request) -> httpx2.Response:
+        context = CallContext.of(request)
+        # Read before the send: a hedge begins another attempt while this one is in flight.
+        attempt = context.attempt
+        started = context.clock()
+        try:
+            response = await self._transport.handle_async_request(request)
+        except BaseException as exc:
+            elapsed = context.clock() - started
+            context.emit(AttemptFinished(call=context.info, attempt=attempt, error=type(exc).__name__, elapsed=elapsed))
+            raise
+        elapsed = context.clock() - started
+        context.emit(
+            AttemptFinished(call=context.info, attempt=attempt, status_code=response.status_code, elapsed=elapsed)
+        )
+        return response
+
+    @override
+    async def aclose(self) -> None:
+        """Close the wrapped transport."""
+        await self._transport.aclose()