fpml 0.0.1__tar.gz

fpml-0.0.1/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: fpml
+Version: 0.0.1
+Summary: The FHIRPath mapping language is a data DSL designed to convert data from QuestionnaireResponse (and not only) to any FHIR Resource.
+License: MIT
+Keywords: fhir,fhirpath
+Author: Beda Software
+Author-email: ilya@beda.software
+Maintainer: Vadim Laletin
+Maintainer-email: vadim@beda.software
+Requires-Python: >=3.9
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: fhirpathpy (>=1.2.1,<2.0.0)
+Project-URL: Bug Tracker, https://github.com/beda-software/FHIRPathMappingLanguage/issues
+Project-URL: Documentation, https://github.com/beda-software/FHIRPathMappingLanguage/tree/main/python/README.md
+Project-URL: Homepage, https://github.com/beda-software/FHIRPathMappingLanguage/tree/main/python
+Project-URL: Repository, https://github.com/beda-software/FHIRPathMappingLanguage/tree/main/python
+Description-Content-Type: text/markdown
+
+# FHIRPathMappingLanguage - fpml python package
+
+## Installation
+
+```bash
+pip install fpml
+```
+
+## Usage
+
+```python
+from fpml import resolve_template
+
+
+resource = {
+    "resourceType": "QuestionnaireResponse",
+    "status": "completed",
+    "item": [
+        {
+            "linkId": "name",
+            "answer": [
+                {
+                    "valueString": "Name"
+                }
+            ]
+        }
+    ]
+}
+
+template = {
+    "resourceType": "Patient",
+    "name": "{{ item.where(linkId='name').answer.valueString }}"
+}
+
+context = {}
+
+result = resolve_template(resource, template, context)
+
+print(result)
+# {'resourceType': 'Patient', 'name': 'Name'}
+```
+
+
+## Development
+
+In `./python` directory:
+
+Run in the shell
+```
+autohooks activate
+```
+
+And edit `../.git/hooks/pre-commit` by replacing the first line with
+```
+#!/usr/bin/env -S poetry --project=./python run python
+```
+
+

fpml-0.0.1/README.md

@@ -0,0 +1,57 @@
+# FHIRPathMappingLanguage - fpml python package
+
+## Installation
+
+```bash
+pip install fpml
+```
+
+## Usage
+
+```python
+from fpml import resolve_template
+
+
+resource = {
+    "resourceType": "QuestionnaireResponse",
+    "status": "completed",
+    "item": [
+        {
+            "linkId": "name",
+            "answer": [
+                {
+                    "valueString": "Name"
+                }
+            ]
+        }
+    ]
+}
+
+template = {
+    "resourceType": "Patient",
+    "name": "{{ item.where(linkId='name').answer.valueString }}"
+}
+
+context = {}
+
+result = resolve_template(resource, template, context)
+
+print(result)
+# {'resourceType': 'Patient', 'name': 'Name'}
+```
+
+
+## Development
+
+In `./python` directory:
+
+Run in the shell
+```
+autohooks activate
+```
+
+And edit `../.git/hooks/pre-commit` by replacing the first line with
+```
+#!/usr/bin/env -S poetry --project=./python run python
+```
+

fpml-0.0.1/fpml/__init__.py

@@ -0,0 +1,12 @@
+import importlib.metadata
+
+from .core.exceptions import FPMLValidationError
+from .core.extract import resolve_template
+
+__title__ = "fpml"
+__version__ = importlib.metadata.version("fpml")
+__author__ = "beda.software"
+__license__ = "MIT"
+__copyright__ = "Copyright 2025 beda.software"
+
+__all__ = ["FPMLValidationError", "resolve_template"]

fpml-0.0.1/fpml/core/constants.py

@@ -0,0 +1,5 @@
+# special root node key for the simplification
+root_node_key = "__rootNode__"
+
+# undefined is a special object used to remove keys from the object (similar to JS)
+undefined = object()

fpml-0.0.1/fpml/core/exceptions.py

@@ -0,0 +1,11 @@
+from .constants import root_node_key
+from .types import Path
+
+
+class FPMLValidationError(Exception):
+    def __init__(self, message: str, path: Path) -> None:
+        path_str = ".".join(str(x) for x in path if x != root_node_key)
+        super().__init__(f"{message}. Path '{path_str}'")
+
+        self.error_message = message
+        self.error_path = path_str

fpml-0.0.1/fpml/core/extract.py

@@ -0,0 +1,354 @@
+import re
+from typing import Any, Optional, cast
+
+from fhirpathpy import evaluate  # type: ignore
+
+from .constants import root_node_key, undefined
+from .exceptions import FPMLValidationError
+from .types import (
+    Context,
+    DictNode,
+    FPOptions,
+    Matcher,
+    MatcherResult,
+    Node,
+    Path,
+    Resource,
+    StrNode,
+    Transformer,
+)
+from .utils import flatten, omit_key
+
+
+def resolve_template(
+    resource: Resource,
+    template: Any,
+    context: Optional[Context] = None,
+    fp_options: Optional[FPOptions] = None,
+    strict: bool = False,
+) -> Any:
+    assert strict is False, "strict is not supported yet"
+
+    return resolve_template_recur(
+        [],
+        resource,
+        template,
+        context or {},
+        fp_options,
+    )
+
+
+def resolve_template_recur(
+    start_path: Path,
+    resource: Resource,
+    template: Any,
+    context: Context,
+    fp_options: Optional[FPOptions] = None,
+) -> Any:
+    return iterate_node(
+        start_path,
+        {root_node_key: template},
+        context or {},
+        lambda path, node, context: process_node(path, resource, node, context, fp_options),
+    ).get(root_node_key, None)
+
+
+def process_node(
+    path: Path,
+    resource: Resource,
+    node: Node,
+    context: Context,
+    fp_options: Optional[FPOptions],
+) -> tuple[Node, Context]:
+    if isinstance(node, dict):
+        new_node, new_context = process_assign_block(path, resource, node, context, fp_options)
+
+        matchers: list[Matcher] = [
+            process_context_block,
+            process_merge_block,
+            process_for_block,
+            process_if_block,
+        ]
+
+        for matcher in matchers:
+            result = matcher(path, resource, new_node, new_context, fp_options)
+            if result:
+                return result["node"], new_context
+
+        return new_node, new_context
+
+    if isinstance(node, str):
+        return process_template_string(path, resource, node, context, fp_options), context
+
+    return node, context
+
+
+def iterate_node(start_path: Path, node: Node, context: Context, transform: Transformer) -> Node:
+    if isinstance(node, list):
+        # Arrays are flattened and null/undefined values are removed here
+        return flatten(
+            [
+                value
+                for value in [
+                    iterate_node(
+                        [*start_path, index],
+                        *transform([*start_path, index], value, context),
+                        transform,
+                    )
+                    for index, value in enumerate(node)
+                ]
+                if value is not None and value is not undefined
+            ]
+        )
+    if isinstance(node, dict):
+        # undefined values are removed from dicts, but nulls are preserved
+        return {
+            key: value
+            for key, value in {
+                key: iterate_node(
+                    [*start_path, key],
+                    *transform([*start_path, key], value, context),
+                    transform,
+                )
+                for key, value in node.items()
+            }.items()
+            if value is not undefined
+        }
+
+    return transform(start_path, node, context)[0]
+
+
+def process_template_string(
+    path: Path,
+    resource: Resource,
+    node: StrNode,
+    context: Context,
+    fp_options: Optional[FPOptions],
+) -> Any:
+    template_regexp = re.compile(r"{{\+?\s*([\s\S]+?)\s*\+?}}")
+    result = node
+
+    for match in template_regexp.finditer(node):
+        expr = match.group(1)
+        try:
+            replacement = evaluate_expression(path, resource, expr, context, fp_options)[0]
+        except IndexError:
+            return None if match.group(0).startswith("{{+") else undefined
+        if match.group(0) == node:
+            return replacement
+        result = result.replace(match.group(0), str(replacement))
+
+    return result
+
+
+def process_context_block(
+    path: Path,
+    resource: Resource,
+    node: DictNode,
+    context: Context,
+    fp_options: Optional[FPOptions],
+) -> Optional[MatcherResult]:
+    keys = list(node.keys())
+    context_regexp = re.compile(r"{{\s*(.+?)\s*}}")
+    context_key = next((k for k in keys if context_regexp.match(k)), None)
+
+    if context_key:
+        matches = context_regexp.match(context_key)
+        expr = matches.group(1) if matches else ""
+
+        if len(keys) > 1:
+            raise FPMLValidationError("Context block must be presented as single key", path)
+
+        answers = evaluate_expression(path, resource, expr, context, fp_options)
+        return {
+            "node": [
+                resolve_template_recur(path, answer, node[context_key], context, fp_options)
+                for answer in answers
+            ]
+        }
+
+    return None
+
+
+def process_for_block(
+    path: Path,
+    resource: Resource,
+    node: DictNode,
+    context: Context,
+    fp_options: Optional[FPOptions],
+) -> Optional[MatcherResult]:
+    keys = list(node.keys())
+
+    for_regexp = re.compile(r"{%\s*for\s+(?:(\w+?)\s*,\s*)?(\w+?)\s+in\s+(.+?)\s*%}")
+    for_key = next((k for k in keys if for_regexp.match(k)), None)
+
+    if for_key:
+        matches = for_regexp.match(for_key)
+        if not matches:
+            return None
+
+        has_index_key = len(matches.groups()) == 3  # noqa: PLR2004
+        index_key = cast(str, matches.group(1)) if has_index_key else None
+        item_key = cast(str, matches.group(2) if has_index_key else matches.group(1))
+        expr = matches.group(3) if has_index_key else matches.group(2)
+
+        if len(keys) > 1:
+            raise FPMLValidationError("For block must be presented as single key", path)
+
+        answers = evaluate_expression(path, resource, expr, context, fp_options)
+
+        return {
+            "node": [
+                resolve_template_recur(
+                    path,
+                    resource,
+                    node[for_key],
+                    {
+                        **context,
+                        item_key: answer,
+                        **({index_key: index} if index_key else {}),
+                    },
+                    fp_options,
+                )
+                for index, answer in enumerate(answers)
+            ]
+        }
+
+    return None
+
+
+def process_if_block(
+    path: Path,
+    resource: Resource,
+    node: dict[str, Any],
+    context: Context,
+    fp_options: Optional[FPOptions],
+) -> Optional[MatcherResult]:
+    keys = list(node.keys())
+
+    if_regexp = re.compile(r"{%\s*if\s+(.+?)\s*%}")
+    else_regexp = re.compile(r"{%\s*else\s*%}")
+
+    if_keys = [k for k in keys if if_regexp.match(k)]
+    if len(if_keys) > 1:
+        raise FPMLValidationError("If block must be presented once", path)
+    if_key = if_keys[0] if if_keys else None
+
+    else_keys = [k for k in keys if else_regexp.match(k)]
+    if len(else_keys) > 1:
+        raise FPMLValidationError("Else block must be presented once", path)
+    else_key = else_keys[0] if else_keys else None
+
+    if else_key and not if_key:
+        raise FPMLValidationError(
+            "Else block must be presented only when if block is presented", path
+        )
+
+    if not if_key:
+        return None
+
+    matches = if_regexp.match(if_key)
+    expr = matches.group(1) if matches else ""
+
+    answer = evaluate_expression(path, resource, f"iif({expr}, true, false)", context, fp_options)[
+        0
+    ]
+
+    new_node = (
+        resolve_template_recur(path, resource, node[if_key], context, fp_options)
+        if answer
+        else (
+            resolve_template_recur(path, resource, node[else_key], context, fp_options)
+            if else_key
+            else undefined
+        )
+    )
+
+    is_merge_behavior = len(keys) != (2 if else_key else 1)
+    if is_merge_behavior:
+        if not isinstance(new_node, dict) and new_node is not None and new_node is not undefined:
+            raise FPMLValidationError(
+                "If/else block must return object for implicit merge into existing node",
+                path,
+            )
+
+        return {
+            "node": {
+                **omit_key(omit_key(node, if_key), else_key),
+                **(new_node if isinstance(new_node, dict) else {}),
+            }
+        }
+
+    return {"node": new_node}
+
+
+def process_merge_block(
+    path: Path,
+    resource: Resource,
+    node: DictNode,
+    context: Context,
+    fp_options: Optional[FPOptions],
+) -> Optional[MatcherResult]:
+    merge_key = next((k for k in node if re.match(r"{%\s*merge\s*%}", k)), None)
+    if merge_key:
+        merged_node = omit_key(node, merge_key)
+        values = node[merge_key] if isinstance(node[merge_key], list) else [node[merge_key]]
+        for value in values:
+            result = resolve_template_recur(path, resource, value, context, fp_options)
+            if not isinstance(result, dict) and result is not None and result is not undefined:
+                raise FPMLValidationError("Merge block must contain object", path)
+            if result is not undefined and result is not None:
+                merged_node.update(result)
+        return {"node": merged_node}
+    return None
+
+
+def process_assign_block(
+    path: Path,
+    resource: Resource,
+    node: DictNode,
+    context: Context,
+    fp_options: Optional[FPOptions],
+) -> tuple[DictNode, Context]:
+    extended_context = context.copy()
+    assign_key = next((k for k in node if re.match(r"{%\s*assign\s*%}", k)), None)
+    if assign_key:
+        if isinstance(node[assign_key], list):
+            for obj in node[assign_key]:
+                if len(obj) != 1:
+                    raise FPMLValidationError(
+                        "Assign block must accept only one key per object", path
+                    )
+                extended_context.update(
+                    resolve_template_recur(path, resource, obj, extended_context, fp_options)
+                )
+        elif isinstance(node[assign_key], dict) and len(node[assign_key]) == 1:
+            extended_context.update(
+                resolve_template_recur(
+                    path,
+                    resource,
+                    node[assign_key],
+                    extended_context,
+                    fp_options,
+                )
+            )
+        else:
+            raise FPMLValidationError("Assign block must accept array or object", path)
+        return omit_key(node, assign_key), extended_context
+    return node, context
+
+
+def evaluate_expression(
+    path: Path,
+    resource: Resource,
+    expression: str,
+    context: Context,
+    fp_options: Optional[FPOptions] = None,
+) -> list[Any]:
+    fp_options_with_default = cast(FPOptions, fp_options or {})
+    model = fp_options_with_default.get("model")
+
+    try:
+        return evaluate(resource, expression, context, model)
+    except Exception as exc:
+        raise FPMLValidationError(f"Cannot evaluate '{expression}': {exc}", path) from exc

fpml-0.0.1/fpml/core/types.py

@@ -0,0 +1,39 @@
+# noqa: A005
+from typing import Any, Callable, Optional, TypedDict, Union
+
+Resource = dict[str, Any]
+Node = Any
+DictNode = dict[str, Any]
+StrNode = str
+Context = dict[str, Any]
+
+Path = list[Union[str, int]]
+
+
+class Model(TypedDict):
+    choiceTypePaths: dict[str, list[str]]
+    pathsDefinedElsewhere: dict[str, str]
+    type2Parent: dict[str, str]
+    path2Type: dict[str, str]
+
+
+class FPOptions(TypedDict):
+    model: Optional[Model]
+
+
+class MatcherResult(TypedDict):
+    node: Optional[Node]
+
+
+Matcher = Callable[
+    [
+        Path,
+        Resource,
+        DictNode,
+        Context,
+        Optional[FPOptions],
+    ],
+    Optional[MatcherResult],
+]
+
+Transformer = Callable[[Path, Node, Context], tuple[Node, Context]]

fpml-0.0.1/fpml/core/utils.py

@@ -0,0 +1,17 @@
+from typing import Any, Optional
+
+
+def flatten(lst: list):
+    result = []
+    for item in lst:
+        if isinstance(item, list):
+            result.extend(flatten(item))
+        else:
+            result.append(item)
+    return result
+
+
+def omit_key(obj: dict[str, Any], key: Optional[str]) -> dict[str, Any]:
+    if key is None:
+        return obj
+    return {k: v for k, v in obj.items() if k != key}

fpml-0.0.1/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "fpml"
+description = "The FHIRPath mapping language is a data DSL designed to convert data from QuestionnaireResponse (and not only) to any FHIR Resource."
+authors = [{ name = "Beda Software", email = "ilya@beda.software" }]
+maintainers = [
+    { name = "Vadim Laletin", email = "vadim@beda.software" },
+    { name = "Ilya Beda", email = "ilya@beda.software" },
+]
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["fhir", "fhirpath"]
+dynamic = ["version", "classifiers"]
+dependencies = ["fhirpathpy (>=1.2.1,<2.0.0)"]
+
+[project.urls]
+homepage = "https://github.com/beda-software/FHIRPathMappingLanguage/tree/main/python"
+repository = "https://github.com/beda-software/FHIRPathMappingLanguage/tree/main/python"
+documentation = "https://github.com/beda-software/FHIRPathMappingLanguage/tree/main/python/README.md"
+"Bug Tracker" = "https://github.com/beda-software/FHIRPathMappingLanguage/issues"
+
+[tool.poetry]
+version = "0.0.1"
+packages = [{ include = "fpml" }]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+readme = ["README.md"]
+
+[tool.poetry.dependencies]
+python = ">=3.9,<4.0"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.9.7"
+mypy = "^1.15.0"
+autohooks-plugin-mypy = "^23.10.0"
+autohooks-plugin-ruff = "^25.2.0"
+autohooks = "^25.2.0"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.3.4"
+pytest-cov = "^6.0.0"
+pyyaml = "^6.0.2"
+types-PyYAML = "^6.0.12"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["I", "E", "F", "N", "B", "C4", "PT", "UP", "I001", "A", "RET", "TID251", "RUF", "SIM", "PYI", "T20", "PIE", "G", "ISC", "PL"]
+
+[tool.mypy]
+files = ["fpml", "tests"]
+ignore_missing_imports = true
+check_untyped_defs = true
+
+[tool.autohooks]
+mode = "poetry"
+pre-commit = ["autohooks.plugins.mypy", "autohooks.plugins.ruff.format", "autohooks.plugins.ruff.check"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --color=yes --cov fpml --cov-report html --doctest-modules"
+log_cli = true
+log_cli_level = "WARNING"