oehrpy 0.1.0__py3-none-any.whl

openehr_sdk/serialization/__init__.py

@@ -0,0 +1,37 @@
+"""
+Serialization utilities for openEHR Reference Model objects.
+
+This module provides functions for serializing and deserializing
+openEHR RM objects to/from various formats:
+
+- Canonical JSON: Standard openEHR JSON with _type discriminator
+- FLAT format: Simplified format used by EHRBase
+"""
+
+from .canonical import (
+    from_canonical,
+    get_type_registry,
+    register_type,
+    to_canonical,
+)
+from .flat import (
+    FlatBuilder,
+    FlatContext,
+    FlatPath,
+    flatten_dict,
+    unflatten_dict,
+)
+
+__all__ = [
+    # Canonical JSON
+    "from_canonical",
+    "to_canonical",
+    "register_type",
+    "get_type_registry",
+    # FLAT format
+    "FlatBuilder",
+    "FlatContext",
+    "FlatPath",
+    "flatten_dict",
+    "unflatten_dict",
+]

openehr_sdk/serialization/canonical.py

@@ -0,0 +1,203 @@
+"""
+Canonical JSON serialization for openEHR Reference Model objects.
+
+The canonical JSON format is the standard openEHR JSON serialization format,
+which includes a `_type` field for polymorphic type identification.
+
+Example:
+    >>> from openehr_sdk.rm import DV_QUANTITY
+    >>> from openehr_sdk.serialization import to_canonical, from_canonical
+    >>>
+    >>> # Create a DV_QUANTITY
+    >>> bp = DV_QUANTITY(magnitude=120.0, units="mm[Hg]", property=...)
+    >>>
+    >>> # Serialize to canonical JSON
+    >>> json_data = to_canonical(bp)
+    >>> # {
+    >>> #   "_type": "DV_QUANTITY",
+    >>> #   "magnitude": 120.0,
+    >>> #   "units": "mm[Hg]",
+    >>> #   ...
+    >>> # }
+    >>>
+    >>> # Deserialize back (with type detection)
+    >>> restored = from_canonical(json_data)
+    >>> assert isinstance(restored, DV_QUANTITY)
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+# Type registry: maps _type string to class
+_TYPE_REGISTRY: dict[str, type[BaseModel]] = {}
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def register_type(cls: type[T]) -> type[T]:
+    """Register a type in the canonical JSON type registry.
+
+    Args:
+        cls: The Pydantic model class to register.
+
+    Returns:
+        The same class (allows use as decorator).
+    """
+    type_name = getattr(cls, "_type_", cls.__name__)
+    _TYPE_REGISTRY[type_name] = cls
+    return cls
+
+
+def get_type_registry() -> dict[str, type[BaseModel]]:
+    """Get a copy of the type registry."""
+    return _TYPE_REGISTRY.copy()
+
+
+def _build_registry() -> None:
+    """Build the type registry from all RM classes."""
+    if _TYPE_REGISTRY:
+        return  # Already built
+
+    # Import all RM types and register them
+    from openehr_sdk import rm
+
+    for name in dir(rm):
+        cls = getattr(rm, name)
+        if isinstance(cls, type) and issubclass(cls, BaseModel) and cls is not BaseModel:
+            type_name = getattr(cls, "_type_", name)
+            _TYPE_REGISTRY[type_name] = cls
+
+
+def to_canonical(
+    obj: BaseModel,
+    *,
+    exclude_none: bool = True,
+    by_alias: bool = False,
+) -> dict[str, Any]:
+    """Serialize a Pydantic model to canonical JSON format.
+
+    The canonical format includes a `_type` field at the root level and
+    recursively in any nested objects that have a _type_ class attribute.
+
+    Args:
+        obj: The Pydantic model to serialize.
+        exclude_none: Whether to exclude None values from output.
+        by_alias: Whether to use field aliases in output.
+
+    Returns:
+        A dictionary suitable for JSON serialization.
+    """
+    data = obj.model_dump(exclude_none=exclude_none, by_alias=by_alias)
+
+    # Add _type field
+    type_name = getattr(obj.__class__, "_type_", obj.__class__.__name__)
+    result = {"_type": type_name}
+    result.update(data)
+
+    # Recursively add _type to nested objects
+    _add_types_recursive(result, obj, exclude_none)
+
+    return result
+
+
+def _add_types_recursive(
+    data: dict[str, Any],
+    obj: BaseModel,
+    exclude_none: bool,
+) -> None:
+    """Recursively add _type fields to nested objects."""
+    for key, value in list(data.items()):
+        if key == "_type":
+            continue
+
+        # Get the corresponding attribute from the object
+        attr = getattr(obj, key, None)
+
+        if attr is None:
+            continue
+
+        if isinstance(attr, BaseModel):
+            # Nested Pydantic model
+            type_name = getattr(attr.__class__, "_type_", attr.__class__.__name__)
+            nested_data = {"_type": type_name}
+            if isinstance(value, dict):
+                nested_data.update(value)
+                data[key] = nested_data
+                _add_types_recursive(nested_data, attr, exclude_none)
+        elif isinstance(attr, list):
+            # List of objects
+            for i, item in enumerate(attr):
+                if isinstance(item, BaseModel) and i < len(value):
+                    type_name = getattr(item.__class__, "_type_", item.__class__.__name__)
+                    if isinstance(value[i], dict):
+                        nested_data = {"_type": type_name}
+                        nested_data.update(value[i])
+                        value[i] = nested_data
+                        _add_types_recursive(nested_data, item, exclude_none)
+
+
+def from_canonical(
+    data: dict[str, Any],
+    *,
+    expected_type: type[T] | None = None,
+) -> T | BaseModel:
+    """Deserialize canonical JSON to a Pydantic model.
+
+    Uses the `_type` field to determine the correct class for polymorphic
+    deserialization.
+
+    Args:
+        data: The canonical JSON data.
+        expected_type: Optional expected type. If provided, validates that
+            the deserialized object is of this type.
+
+    Returns:
+        The deserialized Pydantic model.
+
+    Raises:
+        ValueError: If the _type is not recognized or doesn't match expected_type.
+    """
+    _build_registry()
+
+    # Get the type from the data
+    type_name = data.get("_type")
+    if not type_name:
+        if expected_type:
+            return expected_type.model_validate(data)
+        raise ValueError("Missing _type field in canonical JSON data")
+
+    # Look up the class
+    cls = _TYPE_REGISTRY.get(type_name)
+    if not cls:
+        raise ValueError(f"Unknown type: {type_name}")
+
+    # Validate expected_type if provided
+    if expected_type and not issubclass(cls, expected_type):
+        raise ValueError(f"Type mismatch: expected {expected_type.__name__}, got {type_name}")
+
+    # Remove _type field from data before validation
+    clean_data = {k: v for k, v in data.items() if k != "_type"}
+
+    # Recursively process nested objects
+    _process_nested_types(clean_data)
+
+    return cls.model_validate(clean_data)
+
+
+def _process_nested_types(data: dict[str, Any]) -> None:
+    """Recursively remove _type fields from nested data."""
+    for _key, value in data.items():
+        if isinstance(value, dict):
+            # Remove _type and recurse
+            if "_type" in value:
+                value.pop("_type")
+            _process_nested_types(value)
+        elif isinstance(value, list):
+            for item in value:
+                if isinstance(item, dict):
+                    if "_type" in item:
+                        item.pop("_type")
+                    _process_nested_types(item)

openehr_sdk/serialization/flat.py

@@ -0,0 +1,372 @@
+"""
+FLAT format serialization for EHRBase.
+
+The FLAT format is a simplified key-value representation used by EHRBase
+for composition submission and retrieval. It flattens the hierarchical
+openEHR composition structure into dot-separated paths.
+
+Example FLAT format:
+    {
+        "ctx/language": "en",
+        "ctx/territory": "US",
+        "vital_signs/blood_pressure:0/any_event:0/systolic|magnitude": 120,
+        "vital_signs/blood_pressure:0/any_event:0/systolic|unit": "mm[Hg]",
+        ...
+    }
+
+Note: Full FLAT format support requires template knowledge (OPT files).
+This module provides utilities for working with FLAT format data.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class FlatPath:
+    """Represents a parsed FLAT format path."""
+
+    segments: list[str] = field(default_factory=list)
+    index: int | None = None
+    attribute: str | None = None
+
+    @classmethod
+    def parse(cls, path: str) -> FlatPath:
+        """Parse a FLAT format path string.
+
+        Examples:
+            - "ctx/language" -> FlatPath(["ctx", "language"])
+            - "vital_signs/bp:0/systolic|magnitude" ->
+              FlatPath(["vital_signs", "bp", "systolic"], 0, "magnitude")
+        """
+        result = cls()
+
+        # Split by attribute separator first
+        if "|" in path:
+            path_part, result.attribute = path.rsplit("|", 1)
+        else:
+            path_part = path
+
+        # Split by path separator
+        parts = path_part.split("/")
+
+        for part in parts:
+            # Check for index notation (e.g., "bp:0")
+            match = re.match(r"^(.+):(\d+)$", part)
+            if match:
+                result.segments.append(match.group(1))
+                result.index = int(match.group(2))
+            else:
+                result.segments.append(part)
+
+        return result
+
+    def __str__(self) -> str:
+        """Convert back to FLAT path string."""
+        path = "/".join(self.segments)
+        if self.index is not None:
+            # Add index to the last segment
+            parts = path.rsplit("/", 1)
+            if len(parts) == 2:
+                path = f"{parts[0]}/{parts[1]}:{self.index}"
+            else:
+                path = f"{parts[0]}:{self.index}"
+        if self.attribute:
+            path = f"{path}|{self.attribute}"
+        return path
+
+
+@dataclass
+class FlatContext:
+    """Context fields for FLAT format compositions."""
+
+    language: str = "en"
+    territory: str = "US"
+    composer_name: str | None = None
+    composer_id: str | None = None
+    id_scheme: str | None = None
+    id_namespace: str | None = None
+    health_care_facility_name: str | None = None
+    health_care_facility_id: str | None = None
+    time: str | None = None
+    end_time: str | None = None
+    history_origin: str | None = None
+    participation_name: str | None = None
+    participation_function: str | None = None
+    participation_mode: str | None = None
+    participation_id: str | None = None
+
+    def to_flat(self, prefix: str = "ctx") -> dict[str, Any]:
+        """Convert context to FLAT format.
+
+        Args:
+            prefix: Path prefix to use. Use "ctx" for legacy format,
+                   or composition ID (e.g., "vital_signs_observations") for EHRBase 2.26.0+.
+        """
+        result: dict[str, Any] = {
+            f"{prefix}/language|terminology": "ISO_639-1",
+            f"{prefix}/language|code": self.language,
+            f"{prefix}/territory|terminology": "ISO_3166-1",
+            f"{prefix}/territory|code": self.territory,
+        }
+
+        if self.composer_name:
+            result[f"{prefix}/composer|name"] = self.composer_name
+        if self.composer_id:
+            result[f"{prefix}/composer|id"] = self.composer_id
+        if self.id_scheme:
+            result[f"{prefix}/id_scheme"] = self.id_scheme
+        if self.id_namespace:
+            result[f"{prefix}/id_namespace"] = self.id_namespace
+        if self.health_care_facility_name:
+            result[f"{prefix}/health_care_facility|name"] = self.health_care_facility_name
+        if self.health_care_facility_id:
+            result[f"{prefix}/health_care_facility|id"] = self.health_care_facility_id
+        if self.time:
+            result[f"{prefix}/time"] = self.time
+        if self.end_time:
+            result[f"{prefix}/end_time"] = self.end_time
+        if self.history_origin:
+            result[f"{prefix}/history_origin"] = self.history_origin
+        if self.participation_name:
+            result[f"{prefix}/participation_name"] = self.participation_name
+        if self.participation_function:
+            result[f"{prefix}/participation_function"] = self.participation_function
+        if self.participation_mode:
+            result[f"{prefix}/participation_mode"] = self.participation_mode
+        if self.participation_id:
+            result[f"{prefix}/participation_id"] = self.participation_id
+
+        return result
+
+    @classmethod
+    def from_flat(cls, data: dict[str, Any]) -> FlatContext:
+        """Create context from FLAT format data."""
+        return cls(
+            language=data.get("ctx/language", "en"),
+            territory=data.get("ctx/territory", "US"),
+            composer_name=data.get("ctx/composer_name"),
+            composer_id=data.get("ctx/composer_id"),
+            id_scheme=data.get("ctx/id_scheme"),
+            id_namespace=data.get("ctx/id_namespace"),
+            health_care_facility_name=data.get("ctx/health_care_facility|name"),
+            health_care_facility_id=data.get("ctx/health_care_facility|id"),
+            time=data.get("ctx/time"),
+            end_time=data.get("ctx/end_time"),
+            history_origin=data.get("ctx/history_origin"),
+            participation_name=data.get("ctx/participation_name"),
+            participation_function=data.get("ctx/participation_function"),
+            participation_mode=data.get("ctx/participation_mode"),
+            participation_id=data.get("ctx/participation_id"),
+        )
+
+
+def flatten_dict(data: dict[str, Any], prefix: str = "") -> dict[str, Any]:
+    """Flatten a nested dictionary to FLAT format paths.
+
+    Args:
+        data: Nested dictionary to flatten.
+        prefix: Prefix for all keys.
+
+    Returns:
+        Flattened dictionary with path keys.
+    """
+    result: dict[str, Any] = {}
+
+    for key, value in data.items():
+        new_key = f"{prefix}/{key}" if prefix else key
+
+        if isinstance(value, dict):
+            # Recursively flatten nested dicts
+            result.update(flatten_dict(value, new_key))
+        elif isinstance(value, list):
+            # Handle lists with index notation
+            for i, item in enumerate(value):
+                indexed_key = f"{new_key}:{i}"
+                if isinstance(item, dict):
+                    result.update(flatten_dict(item, indexed_key))
+                else:
+                    result[indexed_key] = item
+        else:
+            result[new_key] = value
+
+    return result
+
+
+def unflatten_dict(data: dict[str, Any]) -> dict[str, Any]:
+    """Unflatten FLAT format paths to nested dictionary.
+
+    Args:
+        data: Flattened dictionary with path keys.
+
+    Returns:
+        Nested dictionary.
+    """
+    result: dict[str, Any] = {}
+
+    for path, value in data.items():
+        parts = path.replace("|", "/").split("/")
+        current = result
+
+        for _i, part in enumerate(parts[:-1]):
+            # Check for index notation
+            match = re.match(r"^(.+):(\d+)$", part)
+            if match:
+                name, idx = match.group(1), int(match.group(2))
+                if name not in current:
+                    current[name] = []
+                while len(current[name]) <= idx:
+                    current[name].append({})
+                current = current[name][idx]
+            else:
+                if part not in current:
+                    current[part] = {}
+                current = current[part]
+
+        # Set the final value
+        final_key = parts[-1]
+        match = re.match(r"^(.+):(\d+)$", final_key)
+        if match:
+            name, idx = match.group(1), int(match.group(2))
+            if name not in current:
+                current[name] = []
+            while len(current[name]) <= idx:
+                current[name].append(None)
+            current[name][idx] = value
+        else:
+            current[final_key] = value
+
+    return result
+
+
+class FlatBuilder:
+    """Builder for creating FLAT format compositions.
+
+    This provides a fluent API for constructing FLAT format data
+    without needing to know the exact path structure.
+
+    Example:
+        >>> builder = FlatBuilder()
+        >>> builder.context(language="en", territory="US", composer_name="Dr. Smith")
+        >>> builder.set("vital_signs/blood_pressure:0/any_event:0/systolic|magnitude", 120)
+        >>> builder.set("vital_signs/blood_pressure:0/any_event:0/systolic|unit", "mm[Hg]")
+        >>> flat_data = builder.build()
+    """
+
+    def __init__(self, composition_prefix: str | None = None) -> None:
+        """Initialize the builder.
+
+        Args:
+            composition_prefix: Composition ID prefix for EHRBase 2.26.0+ format.
+                              If None, uses legacy "ctx" format.
+        """
+        self._data: dict[str, Any] = {}
+        self._context = FlatContext()
+        self._composition_prefix = composition_prefix
+
+    def context(
+        self,
+        language: str = "en",
+        territory: str = "US",
+        composer_name: str | None = None,
+        **kwargs: Any,
+    ) -> FlatBuilder:
+        """Set context fields."""
+        self._context.language = language
+        self._context.territory = territory
+        if composer_name:
+            self._context.composer_name = composer_name
+        for key, value in kwargs.items():
+            if hasattr(self._context, key):
+                setattr(self._context, key, value)
+        return self
+
+    def set(self, path: str, value: Any) -> FlatBuilder:
+        """Set a value at the given FLAT path."""
+        self._data[path] = value
+        return self
+
+    def set_quantity(
+        self,
+        path: str,
+        magnitude: float,
+        unit: str,
+        precision: int | None = None,
+    ) -> FlatBuilder:
+        """Set a DV_QUANTITY at the given path."""
+        self._data[f"{path}|magnitude"] = magnitude
+        self._data[f"{path}|unit"] = unit
+        if precision is not None:
+            self._data[f"{path}|precision"] = precision
+        return self
+
+    def set_coded_text(
+        self,
+        path: str,
+        value: str,
+        code: str,
+        terminology: str = "local",
+    ) -> FlatBuilder:
+        """Set a DV_CODED_TEXT at the given path."""
+        self._data[f"{path}|value"] = value
+        self._data[f"{path}|code"] = code
+        self._data[f"{path}|terminology"] = terminology
+        return self
+
+    def set_proportion(self, path: str, numerator: float, denominator: float) -> FlatBuilder:
+        """Set a DV_PROPORTION at the given path."""
+        self._data[f"{path}|numerator"] = numerator
+        self._data[f"{path}|denominator"] = denominator
+        return self
+
+    def set_text(self, path: str, value: str) -> FlatBuilder:
+        """Set a DV_TEXT at the given path."""
+        self._data[path] = value
+        return self
+
+    def set_datetime(self, path: str, value: str) -> FlatBuilder:
+        """Set a DV_DATE_TIME at the given path."""
+        self._data[path] = value
+        return self
+
+    def build(self) -> dict[str, Any]:
+        """Build the final FLAT format dictionary."""
+        prefix = self._composition_prefix if self._composition_prefix else "ctx"
+        result = self._context.to_flat(prefix=prefix)
+
+        # Add category and context fields for EHRBase 2.26.0+ format
+        if self._composition_prefix:
+            from datetime import datetime, timezone
+
+            # Add category
+            result[f"{self._composition_prefix}/category|terminology"] = "openehr"
+            result[f"{self._composition_prefix}/category|code"] = "433"
+            result[f"{self._composition_prefix}/category|value"] = "event"
+
+            # Add context/start_time if not already set
+            context_time_key = f"{self._composition_prefix}/context/start_time"
+            if context_time_key not in result and context_time_key not in self._data:
+                result[context_time_key] = datetime.now(timezone.utc).isoformat()
+
+            # Add context/setting if not already set
+            context_setting_code = f"{self._composition_prefix}/context/setting|code"
+            if context_setting_code not in result and context_setting_code not in self._data:
+                result[f"{self._composition_prefix}/context/setting|terminology"] = "openehr"
+                result[context_setting_code] = "238"
+                result[f"{self._composition_prefix}/context/setting|value"] = "other care"
+
+        result.update(self._data)
+        return result
+
+
+# Re-export for convenience
+__all__ = [
+    "FlatPath",
+    "FlatContext",
+    "FlatBuilder",
+    "flatten_dict",
+    "unflatten_dict",
+]

openehr_sdk/templates/__init__.py

@@ -0,0 +1,40 @@
+"""
+Template builders and OPT parsing for openEHR.
+
+This module provides:
+- OPT (Operational Template) XML parser
+- Template-specific composition builders
+- Pre-built builders for common templates
+- OPT-to-Builder code generator
+"""
+
+from .builder_generator import (
+    BuilderGenerator,
+    generate_builder_from_opt,
+)
+from .builders import (
+    TemplateBuilder,
+    VitalSignsBuilder,
+)
+from .opt_parser import (
+    ArchetypeNode,
+    ConstraintDefinition,
+    OPTParser,
+    TemplateDefinition,
+    parse_opt,
+)
+
+__all__ = [
+    # OPT Parser
+    "OPTParser",
+    "TemplateDefinition",
+    "ArchetypeNode",
+    "ConstraintDefinition",
+    "parse_opt",
+    # Builder Generator
+    "BuilderGenerator",
+    "generate_builder_from_opt",
+    # Builders
+    "TemplateBuilder",
+    "VitalSignsBuilder",
+]