pyrestkit 1.2.0__py3-none-any.whl

pyrestkit/models/response/user_response.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class UserResponse:
+    id: int
+    email: str
+    first_name: str
+    last_name: str
+    avatar: str

pyrestkit/pipeline/__init__.py

@@ -0,0 +1,5 @@
+from .pipeline import RequestPipeline
+
+__all__ = [
+    "RequestPipeline",
+]

pyrestkit/pipeline/middleware.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from pyrestkit.pipeline.request_context import RequestContext
+
+
+class Middleware(ABC):
+    """
+    Base class for all middleware.
+    """
+
+    @abstractmethod
+    def process(
+        self,
+        context: RequestContext,
+    ) -> RequestContext:
+        raise NotImplementedError

pyrestkit/pipeline/middleware_chain.py

@@ -0,0 +1,11 @@
+from pyrestkit.pipeline.pipeline import RequestPipeline
+
+
+class MiddlewareChain:
+    """
+    Factory responsible for creating request pipelines.
+    """
+
+    @staticmethod
+    def build() -> RequestPipeline:
+        return RequestPipeline()

pyrestkit/pipeline/pipeline.py

@@ -0,0 +1,27 @@
+from pyrestkit.pipeline.middleware import Middleware
+from pyrestkit.pipeline.request_context import RequestContext
+
+
+class RequestPipeline:
+    """
+    Executes middleware sequentially.
+    """
+
+    def __init__(self) -> None:
+        self._middlewares: list[Middleware] = []
+
+    def add(
+        self,
+        middleware: Middleware,
+    ) -> None:
+        self._middlewares.append(middleware)
+
+    def execute(
+        self,
+        context: RequestContext,
+    ) -> RequestContext:
+
+        for middleware in self._middlewares:
+            context = middleware.process(context)
+
+        return context

pyrestkit/pipeline/request_context.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class RequestContext:
+    """
+    Represents a single HTTP request flowing through the middleware pipeline.
+    """
+
+    method: str
+    url: str
+
+    headers: dict[str, str] = field(default_factory=dict)
+
+    params: dict[str, Any] = field(default_factory=dict)
+
+    json: dict[str, Any] | None = None
+
+    data: Any = None
+
+    timeout: int = 30
+
+    kwargs: dict[str, Any] = field(default_factory=dict)

pyrestkit/response/__init__.py

@@ -0,0 +1,8 @@
+from .framework_response import FrameworkResponse, ResponseAIHelper
+from .response_body import ResponseBody
+
+__all__ = [
+    "FrameworkResponse",
+    "ResponseAIHelper",
+    "ResponseBody",
+]

pyrestkit/response/framework_response.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import is_dataclass
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import requests
+
+from pyrestkit.ai.analyzer import FailureAnalyzer
+from pyrestkit.ai.client import AIClient
+from pyrestkit.ai.config import AIConfig
+from pyrestkit.ai.exceptions import AIConfigurationError
+from pyrestkit.ai.models import FailureAnalysis, FailureContext
+from pyrestkit.response.response_body import ResponseBody
+
+if TYPE_CHECKING:
+    from pyrestkit.assertions.response_assertions import ResponseAssertions
+
+T = TypeVar("T")
+
+
+class ResponseAIHelper:
+    """
+    Optional AI helper attached to a FrameworkResponse.
+
+    It is lazy-loaded and degrades gracefully by raising a framework-specific
+    configuration error when no AI client is configured.
+    """
+
+    def __init__(self, response: FrameworkResponse) -> None:
+        self._response = response
+
+    def explain_failure(
+        self,
+        *,
+        client: AIClient | None = None,
+        config: AIConfig | None = None,
+        prompt_loader: Any | None = None,
+    ) -> FailureAnalysis:
+        if client is None:
+            if config is None:
+                raise AIConfigurationError("AI is not configured.")
+
+            client = AIClient(config=config)
+
+        analyzer = FailureAnalyzer(client, prompt_loader=prompt_loader)
+        context = FailureContext(
+            test_name="response_failure",
+            error_type="HTTPError",
+            error_message=self._response._response.reason,
+            request_method=None,
+            request_url=str(self._response._response.url or ""),
+            response_status=self._response.status,
+            response_body=self._response.text,
+        )
+
+        return analyzer.analyze(context)
+
+
+class FrameworkResponse:
+    """
+    Wrapper around requests.Response.
+
+    Adds framework features while still exposing
+    the original response.
+    """
+
+    def __init__(
+        self,
+        response: requests.Response,
+    ) -> None:
+        self._response = response
+        self._body: ResponseBody | None = None
+        self._ai_helper: ResponseAIHelper | None = None
+
+    @property
+    def raw(
+        self,
+    ) -> requests.Response:
+        return self._response
+
+    @property
+    def should(
+        self,
+    ) -> ResponseAssertions:
+        from pyrestkit.assertions.response_assertions import (
+            ResponseAssertions,
+        )
+
+        return ResponseAssertions(self)
+
+    @property
+    def status(
+        self,
+    ) -> int:
+        return self._response.status_code
+
+    @property
+    def status_code(
+        self,
+    ) -> int:
+        return self._response.status_code
+
+    @property
+    def headers(
+        self,
+    ) -> Mapping[str, str]:
+        return self._response.headers
+
+    @property
+    def ai(
+        self,
+    ) -> ResponseAIHelper:
+        if self._ai_helper is None:
+            self._ai_helper = ResponseAIHelper(self)
+
+        return self._ai_helper
+
+    @property
+    def text(
+        self,
+    ) -> str:
+        return self._response.text
+
+    @property
+    def elapsed(
+        self,
+    ) -> timedelta:
+        return self._response.elapsed
+
+    @property
+    def body(
+        self,
+    ) -> ResponseBody:
+        if self._body is None:
+            self._body = ResponseBody(
+                self._response.json(),
+            )
+
+        return self._body
+
+    def json(
+        self,
+    ) -> Any:
+        return self._response.json()
+
+    def as_model(
+        self,
+        model: type[T],
+        path: str | None = None,
+    ) -> T:
+        """
+        Deserialize a JSON object into a dataclass.
+
+        Examples:
+
+            response.as_model(User)
+
+            response.as_model(User, path="data")
+
+            response.as_model(User, path="result.user")
+        """
+        if not is_dataclass(model):
+            raise TypeError(
+                f"{model.__name__} is not a dataclass.",
+            )
+
+        data = self._get_value(path)
+
+        if not isinstance(data, dict):
+            raise TypeError(
+                "Expected a JSON object.",
+            )
+
+        return model(**data)
+
+    def _get_value(
+        self,
+        path: str | None = None,
+    ) -> Any:
+        """
+        Returns a value from the response JSON using dot notation.
+
+        Examples:
+
+            None
+                -> whole JSON
+
+            "data"
+                -> json()["data"]
+
+            "data.user"
+                -> json()["data"]["user"]
+        """
+        data = self.json()
+
+        if path is None:
+            return data
+
+        for key in path.split("."):
+            if not isinstance(data, dict):
+                raise TypeError(
+                    f"Cannot access '{key}' as the current value is not a JSON object.",
+                )
+
+            if key not in data:
+                raise KeyError(
+                    f"Path '{path}' not found in response.",
+                )
+
+            data = data[key]
+
+        return data
+
+    def as_list(
+        self,
+        model: type[T],
+        path: str | None = None,
+    ) -> list[T]:
+        """
+        Deserialize a JSON array into a list of dataclasses.
+
+        Examples:
+
+            response.as_list(User)
+
+            response.as_list(User, path="data")
+
+            response.as_list(User, path="result.users")
+        """
+        if not is_dataclass(model):
+            raise TypeError(
+                f"{model.__name__} is not a dataclass.",
+            )
+
+        data = self._get_value(path)
+
+        if not isinstance(data, list):
+            raise TypeError(
+                "Expected a JSON array.",
+            )
+
+        return [model(**item) for item in data]
+
+    def raise_for_status(
+        self,
+    ) -> None:
+        self._response.raise_for_status()
+
+    def __getattr__(
+        self,
+        name: str,
+    ) -> Any:
+        """
+        Delegate unknown attributes to requests.Response.
+        """
+        return getattr(
+            self._response,
+            name,
+        )
+
+    def __repr__(
+        self,
+    ) -> str:
+        return repr(self._response)
+
+    def __str__(
+        self,
+    ) -> str:
+        return str(self._response)

pyrestkit/response/response_body.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+
+class ResponseBody:
+    """
+    Provides attribute-style access to JSON responses.
+
+    Example:
+
+        body.first_name
+        body.data.email
+        body.users[0].email
+    """
+
+    def __init__(
+        self,
+        data: Any,
+    ) -> None:
+        self._data = data
+
+    def __getattr__(
+        self,
+        name: str,
+    ) -> Any:
+        if not isinstance(self._data, dict):
+            raise AttributeError(
+                f"'{type(self._data).__name__}' has no attribute '{name}'."
+            )
+
+        if name not in self._data:
+            raise AttributeError(f"Field '{name}' not found.")
+
+        return self._wrap(
+            self._data[name],
+        )
+
+    def __getitem__(
+        self,
+        key: Any,
+    ) -> Any:
+        return self._wrap(
+            self._data[key],
+        )
+
+    #     def __iter__(
+    #         self,
+    #     ):
+    #         if isinstance(
+    #             self._data,
+    #             list,
+    #         ):
+    #             for item in self._data:
+    #                 yield self._wrap(item)
+    #         else:
+    #             raise TypeError("ResponseBody is not iterable.")
+
+    #     from collections.abc import Iterator
+
+    # ...
+
+    def __iter__(
+        self,
+    ) -> Iterator[Any]:
+        if isinstance(
+            self._data,
+            list,
+        ):
+            for item in self._data:
+                yield self._wrap(item)
+        else:
+            raise TypeError("ResponseBody is not iterable.")
+
+    @staticmethod
+    def _wrap(
+        value: Any,
+    ) -> Any:
+        if isinstance(
+            value,
+            dict,
+        ):
+            return ResponseBody(value)
+
+        if isinstance(
+            value,
+            list,
+        ):
+            return [ResponseBody._wrap(item) for item in value]
+
+        return value
+
+    def to_dict(
+        self,
+    ) -> Any:
+        """
+        Returns the underlying JSON object.
+        """
+        return self._data
+
+    def get(
+        self,
+        path: str,
+    ) -> Any:
+        """
+        Returns a JSON value using dot notation.
+
+        Example:
+
+            body.get("data.users")
+        """
+
+        current: Any = self._data
+
+        for part in path.split("."):
+            if isinstance(current, dict):
+                if part not in current:
+                    raise AttributeError(f"Field '{path}' not found.")
+                current = current[part]
+            else:
+                raise AttributeError(f"Field '{path}' not found.")
+
+        return current

pyrestkit/retry/__init__.py

@@ -0,0 +1,5 @@
+from .retry_handler import RetryHandler
+
+__all__ = [
+    "RetryHandler",
+]

pyrestkit/retry/backoff.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import time
+
+
+class ExponentialBackoff:
+    """
+    Implements exponential backoff.
+
+    Example:
+
+    attempt=1 -> 1 sec
+
+    attempt=2 -> 2 sec
+
+    attempt=3 -> 4 sec
+
+    attempt=4 -> 8 sec
+    """
+
+    def __init__(
+        self,
+        factor: float = 1.0,
+    ) -> None:
+        self._factor = factor
+
+    def sleep(
+        self,
+        attempt: int,
+    ) -> None:
+        delay = self._factor * (2 ** (attempt - 1))
+        time.sleep(delay)

pyrestkit/retry/retry_handler.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import requests
+
+from pyrestkit.retry.backoff import ExponentialBackoff
+from pyrestkit.retry.retry_policy import RetryPolicy
+
+
+class RetryHandler:
+    """
+    Executes HTTP requests with retry support.
+    """
+
+    def __init__(
+        self,
+        policy: RetryPolicy,
+    ) -> None:
+        self._policy = policy
+        self._backoff = ExponentialBackoff(
+            factor=policy.backoff_factor,
+        )
+
+    def execute(
+        self,
+        request: Callable[..., requests.Response],
+        **kwargs: Any,
+    ) -> requests.Response:
+        last_exception: Exception | None = None
+
+        for attempt in range(
+            1,
+            self._policy.retries + 1,
+        ):
+            try:
+                response = request(**kwargs)
+
+                if response.status_code not in self._policy.retry_on_status:
+                    return response
+
+            except self._policy.retry_on_exceptions as exc:
+                last_exception = exc
+
+            if attempt < self._policy.retries:
+                self._backoff.sleep(attempt)
+
+        if last_exception is not None:
+            raise last_exception
+
+        return response

pyrestkit/retry/retry_policy.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import requests
+
+
+@dataclass(slots=True)
+class RetryPolicy:
+    """
+    Retry configuration.
+    """
+
+    retries: int = 3
+
+    backoff_factor: float = 1.0
+
+    retry_on_status: set[int] = field(
+        default_factory=lambda: {
+            500,
+            502,
+            503,
+            504,
+        },
+    )
+
+    retry_on_exceptions: tuple[
+        type[Exception],
+        ...,
+    ] = (
+        requests.exceptions.Timeout,
+        requests.exceptions.ConnectionError,
+    )

pyrestkit/serializers/response_mapper.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, cast
+
+from pyrestkit.exceptions.serialization_exception import SerializationException
+
+T = TypeVar("T")
+
+
+class ResponseMapper:
+    """
+    Maps API response dictionaries to model objects.
+    """
+
+    @staticmethod
+    def map(
+        data: dict[str, Any],
+        model: type[T],
+    ) -> T:
+        try:
+            return cast(T, model.from_dict(data))  # type: ignore[attr-defined]
+        except Exception as exc:
+            raise SerializationException(
+                f"Unable to map response to {model.__name__}"
+            ) from exc

pyrestkit/types/model_protocol.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeVar
+
+
+class ModelProtocol(Protocol):
+    @classmethod
+    def from_dict(
+        cls,
+        data: dict[str, Any],
+    ) -> ModelProtocol: ...
+
+
+T = TypeVar(
+    "T",
+    bound=ModelProtocol,
+)

pyrestkit/validators/__init__.py

@@ -0,0 +1,7 @@
+from .response_validator import ResponseValidator
+from .schema_validator import SchemaValidator
+
+__all__ = [
+    "ResponseValidator",
+    "SchemaValidator",
+]