FHIRClient Python Library

Warnings

• breaking Python 3.8 support was dropped in `fhirclient` v4.3.0. As of v4.4.0, the minimum required Python version is 3.10. Older versions of Python will no longer work with these client versions.
  Fix: Upgrade your Python environment to 3.10 or newer, or pin `fhirclient` to an older compatible version (e.g., `<4.3.0` for Python 3.8).
• breaking In v4.2.0, the date/time model was refined. `FHIRDate` is now a base class, with new specific classes `FHIRDateTime`, `FHIRInstant`, and `FHIRTime` inheriting from it. Code that used `field_type is FHIRDate` for exact type checking will break.
  Fix: Update type checks from `field_type is FHIRDate` to `issubclass(field_type, FHIRDate)` to correctly identify all FHIR date/time types.
• gotcha Beginning with v4.3.0, `FHIRSearch.perform_resources` now automatically handles pagination behind the scenes, potentially returning more results than previously. New methods `perform_iter` and `perform_resources_iter` were added for explicit iteration over paged results.
  Fix: Review existing uses of `FHIRSearch.perform_resources` to ensure the new pagination behavior is intended. For explicit control over pagination or to avoid loading all results into memory at once, switch to `perform_iter` or `perform_resources_iter`.
• gotcha Version 4.4.0 added support for PKCE (Proof Key for Code Exchange) parameters in the authorization code exchange. While not a breaking change for existing flows, integration with FHIR servers that mandate PKCE for enhanced security might require client updates for full compliance or prevent authentication with older clients.
  Fix: Ensure your authorization flow incorporates PKCE if interacting with servers that require it. Refer to the `fhirclient` documentation or the SMART on FHIR specification for details on implementing PKCE with the library.
• gotcha The `fhirclient` library's versioning is not directly tied to the FHIR specification versioning (e.g., R4, STU3). Always consult the `fhirclient` documentation or GitHub README to understand which FHIR specification versions a particular client version supports.
  Fix: Before using `fhirclient`, verify its compatibility with your target FHIR server's specification version by checking the official client-py documentation.
• deprecated Implicit deprecation warnings for `FHIRSearch.perform` and `FHIRSearch.perform_resources` were being triggered by their `_iter` counterparts prior to v4.3.1. These warnings were unintended for the `_iter` versions.
  Fix: Upgrade to `fhirclient` v4.3.1 or newer to avoid spurious deprecation warnings when using `perform_iter` or `perform_resources_iter`.

Install

• pip install fhirclient Install latest version

Imports

• FHIRClient

  from fhirclient import client
  smart = client.FHIRClient(...)

• Patient

  from fhirclient.models.patient import Patient

• FHIRSearch

  from fhirclient.client import FHIRSearch

• FHIRDate

  from fhirclient.models.fhirdate import FHIRDate

• FHIRDateTime

  from fhirclient.models.fhirdate import FHIRDateTime

  Introduced in v4.2.0, along with FHIRInstant and FHIRTime, for more specific date/time handling. FHIRDate is now the base class.

Quickstart

This quickstart demonstrates how to initialize the `FHIRClient`, fetch a specific patient resource by ID, and perform a basic search query. It uses environment variables for configuration to ensure security and flexibility, falling back to a public SMART Health IT sandbox for demonstration. The example also shows the use of `perform_resources_iter` for handling search results, which is recommended for robust pagination.

import os
from fhirclient import client
from fhirclient.models.patient import Patient

# Configure settings for an open FHIR server
settings = {
    'app_id': os.environ.get('FHIR_APP_ID', 'my_app'),
    'api_base': os.environ.get('FHIR_API_BASE', 'https://r4.smarthealthit.org')
}

# Initialize the FHIRClient
smart = client.FHIRClient(settings=settings)

# Try to read a specific patient by ID
try:
    patient_id = os.environ.get('FHIR_PATIENT_ID', '2cda5aad-e409-4070-9a15-e1c35c46ed5a') # Example ID for smarthealthit.org sandbox
    patient = Patient.read(patient_id, smart.server)
    print(f"Successfully fetched Patient: {patient.id}")
    if patient.name:
        print(f"Patient Name: {smart.human_name(patient.name[0])}")
    if patient.birthDate:
        print(f"Birth Date: {patient.birthDate.isostring}")
except Exception as e:
    print(f"Error fetching patient: {e}")

# Example of a simple search for Patients
try:
    search = Patient.where({'gender': 'female'}).limit(2)
    # Using perform_resources_iter for robust pagination handling (introduced in v4.3.0)
    female_patients = list(search.perform_resources_iter(smart.server))
    print(f"\nFound {len(female_patients)} female patients (first 2):")
    for p in female_patients:
        print(f" - {smart.human_name(p.name[0]) if p.name else 'Unnamed'} (ID: {p.id})")
except Exception as e:
    print(f"Error during patient search: {e}")