helix.fhir.client.sdk
Fluent API to call the FHIR server that handles:
- Authentication to FHIR server
- Renewing access token when they expire
- Retry when there are transient errors
- Un-bundling the resources received from FHIR server
- Paging
- Streaming
- Logging
- Simulating a $graph call when the server does not support it
Usage
pip install helix.fhir.client.sdk
Documentation
https://icanbwell.github.io/helix.fhir.client.sdk/
Test Project using this
https://github.com/icanbwell/fhir-server-performance
Python Version Support
- 1.x supports python 3.7+
- 2.x supports python 3.10+
- 3.x supports python 3.12+
Asynchronous Support
When communicating with FHIR servers, a lot of time is spent waiting for the server to respond.
This is a good use case for using asynchronous programming.
This SDK supports asynchronous programming using the async and await keywords.
The return types are Python AsyncGenerators. Python makes it very easy to work with AsyncGenerators.
For example, if the SDK provides a function like this:
async def get_resources(self) -> AsyncGenerator[FhirGetResponse, None]:
...
You can iterate over the results as they become available:
response: Optional[FhirGetResponse]
async for response in client.get_resources():
print(response.resource)
Or you can get a list of responses (which will return AFTER all the responses are received:
responses: List[FhirGetResponse] = [response async for response in client.get_resources()]
Or you can aggregate the responses into one response (which will return AFTER all the responses are received:
response: Optional[FhirGetResponse] = await FhirGetResponse.from_async_generator(client.get_resources())
Data Streaming
For FHIR servers that support data streaming (e.g., b.well FHIR server), you can just set the use_data_streaming parameter to stream the data as it is received.
The data will be streamed in AsyncGenerators as described above.
Streaming $merge Responses
use_data_streaming also applies to $merge calls (merge_async, merge_resources_async, merge_bundle_async,
merge_bundle_uncompressed). When enabled, the SDK sends Accept: application/fhir+ndjson so a b.well FHIR server
that supports it (see merge.md) can stream the
$merge response back instead of building the whole response in memory first.
from helix_fhir_client_sdk.fhir_client import FhirClient
fhir_client = FhirClient().url(fhir_server_url).resource("Patient").use_data_streaming(True)
merge_response = await FhirMergeResponse.from_async_generator(
fhir_client.merge_async(json_data_list=[json.dumps(patient_resource)])
)
This only changes how the response is read; it does not change the request body. If you also want the request
body sent with chunked transfer encoding (independent of response streaming), opt in separately with
send_data_as_chunked(True).
Error responses (e.g. a 400 with an OperationOutcome) are unaffected by streaming - the SDK always returns the
full error body via response.error/response.responses[...]["issue"], whether or not use_data_streaming is
enabled.
Persistent Sessions (Connection Reuse)
By default, the SDK creates a new HTTP session for each request. For better performance (~4× faster), you can use persistent sessions to reuse connections across multiple requests.
Important: When you provide a custom session factory using use_http_session(), YOU are responsible
for managing the session lifecycle, including closing it when done. The SDK will NOT automatically close
user-provided sessions.
import aiohttp
from helix_fhir_client_sdk.fhir_client import FhirClient
# Create a persistent session for connection reuse
session = aiohttp.ClientSession()
try:
# Configure FhirClient to use persistent session
fhir_client = (
FhirClient()
.url("https://fhir.example.com")
.resource("Patient")
.use_http_session(lambda: session) # User provides session factory
)
# Multiple requests reuse the same connection (~4× performance boost)
response1 = await fhir_client.get_async()
response2 = await fhir_client.clone().resource("Observation").get_async()
finally:
# User must close the session when done
await session.close()
Session Lifecycle Rules:
- No custom factory (default): SDK creates and closes the session automatically
- Custom factory provided: User is responsible for closing the session
Storage Compression
The FHIR client SDK supports two types of compression:
- HTTP Compression (
compress): Compresses HTTP request body when sending data to the server. Default: enabled - In-Memory Storage (
storage_mode): Controls how FHIR resources are stored in memory. Default: raw (no compression)
Disabling HTTP Compression
HTTP compression (gzip) is enabled by default for request bodies. To disable it:
from helix_fhir_client_sdk.fhir_client import FhirClient
# Disable HTTP compression for requests
fhir_client = FhirClient().url("https://fhir.example.com").compress(False)
In-Memory Storage Modes
The SDK supports different storage modes for FHIR resources through the set_storage_mode() method.
By default, resources are stored as raw Python dictionaries (no compression).
from helix_fhir_client_sdk.fhir_client import FhirClient
from compressedfhir.utilities.compressed_dict.v1.compressed_dict_storage_mode import CompressedDictStorageMode
# Use raw storage (default) - no compression, resources stored as plain Python dicts
fhir_client = FhirClient().set_storage_mode(CompressedDictStorageMode(storage_type="raw"))
# Use msgpack storage - stores resources in msgpack format
fhir_client = FhirClient().set_storage_mode(CompressedDictStorageMode(storage_type="msgpack"))
# Use compressed msgpack storage - stores resources in compressed msgpack format
fhir_client = FhirClient().set_storage_mode(CompressedDictStorageMode(storage_type="compressed_msgpack"))
Available storage types:
raw: Default. Resources are stored as standard Python dictionaries (no compression)msgpack: Resources are serialized using MessagePack for efficient storagecompressed_msgpack: Resources are serialized using MessagePack and then compressed
Getting Raw Python Dictionaries
To completely bypass the compressedfhir library and get plain Python dictionaries:
# Returns plain Python dicts, not FhirResource objects
result = await fhir_client.get_raw_resources_async()
resources = result["_resources"] # list[dict[str, Any]]
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file helix_fhir_client_sdk-5.0.9.tar.gz.
File metadata
- Download URL: helix_fhir_client_sdk-5.0.9.tar.gz
- Upload date:
- Size: 201.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
371dc8bbc4dd61d171201c1276f71fe44f585b0caf9b2a2d959e02824f61e085
|
|
| MD5 |
567447b81c22400f3ea05a85bd31cf4e
|
|
| BLAKE2b-256 |
b3ea9118a0f7f6e8097b36eb8acfe012324ea21641b5c6b35b9ba57a767f8b5d
|
File details
Details for the file helix_fhir_client_sdk-5.0.9-py3-none-any.whl.
File metadata
- Download URL: helix_fhir_client_sdk-5.0.9-py3-none-any.whl
- Upload date:
- Size: 335.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
84e109023d89dda2786b135fc9f2c0a1b9890f3cf22d3a3e46a3a5aca8ab1372
|
|
| MD5 |
259451ee08ade3c2096a7bf2f1f274c5
|
|
| BLAKE2b-256 |
be4909bd85d1487339a3938d8e6ebf0b5996d1161b8af91618a7249aa379ec63
|
