Metadata-Version: 2.4
Name: baobab-altered-api
Version: 1.0.0
Summary: Client Python typé pour l’API publique Altered TCG, bâti sur baobab-api-call.
Author: Contributeurs baobab-altered-api
License: MIT
License-File: LICENSE
Keywords: altered,api,client,httpx,tcg
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: baobab-api-call<3.0,>=2.1.0
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: bandit<2,>=1.7; extra == 'dev'
Requires-Dist: black<26,>=24; extra == 'dev'
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: coverage[toml]<8,>=7; extra == 'dev'
Requires-Dist: flake8-pyproject<2,>=1.2; extra == 'dev'
Requires-Dist: flake8<8,>=7; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pylint<5,>=3; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
Requires-Dist: pytest-cov<6,>=4; extra == 'dev'
Requires-Dist: pytest<9,>=7; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx<9,>=7; extra == 'docs'
Description-Content-Type: text/markdown

# baobab-altered-api

Client Python **typé** et **testable** pour consommer les API publiques liées au jeu de cartes **Altered TCG**.

La librairie est conçue comme une extension métier du socle [`baobab-api-call`](https://pypi.org/project/baobab-api-call/) (`>=2.1,<3`) : elle ne réimplémente pas de pile HTTP générique.

## Statut du projet

- **Version actuelle :** `1.0.0` — première release stable du client (sync/async, cartes, référentiels, decks, marketplace lecture seule, Open Data).
- **Stabilité :** API publique de la librairie stabilisée ; les **chemins HTTP Altered** restent documentés comme hypothèses dans `docs/api_observations/` jusqu’à validation officielle.

## Statut API Altered

Les chemins d’endpoints, schémas JSON et règles d’accès **doivent être confirmés** via le portail développeur Altered et consignés dans `docs/api_observations/`.  
Ce dépôt **ne promet pas** de couverture exhaustive tant que ces observations ne sont pas validées.

## Installation (développement)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"
pytest
```

## Qualité

Les seuils et outils sont décrits dans `pyproject.toml` (pytest, coverage, black, flake8, pylint, mypy, bandit, build).

- [Guide des tests et fakes](docs/testing.md) — transports factices `tests.fakes`, garde réseau, exemples.
- [Usages minimaux des clients](docs/clients.md) — `with` / `async with`, configuration, sans promesse d’endpoints non validés.

## Transports HTTPX

- **Synchrone** : `AlteredSyncTransport` avec `SyncApiClient` du socle ; fermer via `transport.close()` (idempotent) ou `with transport:` pour un client HTTPX créé par le transport.
- **Asynchrone** : `AlteredAsyncTransport` avec `AsyncApiClient` ; fermer via `await transport.aclose()` (idempotent) ou `async with transport:` dans le même cas.
- Si vous injectez un `httpx.Client` / `httpx.AsyncClient`, la fermeture du client reste à votre charge ; le transport ne le referme pas.
- **Réponses JSON** : `AlteredTransportResponseHandler` (`json_payload_or_raise`, `raise_for_client_failure`) normalise les succès en `AlteredJsonPayload` et convertit erreurs HTTP, JSON, timeout et réseau en exceptions Altered typées, sans corps de réponse dans les messages.

## Clients publics

Guide pas à pas : **[docs/clients.md](docs/clients.md)** (sync, async, injection, rappels sur les chemins d’API).

Façades : `AlteredClient` et `AsyncAlteredClient`. Import racine recommandé pour la découverte : `from baobab_altered_api import AlteredClient, AsyncAlteredClient` ; import ciblé : `from baobab_altered_api.clients import AlteredClient, AsyncAlteredClient` (mêmes types, `__all__` du sous-package limité aux deux façades). Elles assemblent `AlteredApiConfig`, le transport HTTPX Altered et le client du socle (`http`). Aucune requête à l’instanciation ; préférez `with AlteredClient(…) as c:` / `async with AsyncAlteredClient(…) as c:` pour la fermeture.

- **Injection** : `transport=` accepte un port `SyncTransport` / `AsyncTransport` du socle. `api_client_config=` permet de remplacer la configuration `ApiClientConfig` produite par défaut (ex. en-têtes, timeouts, stratégie d’auth du socle) ; son `base_url` doit coïncider avec `AlteredApiConfig.base_url` après normalisation (`rstrip('/')`), sinon `AlteredConfigError`. Pour cloner une config du socle, préférez `ApiClientConfig.copy_with(...)` plutôt que `dataclasses.replace` (évite le conflit `timeout_seconds` / `timeouts`).
- **Sync vs async** : un transport dont `send` est une coroutine est refusé sur `AlteredClient` ; un `send` synchrone est refusé sur `AsyncAlteredClient` (`TypeError` explicite).
- **Cycle de vie** : la fermeture de la façade (`close` / `aclose`) propage au client du socle, qui ferme le transport exposé. Un transport injecté est donc fermé avec la façade : ne le partagez pas réutilisé après fermeture sans le recréer.

```python
from baobab_altered_api import AlteredApiConfig, AlteredClient

cfg = AlteredApiConfig(base_url="https://api.test.example", bearer_token="baobab-api-token")
with AlteredClient(cfg) as client:
    # Tout chemin doit être validé hors ligne (voir docs/api_observations/).
    resp = client.http.get("/chemin/relatif/exemple")
```

## Configuration et sécurité

- [Configuration](docs/configuration.md) — modèle `AlteredApiConfig`, variables `ALTERED_API_*`, exemples avec valeurs fictives.
- [Authentification](docs/authentication.md) — modes Bearer / clé API, lien avec `AlteredAuthFactory` et le socle.
- [Sécurité](docs/security.md) — gestion des secrets, représentations masquées, bonnes pratiques CI et dépôt.

## Licence

MIT — voir le fichier `LICENSE`.
