asyncly 0.6.2__tar.gz → 0.7.1__tar.gz

asyncly-0.7.1/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: asyncly
+Version: 0.7.1
+Summary: Simple HTTP client and server for your integrations based on aiohttp
+Project-URL: Homepage, https://github.com/andy-takker/asyncly
+Project-URL: Documentation, https://andy-takker.github.io/asyncly/
+Project-URL: Source, https://github.com/andy-takker/asyncly
+Project-URL: Bug Tracker, https://github.com/andy-takker/asyncly/issues
+Author-email: Sergey Natalenko <sergey.natalenko@mail.ru>
+License-Expression: MIT
+Keywords: aiohttp,client,http
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pytest
+Classifier: Framework :: aiohttp
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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: Topic :: Internet
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4,>=3.10
+Requires-Dist: aiohttp<4,>=3.13.3
+Provides-Extra: msgspec
+Requires-Dist: msgspec<0.20,>=0.19.0; extra == 'msgspec'
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-sdk>=1.37.0; extra == 'opentelemetry'
+Provides-Extra: orjson
+Requires-Dist: orjson<4,>=3.10.6; extra == 'orjson'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.22.1; extra == 'prometheus'
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3,>=2.8.2; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# Asyncly
+
+[![PyPI version](https://img.shields.io/pypi/v/asyncly.svg)](https://pypi.org/project/asyncly/)
+[![Python versions](https://img.shields.io/pypi/pyversions/asyncly.svg)](https://pypi.org/project/asyncly/)
+[![License](https://img.shields.io/pypi/l/asyncly.svg)](https://pypi.org/project/asyncly/)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://andy-takker.github.io/asyncly/)
+
+**A tiny async HTTP client and a *real* aiohttp mock server for testing your integrations — built on [aiohttp](https://docs.aiohttp.org/).**
+
+asyncly gives you two pieces that fit together:
+
+- **`BaseHttpClient`** — a thin, typed base class for HTTP clients with per-status
+  response handlers, flexible timeouts, and first-class proxy support.
+- **`srvmocker`** — spin up a *real* aiohttp test server (not a transport patch)
+  to simulate upstreams in tests, assert what your client sent, and even route
+  through a mock proxy.
+
+📖 **[Read the full documentation →](https://andy-takker.github.io/asyncly/)**
+
+## Installation
+
+```bash
+pip install asyncly
+```
+
+Optional extras — `msgspec`, `pydantic`, `orjson`, `prometheus`, `opentelemetry`:
+
+```bash
+pip install "asyncly[pydantic]"
+```
+
+## Quickstart
+
+Define a client by subclassing `BaseHttpClient` and mapping status codes to handlers:
+
+```python
+from http import HTTPStatus
+from types import MappingProxyType
+
+from aiohttp import ClientSession, hdrs
+from pydantic import BaseModel
+
+from asyncly import BaseHttpClient, DEFAULT_TIMEOUT, ResponseHandlersType
+from asyncly.client.handlers.pydantic import parse_model
+from asyncly.client.timeout import TimeoutType
+
+
+class CatFact(BaseModel):
+    fact: str
+    length: int
+
+
+class CatfactClient(BaseHttpClient):
+    FACT_HANDLERS: ResponseHandlersType = MappingProxyType(
+        {HTTPStatus.OK: parse_model(CatFact)}
+    )
+
+    async def fetch_fact(self, timeout: TimeoutType = DEFAULT_TIMEOUT) -> CatFact:
+        return await self._make_req(
+            method=hdrs.METH_GET,
+            url=self._url / "fact",
+            handlers=self.FACT_HANDLERS,
+            timeout=timeout,
+        )
+```
+
+Test it against a real mock server — no network, no monkeypatching:
+
+```python
+from asyncly.srvmocker import JsonResponse, MockRoute, start_service
+
+
+async def test_fetch_fact() -> None:
+    routes = [MockRoute("GET", "/fact", "fact")]
+    async with start_service(routes) as service:
+        service.register("fact", JsonResponse({"fact": "Cats sleep a lot.", "length": 17}))
+
+        async with ClientSession() as session:
+            client = CatfactClient(url=service.url, session=session, client_name="catfact")
+            fact = await client.fetch_fact()
+
+        assert fact.fact == "Cats sleep a lot."
+        service.assert_called("fact", times=1)
+```
+
+Prefer fixtures over boilerplate? asyncly ships a pytest plugin with `mock_service`
+and `mock_proxy`. See the [Quickstart](https://andy-takker.github.io/asyncly/) for more.
+
+## Why asyncly?
+
+Unlike transport-patching mocks (`aioresponses`, `respx`), `srvmocker` runs a real
+`aiohttp.TestServer` inside your test loop — catching real sockets, timeouts, header
+auto-injection, and serialization quirks. See
+[Testing strategies](https://andy-takker.github.io/asyncly/) for the full comparison.
+
+## License
+
+[MIT](https://github.com/andy-takker/asyncly/blob/master/LICENSE)

asyncly-0.7.1/README.md

@@ -0,0 +1,98 @@
+# Asyncly
+
+[![PyPI version](https://img.shields.io/pypi/v/asyncly.svg)](https://pypi.org/project/asyncly/)
+[![Python versions](https://img.shields.io/pypi/pyversions/asyncly.svg)](https://pypi.org/project/asyncly/)
+[![License](https://img.shields.io/pypi/l/asyncly.svg)](https://pypi.org/project/asyncly/)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://andy-takker.github.io/asyncly/)
+
+**A tiny async HTTP client and a *real* aiohttp mock server for testing your integrations — built on [aiohttp](https://docs.aiohttp.org/).**
+
+asyncly gives you two pieces that fit together:
+
+- **`BaseHttpClient`** — a thin, typed base class for HTTP clients with per-status
+  response handlers, flexible timeouts, and first-class proxy support.
+- **`srvmocker`** — spin up a *real* aiohttp test server (not a transport patch)
+  to simulate upstreams in tests, assert what your client sent, and even route
+  through a mock proxy.
+
+📖 **[Read the full documentation →](https://andy-takker.github.io/asyncly/)**
+
+## Installation
+
+```bash
+pip install asyncly
+```
+
+Optional extras — `msgspec`, `pydantic`, `orjson`, `prometheus`, `opentelemetry`:
+
+```bash
+pip install "asyncly[pydantic]"
+```
+
+## Quickstart
+
+Define a client by subclassing `BaseHttpClient` and mapping status codes to handlers:
+
+```python
+from http import HTTPStatus
+from types import MappingProxyType
+
+from aiohttp import ClientSession, hdrs
+from pydantic import BaseModel
+
+from asyncly import BaseHttpClient, DEFAULT_TIMEOUT, ResponseHandlersType
+from asyncly.client.handlers.pydantic import parse_model
+from asyncly.client.timeout import TimeoutType
+
+
+class CatFact(BaseModel):
+    fact: str
+    length: int
+
+
+class CatfactClient(BaseHttpClient):
+    FACT_HANDLERS: ResponseHandlersType = MappingProxyType(
+        {HTTPStatus.OK: parse_model(CatFact)}
+    )
+
+    async def fetch_fact(self, timeout: TimeoutType = DEFAULT_TIMEOUT) -> CatFact:
+        return await self._make_req(
+            method=hdrs.METH_GET,
+            url=self._url / "fact",
+            handlers=self.FACT_HANDLERS,
+            timeout=timeout,
+        )
+```
+
+Test it against a real mock server — no network, no monkeypatching:
+
+```python
+from asyncly.srvmocker import JsonResponse, MockRoute, start_service
+
+
+async def test_fetch_fact() -> None:
+    routes = [MockRoute("GET", "/fact", "fact")]
+    async with start_service(routes) as service:
+        service.register("fact", JsonResponse({"fact": "Cats sleep a lot.", "length": 17}))
+
+        async with ClientSession() as session:
+            client = CatfactClient(url=service.url, session=session, client_name="catfact")
+            fact = await client.fetch_fact()
+
+        assert fact.fact == "Cats sleep a lot."
+        service.assert_called("fact", times=1)
+```
+
+Prefer fixtures over boilerplate? asyncly ships a pytest plugin with `mock_service`
+and `mock_proxy`. See the [Quickstart](https://andy-takker.github.io/asyncly/) for more.
+
+## Why asyncly?
+
+Unlike transport-patching mocks (`aioresponses`, `respx`), `srvmocker` runs a real
+`aiohttp.TestServer` inside your test loop — catching real sockets, timeouts, header
+auto-injection, and serialization quirks. See
+[Testing strategies](https://andy-takker.github.io/asyncly/) for the full comparison.
+
+## License
+
+[MIT](https://github.com/andy-takker/asyncly/blob/master/LICENSE)

asyncly-0.7.1/asyncly/client/base.py

@@ -0,0 +1,117 @@
+from typing import Any
+
+from aiohttp import BasicAuth, ClientSession
+from aiohttp.client import DEFAULT_TIMEOUT
+from yarl import URL
+
+from asyncly.client.handlers.base import (
+    ResponseHandlersType,
+    apply_handler,
+)
+from asyncly.client.timeout import TimeoutType, get_timeout
+from asyncly.client.typing import MethodType
+
+
+class BaseHttpClient:
+    """Typed base class for building async HTTP API clients.
+
+    Subclass it and add one method per endpoint, delegating to ``_make_req``
+    with a mapping of status codes to response handlers. The
+    `aiohttp.ClientSession` is injected, so connection pooling and lifecycle
+    stay under your control.
+
+    Example:
+        ```python
+        class CatfactClient(BaseHttpClient):
+            FACT_HANDLERS = MappingProxyType({HTTPStatus.OK: parse_model(CatFact)})
+
+            async def fetch_fact(self) -> CatFact:
+                return await self._make_req(
+                    method=hdrs.METH_GET,
+                    url=self._url / "fact",
+                    handlers=self.FACT_HANDLERS,
+                )
+        ```
+    """
+
+    __slots__ = ("_url", "_session", "_client_name", "_proxy", "_proxy_auth")
+
+    _url: URL
+    _session: ClientSession
+    _client_name: str
+    _proxy: URL | None
+    _proxy_auth: BasicAuth | None
+
+    def __init__(
+        self,
+        url: URL | str,
+        session: ClientSession,
+        client_name: str,
+        *,
+        proxy: URL | str | None = None,
+        proxy_auth: BasicAuth | None = None,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            url: Base URL the client's endpoints are resolved against.
+            session: The `aiohttp.ClientSession` to issue requests with. The
+                caller owns its lifecycle.
+            client_name: Identifier used in metrics labels and error messages.
+            proxy: Default proxy URL for every request. Can be overridden
+                per request by passing `proxy=` to `_make_req`.
+            proxy_auth: Default `BasicAuth` credentials for the proxy.
+        """
+        self._url = url if isinstance(url, URL) else URL(url)
+        self._session = session
+        self._client_name = client_name
+        self._proxy = URL(proxy) if isinstance(proxy, str) else proxy
+        self._proxy_auth = proxy_auth
+
+    @property
+    def url(self) -> URL:
+        """The base URL the client was configured with."""
+        return self._url
+
+    async def _make_req(
+        self,
+        method: MethodType,
+        url: URL,
+        handlers: ResponseHandlersType,
+        timeout: TimeoutType = DEFAULT_TIMEOUT,
+        **kwargs: Any,
+    ) -> Any:
+        """Issue a request and dispatch the response to a status handler.
+
+        Args:
+            method: HTTP method, e.g. `aiohttp.hdrs.METH_GET`.
+            url: Fully resolved request URL.
+            handlers: Mapping of status code (exact, ``"2xx"`` range, or ``"*"``
+                wildcard) to a response handler callable.
+            timeout: Per-request timeout; accepts `ClientTimeout`, `timedelta`,
+                or a number of seconds.
+            **kwargs: Extra arguments forwarded to `ClientSession.request`
+                (e.g. ``json``, ``params``, ``headers``). Instance-level
+                ``proxy`` / ``proxy_auth`` are injected here unless overridden.
+
+        Returns:
+            Whatever the matched handler returns.
+
+        Raises:
+            UnhandledStatusException: If no handler matches the response status.
+        """
+        if "proxy" not in kwargs and self._proxy is not None:
+            kwargs["proxy"] = self._proxy
+        if "proxy_auth" not in kwargs and self._proxy_auth is not None:
+            kwargs["proxy_auth"] = self._proxy_auth
+        async with self._session.request(
+            method=method,
+            url=url,
+            timeout=get_timeout(timeout),
+            **kwargs,
+        ) as response:
+            return await apply_handler(
+                handlers=handlers,
+                response=response,
+                client_name=self._client_name,
+            )

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/handlers/exceptions.py

@@ -3,10 +3,18 @@ from yarl import URL
 
 
 class BaseHttpClientException(ClientError):
-    pass
+    """Base class for exceptions raised by `BaseHttpClient`."""
 
 
 class UnhandledStatusException(BaseHttpClientException, KeyError):
+    """Raised when a response status has no matching handler.
+
+    Attributes:
+        status: The unmatched response status code.
+        url: The request URL.
+        client_name: The originating client's name, if known.
+    """
+
     status: int
     url: URL
     client_name: str | None

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/handlers/json.py

@@ -14,6 +14,18 @@ def parse_json(
     parser: Callable,
     loads: Callable = json.loads,
 ) -> Callable[[ClientResponse], Awaitable[Any]]:
+    """Build a response handler that decodes JSON and passes it to ``parser``.
+
+    Args:
+        parser: Callable applied to the decoded JSON. May be sync or async.
+            Use ``lambda data: data`` to return the parsed value unchanged.
+        loads: JSON loader. Defaults to `orjson.loads` when the ``orjson``
+            extra is installed, otherwise the stdlib `json.loads`.
+
+    Returns:
+        An async handler usable as a value in a response-handlers mapping.
+    """
+
     async def _parse(response: ClientResponse) -> Any:
         response_data = await response.json(loads=loads)
         if iscoroutinefunction(parser):

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/handlers/msgspec.py

@@ -29,6 +29,22 @@ def parse_struct(
     data_format: DataFormat = "json",
     strict: bool = True,
 ) -> Callable[[ClientResponse], Awaitable[T]]:
+    """Build a response handler that decodes the body into a msgspec struct.
+
+    Requires the ``msgspec`` extra.
+
+    Args:
+        struct: The `msgspec.Struct` subclass to decode into.
+        data_format: Wire format of the body: ``"json"``, ``"msgpack"``,
+            ``"toml"``, or ``"yaml"``.
+        strict: Pass-through to msgspec strict decoding (no implicit coercion).
+
+    Returns:
+        An async handler usable as a value in a response-handlers mapping.
+
+    Raises:
+        msgspec.ValidationError: If the payload does not match ``struct``.
+    """
     decode = _choose_decoder(data_format)
 
     async def _parse(response: ClientResponse) -> T:

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/handlers/pydantic.py

@@ -8,6 +8,20 @@ T = TypeVar("T", bound=BaseModel)
 
 
 def parse_model(model: type[T]) -> Callable[[ClientResponse], Awaitable[T]]:
+    """Build a response handler that validates the body into a Pydantic model.
+
+    Requires the ``pydantic`` extra.
+
+    Args:
+        model: The `pydantic.BaseModel` subclass to validate the JSON body into.
+
+    Returns:
+        An async handler usable as a value in a response-handlers mapping.
+
+    Raises:
+        pydantic.ValidationError: If the body does not match the model.
+    """
+
     async def _parse(response: ClientResponse) -> T:
         return model.model_validate_json(await response.read())
 

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/metrics/instrumentable_client.py

@@ -3,7 +3,7 @@ from time import perf_counter
 from types import TracebackType
 from typing import Any
 
-from aiohttp import ClientResponse, ClientSession
+from aiohttp import BasicAuth, ClientResponse, ClientSession
 from aiohttp.client import DEFAULT_TIMEOUT
 from yarl import URL
 
@@ -16,32 +16,61 @@ from asyncly.client.typing import ResponseHandler, ResponseHandlersType, RouteRe
 
 
 class InstrumentableHttpClient(BaseHttpClient):
-    __slots__ = ("_metrics_sink", "_resolve_route") + BaseHttpClient.__slots__
+    """`BaseHttpClient` that records request metrics through a pluggable sink.
+
+    Behaves exactly like [`BaseHttpClient`][asyncly.BaseHttpClient] until a sink
+    is enabled. Each completed request reports its client name, method, resolved
+    route, status, duration, and error type to the active
+    [`MetricsSink`][asyncly.client.metrics.sinks.base.MetricsSink].
+    """
+
+    __slots__ = ("_metrics_sink", "_resolve_route")
 
     def __init__(
         self,
         url: URL | str,
         session: ClientSession,
         client_name: str,
+        *,
+        proxy: URL | str | None = None,
+        proxy_auth: BasicAuth | None = None,
     ) -> None:
-        super().__init__(url=url, session=session, client_name=client_name)
+        super().__init__(
+            url=url,
+            session=session,
+            client_name=client_name,
+            proxy=proxy,
+            proxy_auth=proxy_auth,
+        )
         self._metrics_sink: MetricsSink = NoopSink()
         self._resolve_route: RouteResolver = default_route_resolver
 
     def enable_metrics(
         self, sink: MetricsSink, *, route_resolver: RouteResolver | None = None
     ) -> None:
+        """Start emitting metrics to ``sink``.
+
+        Args:
+            sink: The metrics sink to report each request to.
+            route_resolver: Optional override for how request URLs are
+                normalized into low-cardinality route labels.
+        """
         self._metrics_sink = sink
         if route_resolver is not None:
             self._resolve_route = route_resolver
 
     def disable_metrics(self) -> None:
+        """Stop emitting metrics (revert to the no-op sink)."""
         self._metrics_sink = NoopSink()
         self._resolve_route = default_route_resolver
 
     def instrument(  # type: ignore[no-untyped-def]
         self, sink: MetricsSink, *, route_resolver: RouteResolver | None = None
     ):
+        """Context manager that enables ``sink`` for the duration of a block.
+
+        Restores the previous sink and route resolver on exit.
+        """
         client = self
 
         class _Ctx:

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/metrics/route_resolver.py

@@ -2,6 +2,12 @@ from yarl import URL
 
 
 def default_route_resolver(url: URL) -> str:
+    """Normalize a URL path into a low-cardinality route label.
+
+    Numeric and UUID-like path segments are replaced with ``:id`` so that, for
+    example, ``/cats/42`` and ``/cats/7`` both map to ``/cats/:id``. Used as the
+    default route label for client metrics.
+    """
     parts: list[str] = []
     for p in url.path.split("/"):
         if not p:

asyncly-0.7.1/asyncly/client/metrics/sinks/base.py

@@ -0,0 +1,30 @@
+from typing import Protocol
+
+
+class MetricsSink(Protocol):
+    """Protocol for metrics backends used by `InstrumentableHttpClient`.
+
+    Implement `observe_request` to record requests in any backend.
+    """
+
+    def observe_request(
+        self,
+        *,
+        client: str,
+        method: str,
+        route: str,
+        status: int | str,
+        duration_seconds: float,
+        error_type: str | None = None,
+    ) -> None:
+        """Record a single completed request.
+
+        Args:
+            client: The client name (`client_name`).
+            method: HTTP method.
+            route: Normalized, low-cardinality route label.
+            status: Response status code, or a string marker on error.
+            duration_seconds: Total time including response handling.
+            error_type: Exception class name if the request failed, else None.
+        """
+        ...

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/metrics/sinks/noop.py

@@ -1,5 +1,5 @@
 class NoopSink:
-    """Синк по умолчанию: ничего не делает."""
+    """The default sink: records nothing and adds no overhead."""
 
     def observe_request(
         self,

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/metrics/sinks/opentelemetry.py

@@ -2,6 +2,14 @@ from opentelemetry.metrics import Meter
 
 
 class OpenTelemetrySink:
+    """Metrics sink backed by OpenTelemetry (needs the ``opentelemetry`` extra).
+
+    Records request counts, durations, and errors through the given `Meter`.
+
+    Args:
+        meter: An OpenTelemetry `Meter` to create instruments from.
+    """
+
     def __init__(self, meter: Meter) -> None:
         # Counter: количество
         self._req_counter = meter.create_counter(

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/client/metrics/sinks/prometheus.py

@@ -5,6 +5,18 @@ from prometheus_client.registry import REGISTRY, CollectorRegistry
 
 
 class PrometheusSink:
+    """Metrics sink that records to Prometheus (needs the ``prometheus`` extra).
+
+    Exposes a request-duration histogram and a request counter, labeled by
+    client, method, route, and status.
+
+    Args:
+        namespace: Prometheus metric namespace prefix.
+        subsystem: Prometheus metric subsystem prefix.
+        buckets: Histogram bucket boundaries in seconds.
+        registry: Collector registry to register the metrics on.
+    """
+
     def __init__(
         self,
         namespace: str = "asyncly",

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/pytest_plugin.py

@@ -18,6 +18,7 @@ import pytest
 
 if TYPE_CHECKING:
     from asyncly.srvmocker.models import MockRoute, MockService
+    from asyncly.srvmocker.proxy import MockProxyService
 
 
 @pytest.fixture
@@ -34,3 +35,12 @@ async def mock_service(
 
     async with start_service(mock_routes) as service:
         yield service
+
+
+@pytest.fixture
+async def mock_proxy() -> "AsyncIterator[MockProxyService]":
+    """A forwarding mock proxy; point a client at it via ``proxy=mock_proxy.url``."""
+    from asyncly.srvmocker import start_proxy
+
+    async with start_proxy() as proxy:
+        yield proxy

{asyncly-0.6.2 → asyncly-0.7.1}/asyncly/srvmocker/__init__.py

@@ -5,6 +5,7 @@ from asyncly.srvmocker.exceptions import (
 )
 from asyncly.srvmocker.matching import Match
 from asyncly.srvmocker.models import MockRoute, MockService
+from asyncly.srvmocker.proxy import MockProxyService, start_proxy
 from asyncly.srvmocker.responses.base import BaseMockResponse
 from asyncly.srvmocker.responses.content import ContentResponse
 from asyncly.srvmocker.responses.json import JsonResponse
@@ -17,6 +18,7 @@ __all__ = (
     "ContentResponse",
     "JsonResponse",
     "Match",
+    "MockProxyService",
     "MockRoute",
     "MockService",
     "RawResponse",
@@ -24,5 +26,6 @@ __all__ = (
     "SequenceResponse",
     "SrvMockerError",
     "UnknownHandlerError",
+    "start_proxy",
     "start_service",
 )