The FHIRPath Mapping Language (FPML) is a data DSL designed to convert data from QuestionnaireResponse (and not only) to any FHIR Resource.
For more details visit the FHIRPathMappingLanguage specification.
You can install the package from PyPI using the following command:
pip install fpmlThe resolve_template function processes a given template with a specified FHIR resource, optionally applying a context and additional processing options.
from fpml import resolve_template
result = resolve_template(
resource,
template,
context=None,
strict=False,
evaluate=None
)- resource (Resource): The input FHIR resource to process.
- template (Any): The template describing the transformation.
- context (Optional[Context], optional): Additional context data. Defaults to None.
- strict (bool, optional): Whether to enforce strict mode. Defaults to False. See more details on strict mode.
- evaluate (Optional[Evaluate], optional): Evaluates one FHIRPath expression against a resource and a context. Defaults to
make_evaluator(), which compiles every expression on every evaluation.
- Any: The processed output based on the template.
- FPMLValidationError: If validation of the template or resource fails.
For the following QuestionnaireResponse resource:
resource = {
"resourceType": "QuestionnaireResponse",
"status": "completed",
"item": [
{
"linkId": "name",
"answer": [
{
"valueString": "Name"
}
]
}
]
}Here's an example demonstrating how to use the resolve_template function:
from fpml import resolve_template
template = {
"resourceType": "Patient",
"name": [
{
"text": "{{ item.where(linkId='name').answer.valueString }}"
}
]
}
context = {}
result = resolve_template(resource, template, context)
print(result)Output:
{'resourceType': 'Patient', 'name': [{'text': 'Name'}]}from fhirpathpy.models import models
from fpml import make_evaluator, resolve_template
template = {
"resourceType": "Patient",
"name": [
{
"text": "{{ item.where(linkId='name').answer.value }}" # <-- according R4 model
}
]
}
context = {}
evaluate = make_evaluator(models["r4"])
result = resolve_template(resource, template, context, evaluate=evaluate)
print(result)Output:
{'resourceType': 'Patient', 'name': [{'text': 'Name'}]}from fpml import make_evaluator, resolve_template
template = {
"resourceType": "Patient",
"name": [
{
"text": "{{ item.where(linkId='name').answer.valueString.strip() }}" # <-- Custom function
}
]
}
context = {}
user_invocation_table = {
"strip": {
"fn": lambda inputs: [i.strip() for i in inputs],
"arity": {0: []},
}
}
evaluate = make_evaluator(options={"userInvocationTable": user_invocation_table})
result = resolve_template(resource, template, context, evaluate=evaluate)
print(result)Output:
{'resourceType': 'Patient', 'name': [{'text': 'Name'}]}By default every expression is compiled on every evaluation, which is expensive. Pass an evaluate
function to reuse compiled expressions, cached the way your application needs. It takes a resource,
an expression and a context, and returns the list of results.
from functools import lru_cache
from fhirpathpy import compile
from fhirpathpy.models import models
from fpml import resolve_template
@lru_cache(maxsize=1024)
def cached_compile(expression, model_name):
return compile(expression, models.get(model_name))
def evaluate(resource, expression, context):
return cached_compile(expression, "r4")(resource, context)
for resource in resources:
resolve_template(resource, template, context, evaluate=evaluate)Compilation binds the model and the user-defined functions, so cache entries are only reusable for
the same pair. Keep them in the key, like model_name above, when the application evaluates against
more than one model, otherwise expressions compiled for one silently resolve against the other.
A compiled expression retains its parsed AST, so the memory cost grows with the expression length:
1024 of them take about 11mb for short expressions and up to 290mb for 1kb ones. Size the cache for
the number of distinct expressions your templates and questionnaires actually contain.
make_evaluator builds the default evaluator from a model and a user-defined function table, as the
examples above do. A custom evaluator applies both itself.
from fpml import FPMLValidationError, resolve_template
template = {
"resourceType": "Patient",
"name": [
{
"text": "{{ item.where( }}" # <-- Invalid expression
}
]
}
context = {}
try:
resolve_template(resource, template, context)
except FPMLValidationError as e:
print(f"Validation error: {e.error_message}")
print(f"Error path: `{e.error_path}`")Output:
"Validation error: Cannot evaluate 'item.where(': where wrong arity: got 0"
"Error path: `name.0.text`"In strict mode only context variables can be used (starting with percent sigh). Any access of the resource property will raise a validation error.
from fpml import resolve_template
template = {
"resourceType": "Patient",
"name": [
{
"text": "{{ item.where(linkId='name').answer.valueString }}" # <-- Accessing resource attribute
}
]
}
context = {}
resolve_template(resource, template, context, strict=True)Raises an error:
FPMLValidationError: Cannot evaluate 'item.where(linkId='name').answer.valueString': "Forbidden access to resource property 'item' in strict mode. Use context instead.". Path 'name.0.text'
Meanwhile using context:
from fpml import resolve_template
template = {
"resourceType": "Patient",
"name": [
{
"text": "{{ %QuestionnaireResponse.item.where(linkId='name').answer.valueString }}" # <-- Accessing context variable
}
]
}
context = {"QuestionnaireResponse": resource} # <-- Context
result = resolve_template(resource, template, context, strict=True)
print(result)Output:
{'resourceType': 'Patient', 'name': [{'text': 'Name'}]}cd ./python
poetry installTo run tests:
poetry run pytestIn ./python directory:
Run in the shell
autohooks activateAnd edit ../.git/hooks/pre-commit replacing the first line with
#!/usr/bin/env -S poetry --project=./python run python
This project is licensed under the MIT License.