{"id":27431057,"url":"https://github.com/migraf/fhir-kindling","last_synced_at":"2025-08-23T17:35:08.554Z","repository":{"id":36961977,"uuid":"399513008","full_name":"migraf/fhir-kindling","owner":"migraf","description":"HL7 FHIR client library. Sync and async crud operations against R4 FHIR servers. Resource validation \u0026 serialization","archived":false,"fork":false,"pushed_at":"2024-04-15T06:14:26.000Z","size":7880,"stargazers_count":20,"open_issues_count":18,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-23T02:46:29.916Z","etag":null,"topics":["data-science","fhir","fhir-client","hl7","medical","medical-data","pydantic","python"],"latest_commit_sha":null,"homepage":"https://migraf.github.io/fhir-kindling/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/migraf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-08-24T15:17:35.000Z","updated_at":"2025-08-10T10:13:01.000Z","dependencies_parsed_at":"2025-04-16T01:32:56.799Z","dependency_job_id":null,"html_url":"https://github.com/migraf/fhir-kindling","commit_stats":{"total_commits":414,"total_committers":5,"mean_commits":82.8,"dds":"0.16425120772946855","last_synced_commit":"d48540d1eee9a802338d395205ccd56ea0fc2c2e"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/migraf/fhir-kindling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migraf%2Ffhir-kindling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migraf%2Ffhir-kindling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migraf%2Ffhir-kindling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migraf%2Ffhir-kindling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/migraf","download_url":"https://codeload.github.com/migraf/fhir-kindling/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/migraf%2Ffhir-kindling/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271746275,"owners_count":24813553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","fhir","fhir-client","hl7","medical","medical-data","pydantic","python"],"created_at":"2025-04-14T15:28:27.288Z","updated_at":"2025-08-23T17:35:08.518Z","avatar_url":"https://github.com/migraf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Header](./docs/logo/kindling_header.png)\n\n[![CI](https://github.com/migraf/fhir-kindling/actions/workflows/main_ci.yml/badge.svg?branch=main)](https://github.com/migraf/fhir-kindling/actions/workflows/main_ci.yml)\n[![codecov](https://codecov.io/gh/migraf/fhir-kindling/branch/main/graph/badge.svg?token=FKQENFXACB)](https://codecov.io/gh/migraf/fhir-kindling)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Maintainability](https://api.codeclimate.com/v1/badges/3b83aa52724b6e75fc22/maintainability)](https://codeclimate.com/github/migraf/fhir-kindling/maintainability)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/fhir_kindling)\n![PyPI](https://img.shields.io/pypi/v/fhir_kindling)\n\n\n\nPython library for interacting with [HL7 FHIR](http://hl7.org/fhir/) servers and resources. Resource validation and parsing powered by\n[pydantic](https://github.com/samuelcolvin/pydantic) and the [fhir.resources](https://github.com/nazrulworld/fhir.resources) library.\nProvides a simple interface for synchronous and asynchronous CRUD operations for resources and bundles, \nas well as resource transfer between servers.\nDatascience features include flattening of resources and bundles into tabular format (pandas dataframes) and plotting \nmethods for resources and bundles can optionally be included with the `ds` extra.\n\nCheck out the [documentation](https://migraf.github.io/fhir-kindling/) for more information and a detailed user guide.\n\n\nTable of Contents\n=================\n\n- [Table of Contents](#table-of-contents)\n  - [Features](#features)\n  - [Installation](#installation)\n    - [Extras (optional)](#extras-optional)\n  - [Usage](#usage)\n    - [Connecting to a FHIR server](#connecting-to-a-fhir-server)\n    - [Query resources from the server](#query-resources-from-the-server)\n      - [Basic resource query](#basic-resource-query)\n      - [Query with filters](#query-with-filters)\n      - [Including related resources in the query](#including-related-resources-in-the-query)\n      - [Query resources by reference](#query-resources-by-reference)\n    - [Add resources to the server](#add-resources-to-the-server)\n    - [Deleting/Updating resources](#deletingupdating-resources)\n    - [Transfer resources between servers](#transfer-resources-between-servers)\n  - [Performance](#performance)\n  - [Contributing](#contributing)\n    - [Development](#development)\n    - [Tests](#tests)\n  - [Credits](#credits)\n\n## Features\n\n- Create, Read, Update, Delete resources using a FHIR server's REST API\n- Transfer resources between servers while maintaining referential integrity using server-given IDs\n- Bundle creation, validation and data management on a FHIR server via the REST API\n- Supports Hapi, Blaze and IBM FHIR servers\n- CSV serialization of query results\n- Synthetic data generation and\n\n\n\n\u003c!-- Created by https://github.com/ekalinin/github-markdown-toc --\u003e\n\n\n## Installation\n\nInstall the package using pip:\n\n```shell\npip install fhir-kindling --user\n```\n\n### Extras (optional)\nFhir kindling can be used with the following extras:\n- `ds` for data science related features, such as flattening of resources into a tabular format\n\n```\npip install fhir-kindling[ds] --user\n```\n\n## Usage\n\n### Connecting to a FHIR server\n\n```python\nfrom fhir_kindling import FhirServer\n\n# Connect with basic auth \nbasic_auth_server = FhirServer(\"https://fhir.server/fhir\", username=\"admin\", password=\"admin\")\n# Connect with static token\ntoken_server = FhirServer(\"https://fhir.server/fhir\", token=\"your_token\")\n\n# Connect using oauth2/oidc\noidc_server = FhirServer(\"https://fhir.server/fhir\", client_id=\"client_id\", client_secret=\"secret\",\n                         oidc_provider_url=\"url\")\n\n# Print the server's capability statement\nprint(basic_auth_server.capabilities)\n\n```\n\n### Query resources from the server\n\n#### Basic resource query\n\n```python\nfrom fhir_kindling import FhirServer\nfrom fhir.resources.patient import Patient\n\n# Connect using oauth2/oidc\noidc_server = FhirServer(\"https://fhir.server/fhir\", client_id=\"client_id\", client_secret=\"secret\",\n                         oidc_provider_url=\"url\")\n\n# query all patients on the server\nquery = oidc_server.query(Patient, output_format=\"json\").all()\nprint(query.response)\n\n# Query resources based on name of resource\nquery = oidc_server.query(\"Patient\", output_format=\"json\").all()\nprint(query.response)\n```\n\n#### Query with filters\n\nFiltering the targeted resource is done using the `where` method on the query object. The filter is created by defining\nthe target field, the comparison operator and the value to compare.\n\n```python\nfrom fhir_kindling import FhirServer\n\nserver = FhirServer(api_address=\"https://fhir.server/fhir\")\n\nquery = server.query(\"Patient\").where(field=\"birthDate\", operator=\"gt\", value=\"1980\").all()\n```\n\n#### Including related resources in the query\n\nResources that reference or are referenced by resources targeted by the query can be included in the response using\nthe `include` method on the query object.\n\n```python\n# server initialization omitted\n# get the patients along with the queried conditions\nquery_patient_condition = server.query(\"Condition\").include(resource=\"Condition\", reference_param=\"subject\").all()\n\n# get the conditions for a patient\nquery_patient_condition = server.query(\"Patient\")\nquery_patient_condition = query_patient_condition.include(resource=\"Condition\", reference_param=\"subject\", reverse=True)\nresponse = query_patient_condition.all()\n```\n\n#### Query resources by reference\n\nIf you know the id and resource type of the resource you want to query, you can use the `get` method for a single\nreference\nfor a list of references use `get_many`. The passed references should follow the format of `\u003cresource_type\u003e/\u003cid\u003e`.\n\n```python\n# server initialization omitted\npatient = server.get(\"Patient/123\")\n\npatients = server.get_many([\"Patient/123\", \"Patient/456\"])\n\n```\n\n### Add resources to the server\n\nResources can be added to the server using the `add` method on the server object. Lists of resources can be added using\n'add_all'.\n\n```python\nfrom fhir_kindling import FhirServer\nfrom fhir.resources.patient import Patient\n\n# Connect to the server\nserver = FhirServer(api_address=\"https://fhir.server/fhir\")\n\n# add a single resource\npatient = Patient(name=[{\"family\": \"Smith\", \"given\": [\"John\"]}])\nresponse = server.add(patient)\n\n# add multiple resources\npatients = [Patient(name=[{\"family\": f\"Smith_{i}\", \"given\": [\"John\"]}]) for i in range(10)]\nresponse = server.add_all(patients)\n```\n\n### Deleting/Updating resources\n\nResources can be deleted from the server using the `delete` method on the server object, it takes as input either\nreferences to the resources or the resources itself.  \nSimilarly the `update` method can be used to update the resources on the server, by passing a list of updated resources.\n\n```python\nfrom fhir_kindling import FhirServer\nfrom fhir.resources.patient import Patient\n\n# Connect to the server\nserver = FhirServer(api_address=\"https://fhir.server/fhir\")\n\n# add some patients\npatients = [Patient(name=[{\"family\": f\"Smith_{i}\", \"given\": [\"John\"]}]) for i in range(10)]\nresponse = server.add_all(patients)\n\n# change the name of the patients\nfor patient in response.resources:\n    patient.name[0].given[0] = \"Jane\"\n\n# update the patients on the server\nupdated_patients = server.update(resources=response.resources)\n\n# delete based on reference\nserver.delete(references=response.references[:5])\n# delete based on resources\nserver.delete(resources=response.resources[5:])\n```\n\n### Transfer resources between servers\n\nTransferring resources between servers is done using the `transfer` method on the server object. Using this method\nserver assigned ids are used for transfer and referential integrity is maintained.  \nThis method will also attempt to get all the resources that are referenced by the resources being transferred from the\norigin\nserver and transfer them to the destination server as well.\n\n```python\nfrom fhir_kindling import FhirServer\n\n# initialize the two servers\nserver_1 = FhirServer(api_address=\"https://fhir.server/fhir\")\nserver_2 = FhirServer(api_address=\"https://fhir.server/fhir\")\n\n# query some resources from server 1\nconditions = server_1.query(\"Condition\").limit(10)\n# transfer the resources to server 2\nresponse = server_1.transfer(server_2, resources=conditions.resources)\n\n```\n\n## Performance\n\nThis library performs request at least 1.5 times faster than other popular python FHIR libraries.\nSee [Benchmarks](benchmarks/README.md) for a more detailed description of the benchmarks.\n![Query Results](benchmarks/results/query_plot.png)\n\n\n## Contributing\nContributions are very welcome and greatly appreciated! If you want to contribute to this project, please fork the \nrepository and make changes as you'd like. Pull requests are warmly welcome and credit will always be given.\n\n### Development\n\nTo set up your environment to develop this package make sure you have [poetry](https://python-poetry.org/) installed and\nrun the following commands:\n\nInstall the dependencies:\n```bash\npoetry install --with dev --all-extras\n```\n\nInstall pre-commit hooks:\n\n- Linting: [ruff](https://github.com/charliermarsh/ruff)\n- Formatting [black](https://black.readthedocs.io/en/stable/)\n\n```bash\npoetry run pre-commit install\n```\n\n### Tests\nTo run the full test suit you need access to two FHIR servers (the second one is used for transfer tests).\nYou can spin up two servers (one HAPI and one Blaze FHIR) using the compose file in the `testing` directory.\n```bash\ncd testing\ndocker compose up\n```\nThe servers will be available at `http://localhost:9090/fhir` and `http://localhost:9091/fhir` respectively.\nAnd the test should be configured to use them via the environment variables `FHIR_API_URL` and `TRANSFER_SERVER_URL` respectively.\n\nRun the tests:\n```bash\npoetry run pytest\n```\n\n\n## Credits\n\nThis package was created with Cookiecutter and\nthe [audreyr/cookiecutter-pypackage](https://github.com/audreyr/cookiecutter) project template.\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigraf%2Ffhir-kindling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmigraf%2Ffhir-kindling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmigraf%2Ffhir-kindling/lists"}