{"id":4000,"library":"fhirpy","title":"FHIR Client for Python","description":"fhirpy is an asynchronous and synchronous FHIR client for Python 3. This library provides a high-level API for performing CRUD operations and complex searches over FHIR resources. It is actively maintained by beda.software, with version 2.2.0 released on October 7, 2025, and generally follows a regular release cadence.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/beda-software/fhir-py","tags":["FHIR","healthcare","API client","async","sync"],"install":[{"cmd":"pip install fhirpy","lang":"bash","label":"Install stable version"},{"cmd":"pip install git+https://github.com/beda-software/fhir-py.git","lang":"bash","label":"Install latest development version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"Python","optional":false}],"imports":[{"symbol":"AsyncFHIRClient","correct":"from fhirpy import AsyncFHIRClient"},{"symbol":"SyncFHIRClient","correct":"from fhirpy import SyncFHIRClient"},{"note":"FHIRResource, FHIRReference, and FHIRSearchSet are part of the base module in recent versions. Direct import from fhirpy is for clients.","wrong":"from fhirpy import FHIRResource","symbol":"FHIRResource","correct":"from fhirpy.base.resource import FHIRResource"}],"quickstart":{"code":"import asyncio\nimport os\nfrom fhirpy import AsyncFHIRClient, SyncFHIRClient\n\n# Replace with your FHIR server URL\nFHIR_SERVER_URL = os.environ.get('FHIR_SERVER_URL', 'http://hapi.fhir.org/baseR4')\n\n# --- Async Client Example ---\nasync def async_example():\n    async_client = AsyncFHIRClient(FHIR_SERVER_URL, fhir_version='4.0.0')\n\n    # Create a Patient resource\n    patient = await async_client.resource('Patient', **{\n        'resourceType': 'Patient',\n        'gender': 'female',\n        'name': [{'family': 'Doe', 'given': ['Jane']}]\n    })\n    await patient.save()\n    print(f\"Async: Created Patient with ID: {patient.id}\")\n\n    # Read the Patient resource\n    read_patient = await async_client.resources('Patient').get(id=patient.id)\n    print(f\"Async: Read Patient: {read_patient.serialize()['name'][0]['given'][0]} {read_patient.serialize()['name'][0]['family']}\")\n\n    # Search for all Patients\n    patients_search = async_client.resources('Patient').search(gender='female')\n    all_patients = await patients_search.fetch_all()\n    print(f\"Async: Found {len(all_patients)} female patients.\")\n\n    # Delete the created Patient\n    await read_patient.delete()\n    print(f\"Async: Deleted Patient with ID: {patient.id}\")\n\n# --- Sync Client Example ---\ndef sync_example():\n    sync_client = SyncFHIRClient(FHIR_SERVER_URL, fhir_version='4.0.0')\n\n    # Create a Patient resource\n    patient = sync_client.resource('Patient', **{\n        'resourceType': 'Patient',\n        'gender': 'male',\n        'name': [{'family': 'Smith', 'given': ['John']}]\n    })\n    patient.save()\n    print(f\"Sync: Created Patient with ID: {patient.id}\")\n\n    # Read the Patient resource\n    read_patient = sync_client.resources('Patient').get(id=patient.id)\n    print(f\"Sync: Read Patient: {read_patient.serialize()['name'][0]['given'][0]} {read_patient.serialize()['name'][0]['family']}\")\n\n    # Search for all Patients\n    patients_search = sync_client.resources('Patient').search(gender='male')\n    all_patients = patients_search.fetch_all()\n    print(f\"Sync: Found {len(all_patients)} male patients.\")\n\n    # Delete the created Patient\n    read_patient.delete()\n    print(f\"Sync: Deleted Patient with ID: {patient.id}\")\n\nif __name__ == '__main__':\n    print(\"Running Async Example...\")\n    asyncio.run(async_example())\n    print(\"\\nRunning Sync Example...\")\n    sync_example()\n","lang":"python","description":"This quickstart demonstrates basic CRUD (Create, Read, Update, Delete) operations and a search query using both the `AsyncFHIRClient` and `SyncFHIRClient`. Remember to set the `FHIR_SERVER_URL` environment variable or replace the placeholder with your actual FHIR server endpoint."},"warnings":[{"fix":"Initialize client with `FHIRClient(url, fhir_version='4.0.0')`.","message":"Always explicitly specify the `fhir_version` when initializing `FHIRClient` (e.g., '4.0.0'). The FHIR standard evolves, and specifying the correct version ensures compatibility with your FHIR server and prevents unexpected behavior due to differing FHIR specifications.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If your application uses `asyncio`, use `AsyncFHIRClient` and `await` its operations. For synchronous applications, use `SyncFHIRClient`.","message":"Choose between `AsyncFHIRClient` and `SyncFHIRClient` based on your application's architecture. Mixing async and sync calls or using the wrong client type in an async/sync context can lead to unexpected blocking behavior or errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For included resources, use `await search_set.fetch_raw()` instead of `await search_set.fetch()` or `await search_set.fetch_all()`.","message":"When fetching resources, `fetch()` and `fetch_all()` methods do not return included resources. If you need to retrieve all included resources as well, use the `fetch_raw()` method.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `resource_instance.get_resource_type()` instead of `resource_instance.resource_type` for `fhir.resources` objects.","message":"While not directly a `fhirpy` change, the `fhir.resources` library (often used with `fhirpy` for data models) removed the `resource_type` attribute from its base FHIR class in version 7, in favor of a `get_resource_type()` method. This might affect code directly accessing `resource_type` on `fhir.resources` objects.","severity":"breaking","affected_versions":"fhir.resources >= 7.x"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}