API Reference

to_fhir

Collection of utils for writing FHIR mappings.

class DataAbsentReason(*values)[source]

Bases: StrEnum

Codes from the data-absent-reason code system.

See CodeSystem: DataAbsentReason. Members are their own FHIR code, so DataAbsentReason.NOT_ASKED == "not-asked".

UNKNOWN = 'unknown'

The value is expected to exist but is not known.

ASKED_UNKNOWN = 'asked-unknown'

The source was asked but does not know the value.

TEMP_UNKNOWN = 'temp-unknown'

There is reason to expect (from the workflow) that the value may become known.

NOT_ASKED = 'not-asked'

The workflow didn’t lead to this value being known.

ASKED_DECLINED = 'asked-declined'

The source was asked but declined to answer.

MASKED = 'masked'

The information is not available due to security, privacy or related reasons.

NOT_APPLICABLE = 'not-applicable'

There is no proper value for this element (e.g. last menstrual period for a male).

UNSUPPORTED = 'unsupported'

The source system wasn’t capable of supporting this element.

AS_TEXT = 'as-text'

The content of the data is represented in the resource narrative.

ERROR = 'error'

Some system or workflow process error means that the information is not available.

NOT_A_NUMBER = 'not-a-number'

The numeric value is undefined or unrepresentable due to a floating point error.

NEGATIVE_INFINITY = 'negative-infinity'

The numeric value is excessively low and unrepresentable due to a floating point error.

POSITIVE_INFINITY = 'positive-infinity'

The numeric value is excessively high and unrepresentable due to a floating point error.

NOT_PERFORMED = 'not-performed'

The value is not available because the observation procedure was not performed.

NOT_PERMITTED = 'not-permitted'

The value is not permitted in this context (e.g. due to profiles, or the base data types).

property code: str

The FHIR code for this concept, e.g. not-asked.

coding() → Coding[source]

Return a fresh Coding for this concept.

extension() → Extension[source]

Return a fresh data-absent-reason extension carrying this concept.

class DataAndProvenanceBundles(data_bundle: Bundle, provenance_bundle: Bundle)[source]

Bases: NamedTuple

A pair of FHIR bundles: one holding data resources, one holding provenance resources.

data_bundle: Bundle

The bundle containing data resources (e.g. Patient, Observation).

provenance_bundle: Bundle

The bundle containing Provenance and optionally Device resources.

class TransactionBuilder[source]

Bases: object

Builder for FHIR transaction bundles, using the update-as-create approach by default.

with_type(bundle_type: str) → Self[source]

Set the bundle type, e.g. "transaction" or "batch".

fail_on_duplicate_entries() → Self[source]

Raise when multiple resources with the same id are added, once the bundle is built.

add_entry(resource: Resource) → Self[source]

Add a FHIR resource to the transaction bundle.

add_entries(*resources: Resource) → Self[source]

Add FHIR resources to the transaction bundle.

add_delete_entry(resource: Reference) → Self[source]

Add a reference to a resource that should be deleted as part of the transaction.

add_delete_entries(*resources: Reference) → Self[source]

Add references to resources that should be deleted as part of the transaction.

with_id(bundle_id: str) → Self[source]

Set the id of the bundle.

with_full_url_base(base_url: str) → Self[source]

Set an absolute base URL used to build each entry’s fullUrl.

Each entry’s fullUrl becomes <base_url>/<ResourceType>/<id>, making it absolute as FHIR requires. Plain ResourceType/id references used elsewhere in the bundle (e.g. in a Provenance.target) still resolve correctly against it, since those match by the tail of a hierarchical fullUrl. The base URL does not need to be a real, dereferenceable server endpoint.

Parameters:

base_url – An absolute base URL, e.g. https://example.org/fhir. A trailing slash is optional.

with_provenance(who: Reference | Device, what: Reference) → Self[source]

Include a Provenance resource in the bundle.

If the bundle contains both delete and update/create entries, two Provenance resources are included. The Provenance.id is derived from the hash of who and what.

Parameters:

  • who – The agent responsible for the transformation or deletion, as Provenance .agent.who. This is typically the transformation service itself. Passing a Device adds that resource to the bundle and references it instead.

  • what – A reference to the resource that is the source of the transformation, as Provenance.entity.what.

build() → Bundle[source]

Build a FHIR Bundle with the configured type.

Raises:

ValueError – fail_on_duplicate_entries() is enabled and duplicate resource ids were found.

build_with_separate_provenance() → DataAndProvenanceBundles[source]

Build the data resources and the provenance resources as two separate bundles.

The data bundle holds only the data resources and delete entries; the provenance bundle holds the Provenance resource(s) and, if configured via with_provenance(), the Device. The provenance bundle is always of type transaction.

Raises:
create_reference_to(resource: Resource) → Reference[source]

Create a reference to resource, in the form ResourceType/id.

Parameters:

resource – The FHIR resource to create a reference to. It must have a non-blank id.

Raises:

ValueError – The resource has no id, or a blank one.

create_reference_to_identifier(identifier: Identifier, resource_type: str, *, algorithm: str = 'sha256') → Reference[source]

Create a reference to the resource identified by identifier.

The reference is of the form <resource_type>/sha256(system|value).

Parameters:

  • identifier – An identifier of the FHIR resource to create a reference to.

  • resource_type – The resource type to include in the reference.

  • algorithm – The hashlib algorithm to hash with.

Raises:

ValueError – The identifier’s system or value is missing or blank.

data_absent_reason(reason: DataAbsentReason | None = None) → Extension[source]

Return a fresh data-absent-reason extension.

Parameters:

reason – The reason the value is absent. When omitted, the returned extension is a bare template without a value.

to_fhir.transaction_builder

Builder for creating FHIR transaction bundles.

class DataAndProvenanceBundles(data_bundle: Bundle, provenance_bundle: Bundle)[source]

Bases: NamedTuple

A pair of FHIR bundles: one holding data resources, one holding provenance resources.

data_bundle: Bundle

The bundle containing data resources (e.g. Patient, Observation).

provenance_bundle: Bundle

The bundle containing Provenance and optionally Device resources.

class TransactionBuilder[source]

Bases: object

Builder for FHIR transaction bundles, using the update-as-create approach by default.

with_type(bundle_type: str) → Self[source]

Set the bundle type, e.g. "transaction" or "batch".

fail_on_duplicate_entries() → Self[source]

Raise when multiple resources with the same id are added, once the bundle is built.

add_entry(resource: Resource) → Self[source]

Add a FHIR resource to the transaction bundle.

add_entries(*resources: Resource) → Self[source]

Add FHIR resources to the transaction bundle.

add_delete_entry(resource: Reference) → Self[source]

Add a reference to a resource that should be deleted as part of the transaction.

add_delete_entries(*resources: Reference) → Self[source]

Add references to resources that should be deleted as part of the transaction.

with_id(bundle_id: str) → Self[source]

Set the id of the bundle.

with_full_url_base(base_url: str) → Self[source]

Set an absolute base URL used to build each entry’s fullUrl.

Each entry’s fullUrl becomes <base_url>/<ResourceType>/<id>, making it absolute as FHIR requires. Plain ResourceType/id references used elsewhere in the bundle (e.g. in a Provenance.target) still resolve correctly against it, since those match by the tail of a hierarchical fullUrl. The base URL does not need to be a real, dereferenceable server endpoint.

Parameters:

base_url – An absolute base URL, e.g. https://example.org/fhir. A trailing slash is optional.

with_provenance(who: Reference | Device, what: Reference) → Self[source]

Include a Provenance resource in the bundle.

If the bundle contains both delete and update/create entries, two Provenance resources are included. The Provenance.id is derived from the hash of who and what.

Parameters:

  • who – The agent responsible for the transformation or deletion, as Provenance .agent.who. This is typically the transformation service itself. Passing a Device adds that resource to the bundle and references it instead.

  • what – A reference to the resource that is the source of the transformation, as Provenance.entity.what.

build() → Bundle[source]

Build a FHIR Bundle with the configured type.

Raises:

ValueError – fail_on_duplicate_entries() is enabled and duplicate resource ids were found.

build_with_separate_provenance() → DataAndProvenanceBundles[source]

Build the data resources and the provenance resources as two separate bundles.

The data bundle holds only the data resources and delete entries; the provenance bundle holds the Provenance resource(s) and, if configured via with_provenance(), the Device. The provenance bundle is always of type transaction.

Raises:

to_fhir.fhir_codings

Factory functions for default Coding templates used across to-FHIR®.

Each function returns a fresh instance, since Coding is mutable.

loinc() → Coding[source]

Return a fresh LOINC coding template.

snomed() → Coding[source]

Return a fresh SNOMED CT coding template.

ops() → Coding[source]

Return a fresh OPS coding template.

atc() → Coding[source]

Return a fresh ATC coding template.

icd10gm() → Coding[source]

Return a fresh ICD-10-GM coding template.

pzn() → Coding[source]

Return a fresh PZN coding template.

to_fhir.fhir_extensions

Factory functions for default Extension templates used across to-FHIR®.

DATA_ABSENT_REASON_URL = 'http://hl7.org/fhir/StructureDefinition/data-absent-reason'

The data-absent-reason extension URL.

DATA_ABSENT_REASON_CODE_SYSTEM = 'http://terminology.hl7.org/CodeSystem/data-absent-reason'

The code system backing DataAbsentReason.

class DataAbsentReason(*values)[source]

Bases: StrEnum

Codes from the data-absent-reason code system.

See CodeSystem: DataAbsentReason. Members are their own FHIR code, so DataAbsentReason.NOT_ASKED == "not-asked".

UNKNOWN = 'unknown'

The value is expected to exist but is not known.

ASKED_UNKNOWN = 'asked-unknown'

The source was asked but does not know the value.

TEMP_UNKNOWN = 'temp-unknown'

There is reason to expect (from the workflow) that the value may become known.

NOT_ASKED = 'not-asked'

The workflow didn’t lead to this value being known.

ASKED_DECLINED = 'asked-declined'

The source was asked but declined to answer.

MASKED = 'masked'

The information is not available due to security, privacy or related reasons.

NOT_APPLICABLE = 'not-applicable'

There is no proper value for this element (e.g. last menstrual period for a male).

UNSUPPORTED = 'unsupported'

The source system wasn’t capable of supporting this element.

AS_TEXT = 'as-text'

The content of the data is represented in the resource narrative.

ERROR = 'error'

Some system or workflow process error means that the information is not available.

NOT_A_NUMBER = 'not-a-number'

The numeric value is undefined or unrepresentable due to a floating point error.

NEGATIVE_INFINITY = 'negative-infinity'

The numeric value is excessively low and unrepresentable due to a floating point error.

POSITIVE_INFINITY = 'positive-infinity'

The numeric value is excessively high and unrepresentable due to a floating point error.

NOT_PERFORMED = 'not-performed'

The value is not available because the observation procedure was not performed.

NOT_PERMITTED = 'not-permitted'

The value is not permitted in this context (e.g. due to profiles, or the base data types).

property code: str

The FHIR code for this concept, e.g. not-asked.

coding() → Coding[source]

Return a fresh Coding for this concept.

extension() → Extension[source]

Return a fresh data-absent-reason extension carrying this concept.

data_absent_reason(reason: DataAbsentReason | None = None) → Extension[source]

Return a fresh data-absent-reason extension.

Parameters:

reason – The reason the value is absent. When omitted, the returned extension is a bare template without a value.

to_fhir.fhir_systems

Canonical FHIR coding system URIs used across to-FHIR®.

UCUM = 'http://unitsofmeasure.org'

The UCUM system.

LOINC = 'http://loinc.org'

The LOINC system.

SNOMED = 'http://snomed.info/sct'

The SNOMED CT system.

ATC = 'http://fhir.de/CodeSystem/bfarm/atc'

The ATC system.

OPS = 'http://fhir.de/CodeSystem/bfarm/ops'

The OPS system.

ICD10GM = 'http://fhir.de/CodeSystem/bfarm/icd-10-gm'

The ICD-10-GM system.

PZN = 'http://fhir.de/CodeSystem/ifa/pzn'

The PZN system.

to_fhir.id_utils

Utilities for deterministic FHIR resource ids.

DEFAULT_ALGORITHM = 'sha256'

The hash algorithm used unless a different hashlib algorithm is requested.

from_identifier(identifier: Identifier, resource_type: str | None = None, *, algorithm: str = 'sha256') → str[source]

Compute a deterministic id from a FHIR identifier by hashing its system and value.

Parameters:

  • identifier – The FHIR identifier to compute the id from.

  • resource_type – When given, the id is returned as the relative reference <resource_type>/<id> instead of the bare id.

  • algorithm – The hashlib algorithm to hash with, e.g. "sha256".

Returns:

The deterministic id, optionally qualified with resource_type.

Raises:

ValueError – The identifier’s system or value is missing or blank.

to_fhir.reference_utils

Utilities for creating FHIR references to resources.

create_reference_to(resource: Resource) → Reference[source]

Create a reference to resource, in the form ResourceType/id.

Parameters:

resource – The FHIR resource to create a reference to. It must have a non-blank id.

Raises:

ValueError – The resource has no id, or a blank one.

create_reference_to_identifier(identifier: Identifier, resource_type: str, *, algorithm: str = 'sha256') → Reference[source]

Create a reference to the resource identified by identifier.

The reference is of the form <resource_type>/sha256(system|value).

Parameters:

  • identifier – An identifier of the FHIR resource to create a reference to.

  • resource_type – The resource type to include in the reference.

  • algorithm – The hashlib algorithm to hash with.

Raises:

ValueError – The identifier’s system or value is missing or blank.