Skip to main content

Fast-FHIR Parser: High-Performance FHIR Parser (R5)

A blazing-fast Python library for parsing and processing FHIR R5 (Fast Healthcare Interoperability Resources) data with C extensions for maximum performance. Built specifically for healthcare systems that need to process large volumes of FHIR data efficiently.

# Parse FHIR resources 100x faster than standard libraries
from fast_fhir.deserializers import deserialize_patient

patient_json = {
    "resourceType": "Patient", 
    "id": "example",
    "name": [{"family": "Doe", "given": ["John"]}],
    "gender": "male",
    "birthDate": "1980-01-01"
}

# Lightning-fast parsing with full validation
patient = deserialize_patient(patient_json)
print(f"Patient: {patient.name[0].given[0]} {patient.name[0].family}")
# Output: Patient: John Doe

🔥 FHIR Parser Capabilities

Lightning-Fast JSON Parsing

  • 10-100x faster than standard Python JSON parsers
  • C-optimized parsing engine for FHIR-specific data structures
  • Streaming parser support for large FHIR bundles and documents
  • Memory-efficient processing of healthcare datasets

Comprehensive FHIR R5 Support

  • Foundation Resources: Patient, Practitioner, PractitionerRole, Encounter, Person, RelatedPerson, Group
  • Care Provision Resources: CarePlan, CareTeam, Goal, ServiceRequest, RiskAssessment
  • Clinical Resources: Observation, Condition, Procedure, DiagnosticReport
  • Entities Resources: Organization, Location, HealthcareService
  • 24+ implemented resource types with 60+ total planned

Advanced Parsing Features

  • Intelligent Type Detection: Automatic FHIR resource type identification
  • Validation Integration: Optional Pydantic validation for data quality
  • Error Recovery: Graceful handling of malformed FHIR data
  • Batch Processing: Efficient parsing of FHIR bundles and collections
  • Extension Support: Full support for FHIR extensions and profiles

⚡ Performance

Fast-FHIR provides efficient FHIR resource deserialization with:

  • Optimized Parsing: Streamlined JSON to Python object conversion
  • Memory Efficient: Low memory overhead for large datasets
  • Pydantic Integration: Optional validation with performance optimization
  • Graceful Fallback: Pure Python implementation when C extensions unavailable

Run benchmarks to see actual performance on your system:

make benchmark
# or
PYTHONPATH=./src python3 benchmarks/benchmark_parser.py

📊 Comparative Results: See benchmarks/COMPARATIVE_RESULTS.md for detailed performance comparison against fhir.resources library.

🏥 FHIR Parser Use Cases

Healthcare System Integration

  • EHR Data Processing: Parse patient records from Epic, Cerner, AllScripts
  • HL7 FHIR API Integration: Process FHIR API responses at scale
  • Data Migration: Convert legacy healthcare data to FHIR R5 format
  • Clinical Decision Support: Real-time parsing for CDS systems

Healthcare Analytics

  • Population Health: Process large patient cohorts efficiently
  • Clinical Research: Parse clinical trial data and research datasets
  • Quality Metrics: Extract quality measures from FHIR resources
  • Interoperability Testing: Validate FHIR implementations

Production Ready

  • Healthcare Integration: Suitable for EHR data processing and FHIR API integration
  • Clinical Applications: Reliable parsing for healthcare applications
  • Data Processing: Efficient handling of FHIR bundles and collections
  • Development Friendly: Easy integration with existing Python healthcare projects

Setup

  1. Create a virtual environment:

    python -m venv venv
    
  2. Activate the virtual environment:

    source venv/bin/activate  # On macOS/Linux
    
  3. Install dependencies:

    pip install -r requirements.txt
    
  4. Build C extensions (for maximum performance):

    python setup.py build_ext --inplace
    

📦 Installation

git clone https://github.com/archit47/fast-fhir.git
cd fast-fhir
pip install -r requirements.txt
python setup.py build_ext --inplace

PyPI Installation

pip install fast-fhir

🚀 FHIR Parser Quick Start

Basic FHIR Parsing

import fast_fhir
from fast_fhir import FHIRParser
from fast_fhir.deserializers import (
    deserialize_patient,
    deserialize_practitioner,
    deserialize_encounter
)

# Initialize high-performance FHIR parser
parser = FHIRParser()

# Parse individual FHIR resources
patient = deserialize_patient(patient_json)
practitioner = deserialize_practitioner(practitioner_json)
encounter = deserialize_encounter(encounter_json)

print(f"Patient: {patient.name[0].given[0]} {patient.name[0].family}")
print(f"Practitioner: Dr. {practitioner.name[0].family}")
print(f"Encounter Status: {encounter.status}")

High-Performance Batch Parsing

from fast_fhir import FHIRParser
from fast_fhir.deserializers import FHIRFoundationDeserializer

# Initialize parser with C extensions for maximum speed
parser = FHIRParser(use_c_extensions=True)
deserializer = FHIRFoundationDeserializer()

# Parse FHIR Bundle with multiple resources
bundle_data = load_fhir_bundle("patient_bundle.json")
resources = []

for entry in bundle_data.get("entry", []):
    resource_data = entry.get("resource", {})
    resource_type = resource_data.get("resourceType")
    
    # Fast parsing with automatic type detection
    if resource_type in ["Patient", "Practitioner", "Encounter"]:
        resource = deserializer.deserialize_foundation_resource(resource_data)
        resources.append(resource)

print(f"Parsed {len(resources)} FHIR resources in milliseconds!")

Advanced FHIR Parser Features

from fast_fhir.deserializers import FHIRCareProvisionDeserializer

# Parser with validation and error handling
deserializer = FHIRCareProvisionDeserializer(
    use_pydantic_validation=True,
    strict_mode=False  # Graceful error handling
)

# Parse complex care provision resources
care_plan = deserializer.deserialize_care_plan(care_plan_json)
care_team = deserializer.deserialize_care_team(care_team_json)
goals = [deserializer.deserialize_goal(goal) for goal in goals_json]

# Access parsed FHIR data with full type safety
print(f"Care Plan: {care_plan.title}")
print(f"Care Team Size: {len(care_team.participant)}")
print(f"Patient Goals: {[goal.description.text for goal in goals]}")

Usage

Basic Usage

Show FHIR implementation status:

python main.py --status

Parse a FHIR resource from JSON file:

python main.py --parse patient.json

Show all available options:

python main.py --help

Examples and Demonstrations

The examples/ directory contains comprehensive demonstration scripts:

  • Complete System Demo: examples/demo_comprehensive.py
  • Care Provision Resources Demo: examples/demo_care_provision.py
  • JSON Deserializers Demo: examples/demo_deserializers.py
  • Implementation Testing: examples/test_implementation.py

Run examples with:

PYTHONPATH=. python3 examples/demo_comprehensive.py
PYTHONPATH=. python3 examples/demo_care_provision.py
PYTHONPATH=. python3 examples/demo_deserializers.py

FHIR Parser Architecture

The Fast-FHIR parser is built with a modular architecture for maximum flexibility:

# Foundation Resources Parser
from fast_fhir.deserializers import (
    deserialize_patient,           # Patient demographics
    deserialize_practitioner,      # Healthcare providers  
    deserialize_practitioner_role, # Provider roles & specialties
    deserialize_encounter,         # Healthcare encounters
    deserialize_person,           # Person demographics
    deserialize_related_person    # Patient relationships
)

# Care Provision Resources Parser  
from fast_fhir.deserializers import (
    deserialize_care_plan,        # Care plans & protocols
    deserialize_care_team,        # Care team coordination
    deserialize_goal,             # Patient goals & outcomes
    deserialize_service_request,  # Service requests
    deserialize_risk_assessment   # Risk assessments
)

# Clinical Resources Parser (Coming Soon)
# deserialize_observation, deserialize_condition, deserialize_procedure

FHIR Parser Performance Modes

# Maximum Performance Mode (C Extensions)
parser = FHIRParser(
    use_c_extensions=True,      # 100x faster parsing
    memory_optimization=True,   # Minimal memory usage
    batch_processing=True       # Optimized for large datasets
)

# Compatibility Mode (Pure Python)  
parser = FHIRParser(
    use_c_extensions=False,     # Pure Python fallback
    validation_mode="strict",   # Full Pydantic validation
    error_recovery=True         # Graceful error handling
)

Supported FHIR Resources

Category Resources Status
Foundation Patient, Practitioner, PractitionerRole, Encounter, Person, RelatedPerson, Group ✅ Complete
Care Provision CarePlan, CareTeam, Goal, ServiceRequest, RiskAssessment, VisionPrescription, NutritionOrder ✅ Complete
Clinical Observation, Condition, Procedure, DiagnosticReport, Medication 🚧 In Progress
Entities Organization, Location, HealthcareService, Schedule, Slot 🚧 In Progress
Financial Coverage, Claim, ExplanationOfBenefit, Invoice 📋 Planned

Total: 24+ implemented, 60+ planned for complete FHIR R5 coverage

📊 Benchmarking

Fast-FHIR includes comprehensive benchmarking tools to measure performance:

Run Benchmarks

# Quick benchmark
make benchmark

# Detailed performance analysis
PYTHONPATH=./src python3 benchmarks/performance_tests.py

# Custom benchmark with your data
from fast_fhir.benchmarks import run_performance_test
result = run_performance_test("your_fhir_data.json")
print(f"Parse time: {result.parse_time:.2f}ms")

Benchmark Categories

  • Deserializer Performance: Compare Foundation, Entities, and Care Provision deserializers
  • Validation Overhead: Measure Pydantic validation impact
  • Memory Usage: Track memory consumption patterns
  • Scaling Analysis: Performance across different dataset sizes

Current Performance Characteristics

  • Linear Scaling: Parse time scales linearly with resource count
  • Memory Efficient: Low memory overhead (< 0.01MB per resource for most cases)
  • High Success Rate: 100% parsing success for valid FHIR data
  • Consistent Performance: Reliable performance across different resource types

🔧 FHIR Parser Configuration

from fast_fhir import FHIRParser, FHIRConfig

# Custom parser configuration
config = FHIRConfig(
    # Performance settings
    use_c_extensions=True,
    enable_streaming=True,
    memory_limit="1GB",
    
    # Validation settings  
    strict_validation=False,
    validate_references=True,
    validate_codes=False,
    
    # Error handling
    error_recovery=True,
    log_parsing_errors=True,
    max_errors=100
)

parser = FHIRParser(config=config)

Development

Install development dependencies:

pip install -r requirements-dev.txt

Run FHIR parser tests:

# Run all parser tests
pytest tests/test_*_deserializers.py -v

# Run performance benchmarks
python scripts/test_c_build.py

# Test FHIR parser with real data
python examples/demo_foundation_deserializers.py

Metadata

Release files for fhir-fast-parser 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fhir-fast-parser 0.1.0
File Size Uploaded Provenance Actions
fhir_fast_parser-0.1.0.tar.gz 220.1 kB Without provenance Details for fhir_fast_parser-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fhir-fast-parser 0.1.0
File Interpreter ABI Platform Actions
fhir_fast_parser-0.1.0-cp313-cp313-macosx_15_0_arm64.whl CPython 3.13 CPython 3.13 macOS 15.0+ ARM64 Details for fhir_fast_parser-0.1.0-cp313-cp313-macosx_15_0_arm64.whl

Total release size: 476.4 kB

Release files / fhir_fast_parser-0.1.0.tar.gz

Download URL fhir_fast_parser-0.1.0.tar.gz
Size 220.1 kB
Tags Source
SHA-256 checksum
How to use checksums
c813db83c5fc554c5e7ad1b78a97d56004168c0fc0ff5a69bb0e9ddb475b658a
BLAKE2b-256 checksum
How to use checksums
256000d92655b94de54e6060f8e40be3a9f04bdd4890f0a96637ad9e066fe346
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Release files / fhir_fast_parser-0.1.0-cp313-cp313-macosx_15_0_arm64.whl

Download URL fhir_fast_parser-0.1.0-cp313-cp313-macosx_15_0_arm64.whl
Size 256.3 kB
Tags CPython 3.13 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
6e65f09124e740bd40c46143e0fa57f30d8b5246b338253212cad7ac4bb93996
BLAKE2b-256 checksum
How to use checksums
899a3a2b908f5f3b596c50d5cc791908a97040d6c4816a397a814f94296d8978
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Security for fhir-fast-parser 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page