Install & Compatibility
Where this runs
tested against v2.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsyncFHIRClient
✓ from fhirpy import AsyncFHIRClient
SyncFHIRClient
✓ from fhirpy import SyncFHIRClient
FHIRResource
✓ from fhirpy.base.resource import FHIRResource
✗ from fhirpy import FHIRResource
FHIRResource, FHIRReference, and FHIRSearchSet are part of the base module in recent versions. Direct import from fhirpy is for clients.
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.
import asyncio
import os
from fhirpy import AsyncFHIRClient, SyncFHIRClient
# Replace with your FHIR server URL
FHIR_SERVER_URL = os.environ.get('FHIR_SERVER_URL', 'http://hapi.fhir.org/baseR4')
# --- Async Client Example ---
async def async_example():
async_client = AsyncFHIRClient(FHIR_SERVER_URL, fhir_version='4.0.0')
# Create a Patient resource
patient = await async_client.resource('Patient', **{
'resourceType': 'Patient',
'gender': 'female',
'name': [{'family': 'Doe', 'given': ['Jane']}]
})
await patient.save()
print(f"Async: Created Patient with ID: {patient.id}")
# Read the Patient resource
read_patient = await async_client.resources('Patient').get(id=patient.id)
print(f"Async: Read Patient: {read_patient.serialize()['name'][0]['given'][0]} {read_patient.serialize()['name'][0]['family']}")
# Search for all Patients
patients_search = async_client.resources('Patient').search(gender='female')
all_patients = await patients_search.fetch_all()
print(f"Async: Found {len(all_patients)} female patients.")
# Delete the created Patient
await read_patient.delete()
print(f"Async: Deleted Patient with ID: {patient.id}")
# --- Sync Client Example ---
def sync_example():
sync_client = SyncFHIRClient(FHIR_SERVER_URL, fhir_version='4.0.0')
# Create a Patient resource
patient = sync_client.resource('Patient', **{
'resourceType': 'Patient',
'gender': 'male',
'name': [{'family': 'Smith', 'given': ['John']}]
})
patient.save()
print(f"Sync: Created Patient with ID: {patient.id}")
# Read the Patient resource
read_patient = sync_client.resources('Patient').get(id=patient.id)
print(f"Sync: Read Patient: {read_patient.serialize()['name'][0]['given'][0]} {read_patient.serialize()['name'][0]['family']}")
# Search for all Patients
patients_search = sync_client.resources('Patient').search(gender='male')
all_patients = patients_search.fetch_all()
print(f"Sync: Found {len(all_patients)} male patients.")
# Delete the created Patient
read_patient.delete()
print(f"Sync: Deleted Patient with ID: {patient.id}")
if __name__ == '__main__':
print("Running Async Example...")
asyncio.run(async_example())
print("\nRunning Sync Example...")
sync_example()
Debug
Known issues
gotchaAlways 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.fixInitialize client with `FHIRClient(url, fhir_version='4.0.0')`.
affects: All versions
gotchaChoose 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.fixIf your application uses `asyncio`, use `AsyncFHIRClient` and `await` its operations. For synchronous applications, use `SyncFHIRClient`.
affects: All versions
gotchaWhen 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.fixFor included resources, use `await search_set.fetch_raw()` instead of `await search_set.fetch()` or `await search_set.fetch_all()`.
affects: All versions
breakingWhile 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.fixUse `resource_instance.get_resource_type()` instead of `resource_instance.resource_type` for `fhir.resources` objects.
affects: fhir.resources >= 7.x
Errors
Common errors & fixes
ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))
This error occurs when the `fhirpy` client cannot establish a connection with the specified FHIR server, often because the server address is incorrect, the server is not running, or a firewall is blocking the connection.
fixEnsure the FHIR server URL is correct and accessible. Verify the server is running and reachable from where your `fhirpy` application is executed. You might need to check network configurations, firewalls, or proxy settings. For example, explicitly provide the full URL, including 'http://' or 'https://'.
AttributeError: 'NoneType' object has no attribute 'serialize'
This error typically arises when a `fhirpy` client operation (like `get()` or a search that expects a single result) fails to find any matching FHIR resource, causing it to return `None`, and then subsequent code attempts to call a method like `.serialize()` on this `None` object.
fixAlways check if the result of a `fhirpy` operation that might return no resources is `None` before attempting to access its attributes or methods. Implement error handling or conditional logic to handle cases where a resource is not found.
TypeError: object AsyncFHIRClient is not async-iterable
This error occurs when an `AsyncFHIRClient` instance is used in a synchronous context or when an asynchronous method is called without `await` in an `async` function, or vice-versa, attempting to treat an asynchronous object as if it were a synchronous iterable.
fixEnsure you are using the correct client type (`AsyncFHIRClient` for `asyncio` applications or `SyncFHIRClient` for synchronous applications). If using `AsyncFHIRClient`, always `await` its asynchronous operations and ensure your code is running within an `async` function.
KeyError: 'birthDate'
This `KeyError` can occur when attempting to access a field (like `birthDate`) on a `fhirpy` resource object using dictionary-style access, but the field does not exist or is not present in the underlying FHIR JSON structure of that specific resource instance. While `fhirpy` aims for `AttributeError` for missing fields, historical issues and dynamic FHIR structures can still lead to `KeyError`.
fixBefore accessing a resource attribute, especially if it might be optional or absent, use safe access patterns like `.get_by_path()` or check for its existence first. Alternatively, ensure the resource instance you are working with actually contains the expected field.
Upgrade
Version history
2.3.0latest on PyPI · released Aug 28, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.9 or newer.