SymfWebAPI 1.26.10.1__py3-none-any.whl

SymfWebAPI/client.py

@@ -0,0 +1,129 @@
+"""High-level async/sync clients wrapping transport + session manager."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import Any, Awaitable, Callable, Optional
+
+from .config import ClientConfig
+from .executors import AsyncRequestExecutor, SyncRequestExecutor
+from .operations import OperationSpec
+from .response import ResponseEnvelope
+from .session import SessionManager
+
+
+class AsyncAPI(AbstractAsyncContextManager["AsyncAPI"]):
+    def __init__(
+        self,
+        config: ClientConfig,
+        session_manager: SessionManager,
+        request_fn: Callable[..., Any],
+        shutdown_hook: Optional[Callable[[], Awaitable[None]]] = None,
+    ):
+        self._config = config
+        self._session = session_manager
+        self._executor = AsyncRequestExecutor(config, session_manager, request_fn)
+        self._shutdown_hook = shutdown_hook
+
+    async def __aenter__(self) -> "AsyncAPI":
+        await self.open()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()
+
+    async def open(self) -> "AsyncAPI":
+        await self._session.ensure_async()
+        return self
+
+    async def close(self) -> None:
+        try:
+            await self._session.close_async()
+        finally:
+            if self._shutdown_hook:
+                await self._shutdown_hook()
+
+    async def ensure_session(self) -> str:
+        return await self._executor.ensure_session()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        return await self._executor.request(method, path, params=params, data=data)
+
+    def invalidate_session(self) -> None:
+        self._executor.invalidate_session()
+
+    async def invoke(
+        self,
+        operation: OperationSpec,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        envelope = await self.request(operation.method, operation.path, params=params, data=data)
+        if self._config.offload_async_parsing:
+            return await asyncio.to_thread(operation.parser, envelope)
+        return operation.parser(envelope)
+
+
+class SyncAPI(AbstractContextManager["SyncAPI"]):
+    def __init__(
+        self,
+        config: ClientConfig,
+        session_manager: SessionManager,
+        request_fn: Callable[..., Any],
+        shutdown_hook: Optional[Callable[[], None]] = None,
+    ):
+        self._session = session_manager
+        self._executor = SyncRequestExecutor(config, session_manager, request_fn)
+        self._shutdown_hook = shutdown_hook
+
+    def __enter__(self) -> "SyncAPI":
+        return self.open()
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def open(self) -> "SyncAPI":
+        self._session.ensure_sync()
+        return self
+
+    def close(self) -> None:
+        try:
+            self._session.close_sync()
+        finally:
+            if self._shutdown_hook:
+                self._shutdown_hook()
+
+    def ensure_session(self) -> str:
+        return self._executor.ensure_session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        return self._executor.request(method, path, params=params, data=data)
+
+    def invalidate_session(self) -> None:
+        self._executor.invalidate_session()
+
+    def invoke(
+        self,
+        operation: OperationSpec,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        envelope = self.request(operation.method, operation.path, params=params, data=data)
+        return operation.parser(envelope)

SymfWebAPI/config.py

@@ -0,0 +1,60 @@
+"""Konfiguracja klienta Symfonia WebAPI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import timedelta
+import re
+from typing import Final
+
+from .errors import ConfigurationError
+
+_GUID_RE: Final[re.Pattern[str]] = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+
+def _validate_guid(label: str, value: str) -> None:
+    if not _GUID_RE.fullmatch(value or ""):
+        raise ConfigurationError(f"{label} must be a GUID (got: {value!r})")
+
+
+def _validate_non_empty(label: str, value: str) -> None:
+    if not value or not value.strip():
+        raise ConfigurationError(f"{label} must be a non-empty string")
+
+
+def _validate_domain(domain: str) -> None:
+    # ClientConfig builds the scheme from `https`, so domain must not include http/https prefix.
+    if "://" in domain:
+        raise ConfigurationError("domain must not include URL scheme (use https flag instead)")
+
+
+@dataclass(slots=True)
+class ClientConfig:
+    """Podstawowe parametry wymagane do połączenia z WebAPI."""
+
+    domain: str
+    application_key: str
+    device_name: str
+    https: bool = False
+    request_timeout: float = 30.0
+    offload_async_parsing: bool = False
+    max_session_age: timedelta | None = field(
+        default_factory=lambda: timedelta(minutes=25)
+    )
+
+    def __post_init__(self) -> None:
+        _validate_non_empty("domain", self.domain)
+        _validate_non_empty("device_name", self.device_name)
+        _validate_domain(self.domain)
+        _validate_guid("application_key", self.application_key)
+        if self.request_timeout <= 0:
+            raise ConfigurationError("request_timeout must be positive")
+        if self.max_session_age is not None and self.max_session_age.total_seconds() <= 0:
+            raise ConfigurationError("max_session_age must be positive when set")
+
+    @property
+    def base_url(self) -> str:
+        scheme = "https" if self.https else "http"
+        return f"{scheme}://{self.domain}"

SymfWebAPI/enums.py

@@ -0,0 +1,36 @@
+"""Forward-compatible enum primitives used by generated models."""
+
+from __future__ import annotations
+
+from enum import Enum
+import re
+from typing import Any
+
+_UNRECOGNIZED_NAME_SANITIZE_RE = re.compile(r"[^0-9A-Za-z_]")
+
+
+class ForwardCompatibleEnum(Enum):
+    """Enum that preserves unknown values returned by the server."""
+
+    @property
+    def is_unrecognized(self) -> bool:
+        return bool(getattr(self, "_unrecognized_", False))
+
+    @property
+    def raw_value(self) -> Any:
+        return self.value
+
+    @classmethod
+    def _missing_(cls, value: object):
+        cached = cls._value2member_map_.get(value)
+        if cached is not None:
+            return cached
+
+        pseudo_member = object.__new__(cls)
+        value_repr = str(value)
+        safe_value = _UNRECOGNIZED_NAME_SANITIZE_RE.sub("_", value_repr).strip("_") or "VALUE"
+        pseudo_member._name_ = f"UNRECOGNIZED_{safe_value}"
+        pseudo_member._value_ = value
+        pseudo_member._unrecognized_ = True
+        cls._value2member_map_[value] = pseudo_member
+        return pseudo_member

SymfWebAPI/errors.py

@@ -0,0 +1,47 @@
+"""Error hierarchy for Symfonia WebAPI client runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+class SymfoniaError(RuntimeError):
+    """Base exception for all runtime errors."""
+
+
+class ConfigurationError(SymfoniaError):
+    """Raised when client configuration is invalid."""
+
+
+class TransportError(SymfoniaError):
+    """Wrapping lower-level HTTP/IO errors."""
+
+    def __init__(self, message: str, *, endpoint: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.endpoint = endpoint
+
+
+class SessionError(SymfoniaError):
+    """Base class for session-specific issues."""
+
+
+class SessionExpiredError(SessionError):
+    """Raised when session token is no longer valid."""
+
+    def __init__(self, message: str, *, endpoint: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.endpoint = endpoint
+
+
+@dataclass(slots=True)
+class WebAPIHttpError(SymfoniaError):
+    """Raised for non-success HTTP responses."""
+
+    status_code: int
+    endpoint: str
+    response_text: str
+
+
+class SessionManagementBypassWarning(UserWarning):
+    """Warning emitted when manual session endpoints are called directly."""

SymfWebAPI/executors.py

@@ -0,0 +1,92 @@
+"""Sync/async executors implementing one shared request flow policy."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from .config import ClientConfig
+from .errors import SessionExpiredError
+from .request_engine import normalize_query_params, should_retry_auth, to_envelope_or_raise
+from .response import ResponseEnvelope
+from .session import SessionManager
+
+
+class SyncRequestExecutor:
+    def __init__(
+        self,
+        _config: ClientConfig,
+        session_manager: SessionManager,
+        request_fn: Callable[..., Any],
+    ) -> None:
+        self._session = session_manager
+        self._request = request_fn
+
+    def ensure_session(self) -> str:
+        state = self._session.ensure_sync()
+        if not state.token:
+            raise SessionExpiredError("Session not established")
+        return state.token
+
+    def invalidate_session(self) -> None:
+        self._session.invalidate()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        normalized_params = normalize_query_params(params)
+        token = self.ensure_session()
+        response = self._request(method, path, token=token, params=normalized_params, data=data)
+        if should_retry_auth(response.status_code):
+            self.invalidate_session()
+            token = self.ensure_session()
+            response = self._request(method, path, token=token, params=normalized_params, data=data)
+        return to_envelope_or_raise(response, path=path)
+
+
+class AsyncRequestExecutor:
+    def __init__(
+        self,
+        config: ClientConfig,
+        session_manager: SessionManager,
+        request_fn: Callable[..., Any],
+    ) -> None:
+        self._config = config
+        self._session = session_manager
+        self._request = request_fn
+
+    async def ensure_session(self) -> str:
+        # Fast path for hot request loops: avoid full async synchronization when
+        # a non-expired token is already present in shared session state.
+        cached_state = self._session.state
+        if cached_state.token and not cached_state.is_expired(max_age=self._config.max_session_age):
+            return cached_state.token
+
+        state = await self._session.ensure_async()
+        if not state.token:
+            raise SessionExpiredError("Session not established")
+        return state.token
+
+    def invalidate_session(self) -> None:
+        self._session.invalidate()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        normalized_params = normalize_query_params(params)
+        token = await self.ensure_session()
+        response = await self._request(method, path, token=token, params=normalized_params, data=data)
+        if should_retry_auth(response.status_code):
+            self.invalidate_session()
+            token = await self.ensure_session()
+            response = await self._request(method, path, token=token, params=normalized_params, data=data)
+        return to_envelope_or_raise(response, path=path)

SymfWebAPI/operations.py

@@ -0,0 +1,116 @@
+"""Operation descriptors and shared invocation helpers for generated controllers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import inspect
+from typing import Any, Awaitable, Callable, Optional, TypeVar, overload, cast
+
+from pydantic import TypeAdapter
+
+from .protocols import (
+    AsyncInvokerProtocol,
+    AsyncRequestProtocol,
+    SyncInvokerProtocol,
+    SyncRequestProtocol,
+)
+from .response import ResponseEnvelope
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class OperationSpec:
+    """Descriptor of one API endpoint call with response parser."""
+
+    method: str
+    path: str
+    parser: Callable[[ResponseEnvelope[Any]], ResponseEnvelope[Any]]
+
+
+def parse_with_adapter(envelope: ResponseEnvelope[Any], adapter: TypeAdapter[T]) -> ResponseEnvelope[T]:
+    if envelope.model is not None:
+        model = cast(T, envelope.model)
+    else:
+        model = adapter.validate_json(envelope.raw_text or "null")
+    return ResponseEnvelope(
+        model=model,
+        status=envelope.status,
+        headers=envelope.headers,
+        raw_text=envelope.raw_text,
+    )
+
+
+def parse_none(envelope: ResponseEnvelope[Any]) -> ResponseEnvelope[None]:
+    return ResponseEnvelope(
+        model=None,
+        status=envelope.status,
+        headers=envelope.headers,
+        raw_text=envelope.raw_text,
+    )
+
+
+@overload
+def invoke_operation(
+    api: SyncInvokerProtocol,
+    operation: OperationSpec,
+    *,
+    params: Optional[dict] = None,
+    data: Any = None,
+) -> ResponseEnvelope[Any]: ...
+
+
+@overload
+def invoke_operation(
+    api: AsyncInvokerProtocol,
+    operation: OperationSpec,
+    *,
+    params: Optional[dict] = None,
+    data: Any = None,
+) -> Awaitable[ResponseEnvelope[Any]]: ...
+
+
+@overload
+def invoke_operation(
+    api: SyncRequestProtocol,
+    operation: OperationSpec,
+    *,
+    params: Optional[dict] = None,
+    data: Any = None,
+) -> ResponseEnvelope[Any]: ...
+
+
+@overload
+def invoke_operation(
+    api: AsyncRequestProtocol,
+    operation: OperationSpec,
+    *,
+    params: Optional[dict] = None,
+    data: Any = None,
+) -> Awaitable[ResponseEnvelope[Any]]: ...
+
+
+def invoke_operation(
+    api: object,
+    operation: OperationSpec,
+    *,
+    params: Optional[dict] = None,
+    data: Any = None,
+) -> ResponseEnvelope[Any] | Awaitable[ResponseEnvelope[Any]]:
+    invoker = getattr(api, "invoke", None)
+    if callable(invoker):
+        return invoker(operation, params=params, data=data)
+
+    requester = getattr(api, "request", None)
+    if not callable(requester):
+        raise TypeError("api must expose either invoke(...) or request(...)")
+
+    result = requester(operation.method, operation.path, params=params, data=data)
+    if inspect.isawaitable(result):
+        async def _resolve() -> ResponseEnvelope[Any]:
+            envelope = await cast(Awaitable[ResponseEnvelope[Any]], result)
+            return operation.parser(envelope)
+
+        return _resolve()
+
+    return operation.parser(cast(ResponseEnvelope[Any], result))

SymfWebAPI/protocols.py

@@ -0,0 +1,85 @@
+"""Structural protocols used by generated controllers and runtime builders."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Awaitable, Optional, Protocol, TypeVar
+
+from .response import ResponseEnvelope
+from .session import SessionBackend
+
+if TYPE_CHECKING:
+    from .operations import OperationSpec
+
+T = TypeVar("T")
+
+
+class SyncRequestProtocol(Protocol):
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        ...
+
+
+class AsyncRequestProtocol(Protocol):
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[Any]:
+        ...
+
+
+class SyncInvokerProtocol(Protocol):
+    def invoke(
+        self,
+        operation: "OperationSpec[T]",
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> ResponseEnvelope[T]:
+        ...
+
+
+class AsyncInvokerProtocol(Protocol):
+    def invoke(
+        self,
+        operation: "OperationSpec[T]",
+        *,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> Awaitable[ResponseEnvelope[T]]:
+        ...
+
+
+class SyncTransportProtocol(SessionBackend, Protocol):
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        token: str,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> Any:
+        ...
+
+
+class AsyncTransportProtocol(SessionBackend, Protocol):
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        token: str,
+        params: Optional[dict] = None,
+        data: Any = None,
+    ) -> Any:
+        ...

SymfWebAPI/request_engine.py

@@ -0,0 +1,43 @@
+"""Shared request policy and response mapping for sync/async clients."""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, Optional
+
+from .errors import WebAPIHttpError
+from .response import ResponseEnvelope
+
+
+def normalize_query_value(value: Any) -> Any:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, dict):
+        return {key: normalize_query_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [normalize_query_value(item) for item in value]
+    return value
+
+
+def normalize_query_params(params: Optional[dict]) -> Optional[dict]:
+    if params is None:
+        return None
+    return {key: normalize_query_value(value) for key, value in params.items()}
+
+
+def should_retry_auth(status_code: int) -> bool:
+    return status_code == 401
+
+
+def to_envelope_or_raise(response: Any, *, path: str) -> ResponseEnvelope[Any]:
+    if 200 <= response.status_code < 300:
+        text = response.text
+        return ResponseEnvelope(
+            model=None,
+            status=response.status_code,
+            headers=dict(response.headers),
+            raw_text=text,
+        )
+    raise WebAPIHttpError(response.status_code, endpoint=path, response_text=response.text)

SymfWebAPI/response.py

@@ -0,0 +1,21 @@
+"""Response container shared by async/sync controllers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class ResponseEnvelope(Generic[T]):
+    model: Optional[T]
+    status: int
+    headers: dict
+    raw_text: Optional[str] = None
+
+    def unwrap(self) -> T:
+        if self.model is None:
+            raise ValueError("Response has no model")
+        return self.model