baobab-altered-api 1.0.0__py3-none-any.whl

baobab_altered_api/__init__.py

@@ -0,0 +1,33 @@
+"""Point d’entrée public du package ``baobab_altered_api``.
+
+L’import de ce module ne doit pas créer de client HTTP, lire la configuration
+depuis l’environnement ni configurer le logging global. Les classes client
+exposées ici ne réalisent aucune requête tant qu’aucune méthode HTTP n’est
+appelée sur ``AlteredClient.http`` ou ``AsyncAlteredClient.http``.
+"""
+
+from __future__ import annotations
+
+from baobab_altered_api.auth import AlteredAuthFactory
+from baobab_altered_api.clients import AlteredClient, AsyncAlteredClient
+from baobab_altered_api.config import (
+    AlteredApiConfig,
+    AlteredLocale,
+    load_config_from_env,
+    to_api_client_config,
+)
+from baobab_altered_api.exceptions import AlteredConfigError
+
+__version__ = "1.0.0"
+
+__all__: tuple[str, ...] = (
+    "__version__",
+    "AlteredApiConfig",
+    "AlteredAuthFactory",
+    "AlteredClient",
+    "AlteredConfigError",
+    "AlteredLocale",
+    "AsyncAlteredClient",
+    "load_config_from_env",
+    "to_api_client_config",
+)

baobab_altered_api/auth/__init__.py

@@ -0,0 +1,5 @@
+"""Authentification Altered compatible avec le socle ``baobab-api-call``."""
+
+from baobab_altered_api.auth.altered_auth_factory import AlteredAuthFactory
+
+__all__ = ("AlteredAuthFactory",)

baobab_altered_api/auth/altered_auth_factory.py

@@ -0,0 +1,36 @@
+"""Fabrique d'authentification pour le socle ``baobab-api-call``."""
+
+from __future__ import annotations
+
+from baobab_api_call import ApiKeyAuth, AuthStrategy, BearerAuth
+
+from baobab_altered_api.config.altered_api_config import AlteredApiConfig
+
+
+class AlteredAuthFactory:
+    """Produit une stratégie ``AuthStrategy`` du socle."""
+
+    def create(self, config: AlteredApiConfig) -> AuthStrategy | None:
+        """Retourne la stratégie d'authentification ou ``None`` si aucune n'est requise.
+
+        Priorité : ``bearer_token`` puis ``api_key`` (cahier des charges).
+
+        :param config: Configuration Altered.
+        :return: ``BearerAuth``, ``ApiKeyAuth`` ou ``None``.
+        """
+        if config.bearer_token is not None:
+            return BearerAuth(token=config.bearer_token)
+        if config.api_key is not None:
+            return ApiKeyAuth(
+                api_key=config.api_key,
+                header_name=config.api_key_header_name,
+                scheme=config.api_key_query_param,
+            )
+        return None
+
+    def __repr__(self) -> str:
+        """Représentation de débogage sans données sensibles.
+
+        :return: Identifiant fixe de la fabrique (aucun secret ni état).
+        """
+        return "AlteredAuthFactory()"

baobab_altered_api/clients/__init__.py

@@ -0,0 +1,17 @@
+"""Clients publics synchrones et asynchrones.
+
+Les classes ci-dessous constituent la surface publique de ce sous-package ;
+les modules internes (validateurs, alignement de config) ne sont pas
+ré-exportés ici.
+
+Imports supportés :
+
+- ``from baobab_altered_api.clients import AlteredClient, AsyncAlteredClient``
+- ``from baobab_altered_api import AlteredClient, AsyncAlteredClient`` (re-export
+  racine, voir ``baobab_altered_api.__all__``).
+"""
+
+from baobab_altered_api.clients.altered_client import AlteredClient
+from baobab_altered_api.clients.async_altered_client import AsyncAlteredClient
+
+__all__: tuple[str, ...] = ("AlteredClient", "AsyncAlteredClient")

baobab_altered_api/clients/altered_client.py

@@ -0,0 +1,137 @@
+"""Façade synchrone publique pour les appels HTTP Altered."""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+from baobab_api_call import ApiClientConfig, SyncApiClient
+from baobab_api_call.transports.sync_transport import SyncTransport
+
+from baobab_altered_api.clients.api_client_config_alignment import (
+    ApiClientConfigAlignment,
+)
+from baobab_altered_api.clients.transport_port_validator import TransportPortValidator
+from baobab_altered_api.config.altered_api_client_config_builder import (
+    AlteredApiClientConfigBuilder,
+)
+from baobab_altered_api.config.altered_api_config import AlteredApiConfig
+from baobab_altered_api.resources.cards_resource import CardsResource
+from baobab_altered_api.resources.decks_resource import DecksResource
+from baobab_altered_api.resources.marketplace_resource import MarketplaceResource
+from baobab_altered_api.resources.open_data_resource import OpenDataResource
+from baobab_altered_api.resources.referentials_resource import ReferentialsResource
+from baobab_altered_api.transports.altered_sync_transport import AlteredSyncTransport
+
+
+class AlteredClient:
+    """Façade synchrone : assemble ``AlteredApiConfig`` et ``SyncApiClient``.
+
+    Aucune requête réseau n'est effectuée à l'instanciation.
+
+    :param config: Configuration applicative Altered (immuable) ; sert de
+        référence métier et, par défaut, de source pour ``ApiClientConfig``.
+    :param transport: Port ``SyncTransport`` avec ``send`` synchrone ; si
+        ``None``, un
+        :class:`~baobab_altered_api.transports.altered_sync_transport.AlteredSyncTransport`
+        est créé et détenu par cette façade.
+    :param api_client_config: Configuration du socle ``baobab-api-call`` ; si
+        fournie, elle remplace celle produite par ``AlteredApiClientConfigBuilder``
+        pour le client HTTP. Son ``base_url`` doit coïncider avec
+        ``config.base_url`` (normalisation par ``rstrip('/')``).
+
+    **Cycle de vie** : :meth:`close` délègue à :class:`~baobab_api_call.SyncApiClient`,
+    qui appelle ``close()`` sur le transport s'il est exposé. Un transport
+    **injecté** subit donc aussi ``close()`` : ne pas partager un transport fermé
+    entre plusieurs clients sans le recréer. Un transport **créé par défaut**
+    est fermé avec la façade.
+    """
+
+    def __init__(
+        self,
+        config: AlteredApiConfig,
+        *,
+        transport: SyncTransport | None = None,
+        api_client_config: ApiClientConfig | None = None,
+    ) -> None:
+        self._altered_config: AlteredApiConfig = config
+        if api_client_config is not None:
+            ApiClientConfigAlignment.assert_matching_base_url(config, api_client_config)
+            api_config = api_client_config
+        else:
+            api_config = AlteredApiClientConfigBuilder.build(config)
+        self._transport: SyncTransport = (
+            AlteredSyncTransport(
+                default_timeout_seconds=float(config.timeout_seconds),
+            )
+            if transport is None
+            else transport
+        )
+        TransportPortValidator.verify_sync_send(self._transport)
+        self._client: SyncApiClient = SyncApiClient(api_config, self._transport)
+        self._cards: CardsResource | None = None
+        self._decks: DecksResource | None = None
+        self._referentials: ReferentialsResource | None = None
+        self._marketplace: MarketplaceResource | None = None
+        self._open_data: OpenDataResource | None = None
+
+    @property
+    def config(self) -> AlteredApiConfig:
+        """Configuration Altered (lecture seule)."""
+        return self._altered_config
+
+    @property
+    def http(self) -> SyncApiClient:
+        """Client HTTP du socle (accès direct, en attendant les ressources métier)."""
+        return self._client
+
+    @property
+    def cards(self) -> CardsResource:
+        """Ressource cartes (lecture)."""
+        if self._cards is None:
+            self._cards = CardsResource(self._client)
+        return self._cards
+
+    @property
+    def decks(self) -> DecksResource:
+        """Ressource decks (lecture)."""
+        if self._decks is None:
+            self._decks = DecksResource(self._client)
+        return self._decks
+
+    @property
+    def referentials(self) -> ReferentialsResource:
+        """Référentiels (sets, factions, etc.)."""
+        if self._referentials is None:
+            self._referentials = ReferentialsResource(self._client)
+        return self._referentials
+
+    @property
+    def marketplace(self) -> MarketplaceResource:
+        """Marketplace lecture seule."""
+        if self._marketplace is None:
+            self._marketplace = MarketplaceResource(self._client)
+        return self._marketplace
+
+    @property
+    def open_data(self) -> OpenDataResource:
+        """Open Data : téléchargement explicite et lecture locale."""
+        if self._open_data is None:
+            self._open_data = OpenDataResource(self._altered_config, self._client)
+        return self._open_data
+
+    def close(self) -> None:
+        """Ferme le client du socle et le transport sous-jacent si applicable."""
+        self._client.close()
+
+    def __enter__(self) -> AlteredClient:
+        """Context manager synchrone : retourne ``self``."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Ferme la façade à la sortie du bloc ``with``."""
+        self.close()

baobab_altered_api/clients/api_client_config_alignment.py

@@ -0,0 +1,35 @@
+"""Alignement entre ``AlteredApiConfig`` et ``ApiClientConfig`` du socle."""
+
+from __future__ import annotations
+
+from baobab_api_call import ApiClientConfig
+
+from baobab_altered_api.config.altered_api_config import AlteredApiConfig
+from baobab_altered_api.exceptions.altered_config_error import AlteredConfigError
+
+
+class ApiClientConfigAlignment:
+    """Vérifie la cohérence minimale entre ``AlteredApiConfig`` et ``ApiClientConfig``.
+
+    Utilisé lorsque l'appelant injecte une configuration du socle via
+    ``api_client_config`` sur les façades publiques.
+    """
+
+    @staticmethod
+    def assert_matching_base_url(
+        altered: AlteredApiConfig,
+        api_cfg: ApiClientConfig,
+    ) -> None:
+        """Vérifie que les URL de base HTTP concordent après normalisation.
+
+        :param altered: Configuration applicative Altered (référence métier).
+        :param api_cfg: Configuration ``baobab-api-call`` injectée.
+        :raises AlteredConfigError: Si ``base_url`` diffère après ``rstrip('/')``.
+        """
+        left = altered.base_url.rstrip("/")
+        right = api_cfg.base_url.rstrip("/")
+        if left != right:
+            raise AlteredConfigError(
+                "api_client_config.base_url must match config.base_url "
+                f"(got {right!r} vs config {left!r})",
+            )

baobab_altered_api/clients/async_altered_client.py

@@ -0,0 +1,141 @@
+"""Façade asynchrone publique pour les appels HTTP Altered."""
+
+# pylint: disable=duplicate-code
+# Parallèle volontaire avec ``altered_client`` (FEAT-004 / BL-004-002).
+
+from __future__ import annotations
+
+from types import TracebackType
+
+from baobab_api_call import ApiClientConfig, AsyncApiClient
+from baobab_api_call.transports.async_transport import AsyncTransport
+
+from baobab_altered_api.clients.api_client_config_alignment import (
+    ApiClientConfigAlignment,
+)
+from baobab_altered_api.clients.transport_port_validator import TransportPortValidator
+from baobab_altered_api.config.altered_api_client_config_builder import (
+    AlteredApiClientConfigBuilder,
+)
+from baobab_altered_api.config.altered_api_config import AlteredApiConfig
+from baobab_altered_api.resources.async_cards_resource import AsyncCardsResource
+from baobab_altered_api.resources.async_decks_resource import AsyncDecksResource
+from baobab_altered_api.resources.async_marketplace_resource import (
+    AsyncMarketplaceResource,
+)
+from baobab_altered_api.resources.async_open_data_resource import AsyncOpenDataResource
+from baobab_altered_api.resources.async_referentials_resource import (
+    AsyncReferentialsResource,
+)
+from baobab_altered_api.transports.altered_async_transport import AlteredAsyncTransport
+
+
+class AsyncAlteredClient:
+    """Façade asynchrone : assemble ``AlteredApiConfig`` et ``AsyncApiClient``.
+
+    Aucune requête réseau n'est effectuée à l'instanciation.
+
+    :param config: Configuration applicative Altered (immuable) ; sert de
+        référence métier et, par défaut, de source pour ``ApiClientConfig``.
+    :param transport: Port ``AsyncTransport`` avec ``send`` asynchrone ; si
+        ``None``, un
+        :class:`~baobab_altered_api.transports.altered_async_transport.AlteredAsyncTransport`
+        est créé et détenu par cette façade.
+    :param api_client_config: Configuration du socle ; si fournie, elle remplace
+        celle du builder. Son ``base_url`` doit coïncider avec ``config.base_url``.
+
+    **Cycle de vie** : :meth:`aclose` délègue à :class:`~baobab_api_call.AsyncApiClient`
+    qui appelle ``aclose()`` sur le transport s'il est exposé. Un transport
+    **injecté** est fermé par cette chaîne : ne pas réutiliser un transport fermé
+    sans le recréer.
+    """
+
+    def __init__(
+        self,
+        config: AlteredApiConfig,
+        *,
+        transport: AsyncTransport | None = None,
+        api_client_config: ApiClientConfig | None = None,
+    ) -> None:
+        self._altered_config: AlteredApiConfig = config
+        if api_client_config is not None:
+            ApiClientConfigAlignment.assert_matching_base_url(config, api_client_config)
+            api_config = api_client_config
+        else:
+            api_config = AlteredApiClientConfigBuilder.build(config)
+        self._transport: AsyncTransport = (
+            AlteredAsyncTransport(
+                default_timeout_seconds=float(config.timeout_seconds),
+            )
+            if transport is None
+            else transport
+        )
+        TransportPortValidator.verify_async_send(self._transport)
+        self._client: AsyncApiClient = AsyncApiClient(api_config, self._transport)
+        self._cards: AsyncCardsResource | None = None
+        self._decks: AsyncDecksResource | None = None
+        self._referentials: AsyncReferentialsResource | None = None
+        self._marketplace: AsyncMarketplaceResource | None = None
+        self._open_data: AsyncOpenDataResource | None = None
+
+    @property
+    def config(self) -> AlteredApiConfig:
+        """Configuration Altered (lecture seule)."""
+        return self._altered_config
+
+    @property
+    def http(self) -> AsyncApiClient:
+        """Client HTTP async du socle (accès direct, en attendant les ressources)."""
+        return self._client
+
+    @property
+    def cards(self) -> AsyncCardsResource:
+        """Ressource cartes async."""
+        if self._cards is None:
+            self._cards = AsyncCardsResource(self._client)
+        return self._cards
+
+    @property
+    def decks(self) -> AsyncDecksResource:
+        """Ressource decks async."""
+        if self._decks is None:
+            self._decks = AsyncDecksResource(self._client)
+        return self._decks
+
+    @property
+    def referentials(self) -> AsyncReferentialsResource:
+        """Référentiels async."""
+        if self._referentials is None:
+            self._referentials = AsyncReferentialsResource(self._client)
+        return self._referentials
+
+    @property
+    def marketplace(self) -> AsyncMarketplaceResource:
+        """Marketplace async (lecture seule)."""
+        if self._marketplace is None:
+            self._marketplace = AsyncMarketplaceResource(self._client)
+        return self._marketplace
+
+    @property
+    def open_data(self) -> AsyncOpenDataResource:
+        """Open Data async : téléchargement explicite et lecture locale."""
+        if self._open_data is None:
+            self._open_data = AsyncOpenDataResource(self._altered_config, self._client)
+        return self._open_data
+
+    async def aclose(self) -> None:
+        """Ferme le client du socle et le transport sous-jacent si applicable."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAlteredClient:
+        """Context manager async : retourne ``self``."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Ferme la façade à la sortie du bloc ``async with``."""
+        await self.aclose()

baobab_altered_api/clients/transport_port_validator.py

@@ -0,0 +1,39 @@
+"""Vérifications runtime des ports transport pour les façades clients."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+
+class TransportPortValidator:
+    """Rejette les transports dont ``send`` ne correspond pas au mode sync/async.
+
+    Les protocoles ``SyncTransport`` / ``AsyncTransport`` du socle ne sont pas
+    vérifiables statiquement à l'exécution : ces garde-fous évitent les erreurs
+    tardives lorsqu'un fake ou un adaptateur incorrect est injecté.
+    """
+
+    @staticmethod
+    def verify_sync_send(transport: Any) -> None:
+        """Lève si ``send`` est une coroutine (transport async sur client sync)."""
+        send = getattr(transport, "send", None)
+        if send is None or not callable(send):
+            raise TypeError("transport must expose a callable send() method")
+        if inspect.iscoroutinefunction(send):
+            raise TypeError(
+                "This transport uses async send(); use AsyncAlteredClient instead "
+                "of AlteredClient."
+            )
+
+    @staticmethod
+    def verify_async_send(transport: Any) -> None:
+        """Lève si ``send`` n'est pas une coroutine (transport sync sur async)."""
+        send = getattr(transport, "send", None)
+        if send is None or not callable(send):
+            raise TypeError("transport must expose a callable send() method")
+        if not inspect.iscoroutinefunction(send):
+            raise TypeError(
+                "This transport uses synchronous send(); use AlteredClient instead "
+                "of AsyncAlteredClient."
+            )

baobab_altered_api/config/__init__.py

@@ -0,0 +1,17 @@
+"""Configuration Altered et pont vers ``baobab-api-call``."""
+
+from baobab_altered_api.config.altered_api_config import AlteredApiConfig
+from baobab_altered_api.config.altered_api_client_config_builder import (
+    AlteredApiClientConfigBuilder,
+    to_api_client_config,
+)
+from baobab_altered_api.config.altered_locale import AlteredLocale
+from baobab_altered_api.config.env_loader import load_config_from_env
+
+__all__ = (
+    "AlteredApiClientConfigBuilder",
+    "AlteredApiConfig",
+    "AlteredLocale",
+    "load_config_from_env",
+    "to_api_client_config",
+)

baobab_altered_api/config/altered_api_client_config_builder.py

@@ -0,0 +1,81 @@
+"""Conversion ``AlteredApiConfig`` vers ``ApiClientConfig`` (baobab-api-call)."""
+
+from __future__ import annotations
+
+from baobab_api_call import ApiClientConfig, RetryPolicy
+from baobab_api_call.middleware import Middleware, MiddlewareAsync
+
+from baobab_altered_api.config.altered_api_config import AlteredApiConfig
+
+
+class AlteredApiClientConfigBuilder:
+    """Construit un ``ApiClientConfig`` à partir d'un ``AlteredApiConfig``."""
+
+    @staticmethod
+    def build(config: AlteredApiConfig) -> ApiClientConfig:
+        """Produit la configuration du socle ``baobab-api-call``.
+
+        Les en-têtes par défaut incluent ``User-Agent``, ``Accept`` et
+        ``Accept-Language``. ``timeout_seconds`` et la :class:`RetryPolicy`
+        (tentatives, backoff initial, jitter) sont alignés sur le socle.
+        Si ``rate_limit_per_second`` est défini, des middlewares sync et async
+        espacent les envois côté client (pacing local ; voir
+        ``altered_rate_limit_middleware``). Les réponses ``429`` serveur restent
+        traitées par le socle et le mapping d'exceptions Altered.
+
+        :param config: Source Altered validée.
+        :return: Instance immuable du socle.
+        """
+        default_headers: dict[str, str] = {
+            "User-Agent": config.user_agent,
+            "Accept": "application/json",
+            "Accept-Language": config.locale.accept_language_value(),
+        }
+        retry_policy = RetryPolicy(
+            max_attempts=int(config.retry_max_attempts),
+            backoff_initial=float(config.retry_backoff_seconds),
+            jitter=bool(config.retry_jitter),
+        )
+        # Import local pour éviter un cycle config → auth → config.
+        # pylint: disable-next=import-outside-toplevel
+        from baobab_altered_api.auth.altered_auth_factory import (
+            AlteredAuthFactory,
+        )
+
+        # Import local : middlewares dépendent du transport, pas de l'auth.
+        # pylint: disable-next=import-outside-toplevel
+        from baobab_altered_api.transports.altered_rate_limit_middleware import (
+            AlteredRateLimitMiddleware,
+        )
+
+        # pylint: disable-next=import-outside-toplevel
+        from baobab_altered_api.transports.altered_rate_limit_middleware_async import (
+            AlteredRateLimitMiddlewareAsync,
+        )
+
+        auth_strategy = AlteredAuthFactory().create(config)
+        sync_middlewares: tuple[Middleware, ...] = ()
+        async_middlewares: tuple[MiddlewareAsync, ...] = ()
+        if config.rate_limit_per_second is not None:
+            rps = float(config.rate_limit_per_second)
+            sync_middlewares = (AlteredRateLimitMiddleware(max_per_second=rps),)
+            async_middlewares = (AlteredRateLimitMiddlewareAsync(max_per_second=rps),)
+
+        return ApiClientConfig(
+            base_url=config.base_url,
+            default_headers=default_headers,
+            timeout_seconds=float(config.timeout_seconds),
+            retry_policy=retry_policy,
+            auth_strategy=auth_strategy,
+            middlewares=sync_middlewares,
+            async_middlewares=async_middlewares,
+        )
+
+
+def to_api_client_config(config: AlteredApiConfig) -> ApiClientConfig:
+    """Convertit une configuration Altered en :class:`ApiClientConfig`.
+
+    :param config: Configuration applicative Altered.
+    :return: Configuration du client HTTP générique.
+    """
+    return AlteredApiClientConfigBuilder.build(config)