annuairesante-fhir-client

Name	annuairesante-fhir-client JSON
Version	0.2.1 JSON
	download
home_page	None
Summary	Client Python pour l'API FHIR de l'Annuaire Santé
upload_time	2025-10-08 12:33:24
maintainer	None
docs_url	None
author	Annuaire Santé FHIR Client Contributors
requires_python	>=3.9
license	MIT
keywords	fhir health annuaire-sante healthcare france
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Annuaire Santé FHIR Client

Client Python pour l'API FHIR de l'Annuaire Santé (ANS).

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()

## Caractéristiques

- ✅ Support complet des ressources FHIR de l'Annuaire Santé
- ✅ **Helper dynamique adaptatif** - s'adapte automatiquement à la structure FHIR
- ✅ **Helpers statiques** pour accès rapide aux données courantes
- ✅ **Résolution automatique des codes MOS**
- ✅ Pagination automatique via liens `next`
- ✅ Gestion d'erreurs robuste
- ✅ Types stricts avec Pydantic
- ✅ Context manager pour gestion automatique des connexions
- ✅ Tests unitaires complets

## Installation

```bash
pip install annuairesante-fhir-client
```

## Configuration

Créez un fichier `.env` à la racine du projet :

```env
ANNUAIRE_SANTE_API_KEY=votre_clé_api

# Optionnel: Configurer le répertoire de cache MOS
# Par défaut: ~/.annuairesante_cache
ANNUAIRE_SANTE_CACHE_DIR=/chemin/vers/cache

# Optionnel: Initialiser automatiquement le cache MOS au premier import
# Par défaut: false
ANNUAIRE_SANTE_AUTO_INIT_MOS=true
```

### Variables d'environnement

| Variable | Description | Défaut |
|----------|-------------|--------|
| `ANNUAIRE_SANTE_API_KEY` | Clé API pour l'Annuaire Santé (obligatoire) | - |
| `ANNUAIRE_SANTE_CACHE_DIR` | Répertoire pour le cache MOS/NOS | `~/.annuairesante_cache` |
| `ANNUAIRE_SANTE_AUTO_INIT_MOS` | Télécharger automatiquement les référentiels MOS au premier import | `false` |

**Note sur l'auto-initialisation MOS**: Lorsque `ANNUAIRE_SANTE_AUTO_INIT_MOS=true`, la librairie téléchargera automatiquement les référentiels MOS essentiels (tables TRE_R*) lors du premier import si le cache est vide. Cela peut prendre quelques minutes mais ne se fera qu'une seule fois.

## Démarrage rapide

### Avec le helper statique (extraction simple) ⭐

```python
from annuairesante_fhir import AnnuaireSanteClient
from annuairesante_fhir.helpers import wrap_practitioner

with AnnuaireSanteClient() as client:
    # Rechercher des professionnels
    result = client.practitioner.search(family="Dupont")

    # Helper statique - propriétés simplifiées
    p = wrap_practitioner(result.entries[0])

    # Accès simple aux propriétés courantes
    print(f"{p.name} (RPPS: {p.rpps})")
    print(f"Genre: {p.gender}, Actif: {p.active}")
    print(f"Email: {p.email}")
```

### Avec le helper dynamique (accès FHIR complet)

```python
from annuairesante_fhir import AnnuaireSanteClient
from annuairesante_fhir.dynamic_helper import fhir

with AnnuaireSanteClient() as client:
    result = client.practitioner.search(family="Dupont")

    # Helper dynamique - accès FHIR direct avec wrapping récursif
    p = fhir(result.entries[0], auto_resolve_mos=True)

    # Accès avec notation pointée aux structures FHIR
    print(f"Nom: {p.name[0].family} {' '.join(p.name[0].given)}")
    print(f"Genre: {p.gender}, Actif: {p.active}")
    print(f"RPPS: {p.identifier[0].value}")
```

### Pagination automatique

```python
from annuairesante_fhir import AnnuaireSanteClient
from annuairesante_fhir.helpers import wrap_practitioner

with AnnuaireSanteClient() as client:
    # Recherche simple
    result = client.practitioner.search(family="Dupont")
    for entry in result.entries:
        p = wrap_practitioner(entry)
        print(f"- {p.name} (RPPS: {p.rpps})")

    # Pagination automatique (récupère tous les résultats)
    all_results = client.practitioner.search_all(
        family="Martin",
        max_results=100
    )
    print(f"Récupéré {len(all_results)} résultats")
```

## Ressources supportées

| Ressource | Description | Recherches principales |
|-----------|-------------|------------------------|
| **Practitioner** | Professionnels de santé | family, given, identifier, active |
| **Organization** | Structures de santé | name, identifier, address_city, active |
| **PractitionerRole** | Rôles des professionnels | practitioner, organization, role, active |
| **HealthcareService** | Services de santé | name, organization, service_type |
| **Device** | Équipements médicaux | identifier, type, status |

## Quelle approche choisir ?

### Helper Statique (extraction simple) ⭐
✅ Propriétés simplifiées prêtes à l'emploi (rpps, name, email)
✅ Autocomplétion IDE complète
✅ Moins de code pour les cas courants

```python
from annuairesante_fhir.helpers import wrap_practitioner
p = wrap_practitioner(data)
print(f"{p.name}: {p.rpps}")  # Simple et direct
print(f"Email: {p.email}")
```

### Helper Dynamique (accès FHIR complet)
✅ Accès automatique à tous les champs FHIR
✅ Wrapping récursif des structures imbriquées
✅ Résolution MOS automatique intégrée
✅ Future-proof - nouveaux champs automatiquement accessibles

```python
from annuairesante_fhir.dynamic_helper import fhir
p = fhir(data, auto_resolve_mos=True)
print(p.name[0].family)  # Accès FHIR direct
print(p.gender, p.birthDate)  # Tous les champs FHIR
```

📖 [Comparaison détaillée](DYNAMIC_VS_STATIC.md)

## Documentation

📚 **Guides** :
- [QUICKSTART.md](QUICKSTART.md) - Guide de démarrage rapide
- [GUIDE_HELPERS.md](GUIDE_HELPERS.md) - Helpers statiques et résolution codes MOS
- [GUIDE_DYNAMIC_HELPER.md](GUIDE_DYNAMIC_HELPER.md) - Helper dynamique adaptatif
- [DYNAMIC_VS_STATIC.md](DYNAMIC_VS_STATIC.md) - Comparaison des deux approches
- [CHANGELOG.md](CHANGELOG.md) - Historique des versions

📁 **Exemples** :
- [examples/exemple_simple.py](examples/exemple_simple.py) - Exemple minimaliste
- [examples/basic_usage.py](examples/basic_usage.py) - Exemples de base (recherche, pagination)
- [examples/utilisation_helpers.py](examples/utilisation_helpers.py) - Helpers statiques et codes MOS
- [examples/dynamic_helper_demo.py](examples/dynamic_helper_demo.py) - Helper dynamique

🔗 **Références officielles** :
- [Documentation API ANS](https://ansforge.github.io/annuaire-sante-fhir-documentation/)
- [Guide d'implémentation FHIR](https://interop.esante.gouv.fr/ig/fhir/annuaire/)
- [Dépôt GitHub ANS](https://github.com/ansforge/annuaire-sante-fhir-documentation)

## Tests

```bash
# Lancer les tests
pytest tests/ -v

# Avec coverage
pytest tests/ --cov=annuairesante_fhir
```

## Notes importantes

⚠️ **Pagination** : L'API Annuaire Santé ne supporte pas les paramètres `_count` et `_offset`. La pagination se fait via les liens `next` dans les réponses Bundle (~50 résultats par page).

⚠️ **Format des résultats** : Les méthodes `search()` retournent des dictionnaires Python (pas des objets FHIR strictement validés) pour plus de flexibilité avec les extensions ANS.

## Licence

Ce projet est un client non-officiel pour l'API Annuaire Santé.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "annuairesante-fhir-client",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "fhir, health, annuaire-sante, healthcare, france",
    "author": "Annuaire Sant\u00e9 FHIR Client Contributors",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/0f/09/e6e0ea27ac25e187e2ef6a7ec45824bc47b84776e40d5084866eee393838/annuairesante_fhir_client-0.2.1.tar.gz",
    "platform": null,
    "description": "# Annuaire Sant\u00e9 FHIR Client\n\nClient Python pour l'API FHIR de l'Annuaire Sant\u00e9 (ANS).\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()\n\n## Caract\u00e9ristiques\n\n- \u2705 Support complet des ressources FHIR de l'Annuaire Sant\u00e9\n- \u2705 **Helper dynamique adaptatif** - s'adapte automatiquement \u00e0 la structure FHIR\n- \u2705 **Helpers statiques** pour acc\u00e8s rapide aux donn\u00e9es courantes\n- \u2705 **R\u00e9solution automatique des codes MOS**\n- \u2705 Pagination automatique via liens `next`\n- \u2705 Gestion d'erreurs robuste\n- \u2705 Types stricts avec Pydantic\n- \u2705 Context manager pour gestion automatique des connexions\n- \u2705 Tests unitaires complets\n\n## Installation\n\n```bash\npip install annuairesante-fhir-client\n```\n\n## Configuration\n\nCr\u00e9ez un fichier `.env` \u00e0 la racine du projet :\n\n```env\nANNUAIRE_SANTE_API_KEY=votre_cl\u00e9_api\n\n# Optionnel: Configurer le r\u00e9pertoire de cache MOS\n# Par d\u00e9faut: ~/.annuairesante_cache\nANNUAIRE_SANTE_CACHE_DIR=/chemin/vers/cache\n\n# Optionnel: Initialiser automatiquement le cache MOS au premier import\n# Par d\u00e9faut: false\nANNUAIRE_SANTE_AUTO_INIT_MOS=true\n```\n\n### Variables d'environnement\n\n| Variable | Description | D\u00e9faut |\n|----------|-------------|--------|\n| `ANNUAIRE_SANTE_API_KEY` | Cl\u00e9 API pour l'Annuaire Sant\u00e9 (obligatoire) | - |\n| `ANNUAIRE_SANTE_CACHE_DIR` | R\u00e9pertoire pour le cache MOS/NOS | `~/.annuairesante_cache` |\n| `ANNUAIRE_SANTE_AUTO_INIT_MOS` | T\u00e9l\u00e9charger automatiquement les r\u00e9f\u00e9rentiels MOS au premier import | `false` |\n\n**Note sur l'auto-initialisation MOS**: Lorsque `ANNUAIRE_SANTE_AUTO_INIT_MOS=true`, la librairie t\u00e9l\u00e9chargera automatiquement les r\u00e9f\u00e9rentiels MOS essentiels (tables TRE_R*) lors du premier import si le cache est vide. Cela peut prendre quelques minutes mais ne se fera qu'une seule fois.\n\n## D\u00e9marrage rapide\n\n### Avec le helper statique (extraction simple) \u2b50\n\n```python\nfrom annuairesante_fhir import AnnuaireSanteClient\nfrom annuairesante_fhir.helpers import wrap_practitioner\n\nwith AnnuaireSanteClient() as client:\n    # Rechercher des professionnels\n    result = client.practitioner.search(family=\"Dupont\")\n\n    # Helper statique - propri\u00e9t\u00e9s simplifi\u00e9es\n    p = wrap_practitioner(result.entries[0])\n\n    # Acc\u00e8s simple aux propri\u00e9t\u00e9s courantes\n    print(f\"{p.name} (RPPS: {p.rpps})\")\n    print(f\"Genre: {p.gender}, Actif: {p.active}\")\n    print(f\"Email: {p.email}\")\n```\n\n### Avec le helper dynamique (acc\u00e8s FHIR complet)\n\n```python\nfrom annuairesante_fhir import AnnuaireSanteClient\nfrom annuairesante_fhir.dynamic_helper import fhir\n\nwith AnnuaireSanteClient() as client:\n    result = client.practitioner.search(family=\"Dupont\")\n\n    # Helper dynamique - acc\u00e8s FHIR direct avec wrapping r\u00e9cursif\n    p = fhir(result.entries[0], auto_resolve_mos=True)\n\n    # Acc\u00e8s avec notation point\u00e9e aux structures FHIR\n    print(f\"Nom: {p.name[0].family} {' '.join(p.name[0].given)}\")\n    print(f\"Genre: {p.gender}, Actif: {p.active}\")\n    print(f\"RPPS: {p.identifier[0].value}\")\n```\n\n### Pagination automatique\n\n```python\nfrom annuairesante_fhir import AnnuaireSanteClient\nfrom annuairesante_fhir.helpers import wrap_practitioner\n\nwith AnnuaireSanteClient() as client:\n    # Recherche simple\n    result = client.practitioner.search(family=\"Dupont\")\n    for entry in result.entries:\n        p = wrap_practitioner(entry)\n        print(f\"- {p.name} (RPPS: {p.rpps})\")\n\n    # Pagination automatique (r\u00e9cup\u00e8re tous les r\u00e9sultats)\n    all_results = client.practitioner.search_all(\n        family=\"Martin\",\n        max_results=100\n    )\n    print(f\"R\u00e9cup\u00e9r\u00e9 {len(all_results)} r\u00e9sultats\")\n```\n\n## Ressources support\u00e9es\n\n| Ressource | Description | Recherches principales |\n|-----------|-------------|------------------------|\n| **Practitioner** | Professionnels de sant\u00e9 | family, given, identifier, active |\n| **Organization** | Structures de sant\u00e9 | name, identifier, address_city, active |\n| **PractitionerRole** | R\u00f4les des professionnels | practitioner, organization, role, active |\n| **HealthcareService** | Services de sant\u00e9 | name, organization, service_type |\n| **Device** | \u00c9quipements m\u00e9dicaux | identifier, type, status |\n\n## Quelle approche choisir ?\n\n### Helper Statique (extraction simple) \u2b50\n\u2705 Propri\u00e9t\u00e9s simplifi\u00e9es pr\u00eates \u00e0 l'emploi (rpps, name, email)\n\u2705 Autocompl\u00e9tion IDE compl\u00e8te\n\u2705 Moins de code pour les cas courants\n\n```python\nfrom annuairesante_fhir.helpers import wrap_practitioner\np = wrap_practitioner(data)\nprint(f\"{p.name}: {p.rpps}\")  # Simple et direct\nprint(f\"Email: {p.email}\")\n```\n\n### Helper Dynamique (acc\u00e8s FHIR complet)\n\u2705 Acc\u00e8s automatique \u00e0 tous les champs FHIR\n\u2705 Wrapping r\u00e9cursif des structures imbriqu\u00e9es\n\u2705 R\u00e9solution MOS automatique int\u00e9gr\u00e9e\n\u2705 Future-proof - nouveaux champs automatiquement accessibles\n\n```python\nfrom annuairesante_fhir.dynamic_helper import fhir\np = fhir(data, auto_resolve_mos=True)\nprint(p.name[0].family)  # Acc\u00e8s FHIR direct\nprint(p.gender, p.birthDate)  # Tous les champs FHIR\n```\n\n\ud83d\udcd6 [Comparaison d\u00e9taill\u00e9e](DYNAMIC_VS_STATIC.md)\n\n## Documentation\n\n\ud83d\udcda **Guides** :\n- [QUICKSTART.md](QUICKSTART.md) - Guide de d\u00e9marrage rapide\n- [GUIDE_HELPERS.md](GUIDE_HELPERS.md) - Helpers statiques et r\u00e9solution codes MOS\n- [GUIDE_DYNAMIC_HELPER.md](GUIDE_DYNAMIC_HELPER.md) - Helper dynamique adaptatif\n- [DYNAMIC_VS_STATIC.md](DYNAMIC_VS_STATIC.md) - Comparaison des deux approches\n- [CHANGELOG.md](CHANGELOG.md) - Historique des versions\n\n\ud83d\udcc1 **Exemples** :\n- [examples/exemple_simple.py](examples/exemple_simple.py) - Exemple minimaliste\n- [examples/basic_usage.py](examples/basic_usage.py) - Exemples de base (recherche, pagination)\n- [examples/utilisation_helpers.py](examples/utilisation_helpers.py) - Helpers statiques et codes MOS\n- [examples/dynamic_helper_demo.py](examples/dynamic_helper_demo.py) - Helper dynamique\n\n\ud83d\udd17 **R\u00e9f\u00e9rences officielles** :\n- [Documentation API ANS](https://ansforge.github.io/annuaire-sante-fhir-documentation/)\n- [Guide d'impl\u00e9mentation FHIR](https://interop.esante.gouv.fr/ig/fhir/annuaire/)\n- [D\u00e9p\u00f4t GitHub ANS](https://github.com/ansforge/annuaire-sante-fhir-documentation)\n\n## Tests\n\n```bash\n# Lancer les tests\npytest tests/ -v\n\n# Avec coverage\npytest tests/ --cov=annuairesante_fhir\n```\n\n## Notes importantes\n\n\u26a0\ufe0f **Pagination** : L'API Annuaire Sant\u00e9 ne supporte pas les param\u00e8tres `_count` et `_offset`. La pagination se fait via les liens `next` dans les r\u00e9ponses Bundle (~50 r\u00e9sultats par page).\n\n\u26a0\ufe0f **Format des r\u00e9sultats** : Les m\u00e9thodes `search()` retournent des dictionnaires Python (pas des objets FHIR strictement valid\u00e9s) pour plus de flexibilit\u00e9 avec les extensions ANS.\n\n## Licence\n\nCe projet est un client non-officiel pour l'API Annuaire Sant\u00e9.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Client Python pour l'API FHIR de l'Annuaire Sant\u00e9",
    "version": "0.2.1",
    "project_urls": {
        "Bug Tracker": "https://github.com/orochvilato/annuairesante-fhir-client/issues",
        "Documentation": "https://github.com/orochvilato/annuairesante-fhir-client#readme",
        "Homepage": "https://github.com/orochvilato/annuairesante-fhir-client",
        "Repository": "https://github.com/orochvilato/annuairesante-fhir-client"
    },
    "split_keywords": [
        "fhir",
        " health",
        " annuaire-sante",
        " healthcare",
        " france"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a901ab6c66ddc38e68ecc2a3498321076c00105fe049a8ee0660a40126f009dc",
                "md5": "5e36b7835290fb0cca3be9f023ebcd37",
                "sha256": "5cb4512aac0dc035c7a26b300ca98be6c6273865e39f6fa67f8796dca440e282"
            },
            "downloads": -1,
            "filename": "annuairesante_fhir_client-0.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5e36b7835290fb0cca3be9f023ebcd37",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 37500,
            "upload_time": "2025-10-08T12:33:23",
            "upload_time_iso_8601": "2025-10-08T12:33:23.482504Z",
            "url": "https://files.pythonhosted.org/packages/a9/01/ab6c66ddc38e68ecc2a3498321076c00105fe049a8ee0660a40126f009dc/annuairesante_fhir_client-0.2.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "0f09e6e0ea27ac25e187e2ef6a7ec45824bc47b84776e40d5084866eee393838",
                "md5": "5df2a0ab9f2613658625d79c3b3e5205",
                "sha256": "359b10525a174f57c5f90166577d459224136e53ab7bf8ff9bba69324ba5a997"
            },
            "downloads": -1,
            "filename": "annuairesante_fhir_client-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "5df2a0ab9f2613658625d79c3b3e5205",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 37218,
            "upload_time": "2025-10-08T12:33:24",
            "upload_time_iso_8601": "2025-10-08T12:33:24.700678Z",
            "url": "https://files.pythonhosted.org/packages/0f/09/e6e0ea27ac25e187e2ef6a7ec45824bc47b84776e40d5084866eee393838/annuairesante_fhir_client-0.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-08 12:33:24",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "orochvilato",
    "github_project": "annuairesante-fhir-client",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "annuairesante-fhir-client"
}