oehrpy 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

{oehrpy-0.1.0.dist-info → oehrpy-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oehrpy
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Python SDK for openEHR with type-safe Reference Model classes, template builders, and EHRBase client
 Project-URL: Homepage, https://github.com/platzhersh/oehrpy
 Project-URL: Documentation, https://github.com/platzhersh/oehrpy#readme

{oehrpy-0.1.0.dist-info → oehrpy-0.2.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 openehr_sdk/__init__.py,sha256=Rzs3NFgVa-P2ljZu2-OXcgkKBrhE_mAwWf9HnnVwrB8,1295
 openehr_sdk/aql/__init__.py,sha256=auR0SKnnnAhzRzq2nU0YZSzUPKmAzYoXXdWs9Kxzoq8,958
-openehr_sdk/aql/builder.py,sha256=APYpX-MhgKllz8USb1XLnW8zI4BN3ZTe5Wxv1DjIex4,17053
-openehr_sdk/client/__init__.py,sha256=swqiwHCbwyIvq_newgkUEfGq6FvHV_CFfU_fYw2rw08,626
-openehr_sdk/client/ehrbase.py,sha256=kTY6j0cTDWfJxinWizODzhZ2xO9NcAGjkyFgaYArvtQ,20740
+openehr_sdk/aql/builder.py,sha256=XptfUJVuMbUAa-LY-XFWxWDXFzBbMSHZStNloz2PAGo,17053
+openehr_sdk/client/__init__.py,sha256=GTa8fnE-6tLCYGCthxF_PAVVoJ_ESVkPfVWFdlemAlE,822
+openehr_sdk/client/ehrbase.py,sha256=ZVR7sySYfIc6aB5WZnnx3-TDnAjCT7vPFJZr61ziJww,28480
 openehr_sdk/rm/__init__.py,sha256=yS5JAFaUuoo3D-k_Q9V78j2cBQKTW4EMK9LYEl34ZAc,457
-openehr_sdk/rm/rm_types.py,sha256=QQtWk5QZD-Xh8VAPScPQYnXu-zoQar94ZFv2JPSzQUc,50511
+openehr_sdk/rm/rm_types.py,sha256=7DLcfubGplYPIhF6byBsrnEO0ayOw_bBeJbzrDqbZ-Q,50518
 openehr_sdk/serialization/__init__.py,sha256=aucmds3NXlq1nQrjQNZnYR6PzqT63lAcCLh3og2AtM8,748
 openehr_sdk/serialization/canonical.py,sha256=hQMLaKWne9Ep_mv0VrT7kJa0y89C37YEB5owRpACRag,6325
 openehr_sdk/serialization/flat.py,sha256=w8hh6jGGsVHzvnjm1RlMoAhAxuhLumfuV_rrC5sH60A,13122
@@ -12,7 +12,7 @@ openehr_sdk/templates/__init__.py,sha256=_9Fwua5Mw_mM5n9CaKqXql12GSQyVvqdc_-J-jx
 openehr_sdk/templates/builder_generator.py,sha256=oTYcsvmwGasUfGU3zmW9O79eCFyyprO4hkGJ5SvMB5I,13679
 openehr_sdk/templates/builders.py,sha256=CJuOrobrCNWBbEyHbVJTzGqxApZ7CAyZrhUmY9ctvWg,13665
 openehr_sdk/templates/opt_parser.py,sha256=WzOFYUHgAYTn7hk8LWghqP2gjiG9t3LWlYpQ3-999pg,12423
-oehrpy-0.1.0.dist-info/METADATA,sha256=Tf-pVSj8lJ4wPt7rFBMnAkTjRgcnznH8p2ZC5WYm91E,11972
-oehrpy-0.1.0.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
-oehrpy-0.1.0.dist-info/licenses/LICENSE,sha256=2RQ4UN7dGDVJh_e9NTzuaUzdMWMDsy1jgLPxKxJahus,1073
-oehrpy-0.1.0.dist-info/RECORD,,
+oehrpy-0.2.0.dist-info/METADATA,sha256=l4yTTO-SCYrJRjifCxqQ4wJUEN2i5gt8-jVuC-wCqKQ,11972
+oehrpy-0.2.0.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
+oehrpy-0.2.0.dist-info/licenses/LICENSE,sha256=2RQ4UN7dGDVJh_e9NTzuaUzdMWMDsy1jgLPxKxJahus,1073
+oehrpy-0.2.0.dist-info/RECORD,,

openehr_sdk/aql/builder.py

@@ -66,7 +66,7 @@ class FromClause:
 
         # EHR clause
         if self.ehr_id_param:
-            parts.append(f"EHR {self.ehr_alias}[ehr_id/value=:{self.ehr_id_param}]")
+            parts.append(f"EHR {self.ehr_alias}[ehr_id/value=${self.ehr_id_param}]")
         else:
             parts.append(f"EHR {self.ehr_alias}")
 
@@ -178,7 +178,7 @@ class AQLBuilder:
         ...     .select("c/context/start_time/value", alias="time")
         ...     .from_ehr("e")
         ...     .contains_composition("c", "IDCR - Vital Signs Encounter.v1")
-        ...     .where("e/ehr_id/value = :ehr_id")
+        ...     .where("e/ehr_id/value = $ehr_id")
         ...     .order_by("c/context/start_time/value", descending=True)
         ...     .limit(10)
         ...     .build()
@@ -269,7 +269,7 @@ class AQLBuilder:
 
         if archetype_id:
             param_name = f"{alias}_archetype_id"
-            containment = f"{rm_type} {alias}[archetype_id/value=:{param_name}]"
+            containment = f"{rm_type} {alias}[archetype_id/value=${param_name}]"
             self._parameters[param_name] = archetype_id
         else:
             containment = f"{rm_type} {alias}"
@@ -299,7 +299,7 @@ class AQLBuilder:
             self._from_clause = FromClause()
 
         if archetype_id:
-            containment = f"COMPOSITION {alias}[archetype_id/value=:{alias}_archetype_id]"
+            containment = f"COMPOSITION {alias}[archetype_id/value=${alias}_archetype_id]"
             self._parameters[f"{alias}_archetype_id"] = archetype_id
         else:
             containment = f"COMPOSITION {alias}"
@@ -309,7 +309,7 @@ class AQLBuilder:
         # Add template_id filter as parameterized WHERE clause
         if template_id:
             self._where_clause.add(
-                f"{alias}/archetype_details/template_id/value = :{template_id_param}"
+                f"{alias}/archetype_details/template_id/value = ${template_id_param}"
             )
             self._parameters[template_id_param] = template_id
 
@@ -373,7 +373,7 @@ class AQLBuilder:
         Returns:
             Self for method chaining.
         """
-        return self.where(f"{ehr_alias}/ehr_id/value = :{param_name}")
+        return self.where(f"{ehr_alias}/ehr_id/value = ${param_name}")
 
     def where_template(
         self,
@@ -391,7 +391,7 @@ class AQLBuilder:
         Returns:
             Self for method chaining.
         """
-        self.where(f"{composition_alias}/archetype_details/template_id/value = :{param_name}")
+        self.where(f"{composition_alias}/archetype_details/template_id/value = ${param_name}")
         if template_id:
             self._parameters[param_name] = template_id
         return self
@@ -417,10 +417,10 @@ class AQLBuilder:
             Self for method chaining.
         """
         if start:
-            self.where(f"{path} >= :{start_param}")
+            self.where(f"{path} >= ${start_param}")
             self._parameters[start_param] = start
         if end:
-            self.where(f"{path} <= :{end_param}")
+            self.where(f"{path} <= ${end_param}")
             self._parameters[end_param] = end
         return self
 

openehr_sdk/client/__init__.py

@@ -9,13 +9,16 @@ from .ehrbase import (
     AuthenticationError,
     CompositionFormat,
     CompositionResponse,
+    CompositionVersionResponse,
     EHRBaseClient,
     EHRBaseConfig,
     EHRBaseError,
     EHRResponse,
     NotFoundError,
+    PreconditionFailedError,
     QueryResponse,
     ValidationError,
+    VersionedCompositionResponse,
 )
 
 __all__ = [
@@ -24,9 +27,12 @@ __all__ = [
     "EHRResponse",
     "CompositionResponse",
     "CompositionFormat",
+    "CompositionVersionResponse",
     "QueryResponse",
+    "VersionedCompositionResponse",
     "EHRBaseError",
     "AuthenticationError",
     "NotFoundError",
+    "PreconditionFailedError",
     "ValidationError",
 ]

openehr_sdk/client/ehrbase.py

@@ -72,6 +72,12 @@ class ValidationError(EHRBaseError):
     pass
 
 
+class PreconditionFailedError(EHRBaseError):
+    """Version conflict — the If-Match header did not match (HTTP 412)."""
+
+    pass
+
+
 # Response dataclasses
 
 
@@ -110,13 +116,25 @@ class CompositionResponse:
     @classmethod
     def from_response(cls, data: dict[str, Any], ehr_id: str | None = None) -> CompositionResponse:
         """Create from API response."""
+        # Try canonical format first (uid is a dict with "value" key)
         uid_data = data.get("uid")
         uid = uid_data.get("value", "") if isinstance(uid_data, dict) else uid_data or ""
+
+        template_id = data.get("archetype_details", {}).get("template_id", {}).get("value")
+        archetype_id = data.get("archetype_details", {}).get("archetype_id", {}).get("value")
+
+        # For FLAT format responses, extract uid from */_uid key
+        if not uid:
+            for key, value in data.items():
+                if key.endswith("/_uid") and isinstance(value, str):
+                    uid = value
+                    break
+
         return cls(
             uid=uid,
             ehr_id=ehr_id,
-            template_id=data.get("archetype_details", {}).get("template_id", {}).get("value"),
-            archetype_id=data.get("archetype_details", {}).get("archetype_id", {}).get("value"),
+            template_id=template_id,
+            archetype_id=archetype_id,
             composition=data,
         )
 
@@ -166,6 +184,58 @@ class TemplateResponse:
         )
 
 
+@dataclass
+class VersionedCompositionResponse:
+    """Response from versioned composition metadata endpoint."""
+
+    uid: str
+    owner_id: str | None = None
+    time_created: str | None = None
+
+    @classmethod
+    def from_response(cls, data: dict[str, Any]) -> VersionedCompositionResponse:
+        """Create from API response."""
+        uid_data = data.get("uid", {})
+        uid = uid_data.get("value", "") if isinstance(uid_data, dict) else uid_data or ""
+        owner_data = data.get("owner_id", {})
+        owner_id = owner_data.get("value", "") if isinstance(owner_data, dict) else owner_data
+        time_created_data = data.get("time_created", {})
+        time_created = (
+            time_created_data.get("value", "")
+            if isinstance(time_created_data, dict)
+            else time_created_data
+        )
+        return cls(uid=uid, owner_id=owner_id, time_created=time_created)
+
+
+@dataclass
+class CompositionVersionResponse:
+    """Response from a specific composition version endpoint."""
+
+    version_uid: str
+    preceding_version_uid: str | None = None
+    lifecycle_state: str | None = None
+    commit_audit: dict[str, Any] | None = None
+    data: dict[str, Any] | None = None
+
+    @classmethod
+    def from_response(cls, data: dict[str, Any]) -> CompositionVersionResponse:
+        """Create from API response."""
+        uid_data = data.get("uid", {})
+        version_uid = uid_data.get("value", "") if isinstance(uid_data, dict) else uid_data or ""
+        preceding = data.get("preceding_version_uid", {})
+        preceding_uid = preceding.get("value", "") if isinstance(preceding, dict) else preceding
+        lifecycle = data.get("lifecycle_state", {})
+        lifecycle_state = lifecycle.get("value", "") if isinstance(lifecycle, dict) else lifecycle
+        return cls(
+            version_uid=version_uid,
+            preceding_version_uid=preceding_uid or None,
+            lifecycle_state=lifecycle_state or None,
+            commit_audit=data.get("commit_audit"),
+            data=data.get("data"),
+        )
+
+
 @dataclass
 class EHRBaseConfig:
     """Configuration for EHRBase client."""
@@ -268,6 +338,11 @@ class EHRBaseClient:
                 "Resource not found",
                 status_code=response.status_code,
             )
+        if response.status_code == 412:
+            raise PreconditionFailedError(
+                "Version conflict: the preceding version UID does not match the latest version",
+                status_code=response.status_code,
+            )
         if response.status_code == 400 or response.status_code == 422:
             try:
                 error_data = response.json()
@@ -318,24 +393,37 @@ class EHRBaseClient:
         Returns:
             EHRResponse with the created EHR details.
         """
-        headers = {}
+        headers: dict[str, str] = {"Prefer": "return=representation"}
         if ehr_id:
-            headers["Prefer"] = "return=representation"
             response = await self.client.put(
                 f"/rest/openehr/v1/ehr/{ehr_id}",
                 headers=headers,
             )
         else:
-            headers["Prefer"] = "return=representation"
-            params = {}
-            if subject_id:
-                params["subject_id"] = subject_id
-            if subject_namespace:
-                params["subject_namespace"] = subject_namespace
+            body = None
+            if subject_id and subject_namespace:
+                body = {
+                    "_type": "EHR_STATUS",
+                    "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1",
+                    "name": {"value": "EHR Status"},
+                    "subject": {
+                        "external_ref": {
+                            "id": {
+                                "_type": "GENERIC_ID",
+                                "value": subject_id,
+                                "scheme": "id_scheme",
+                            },
+                            "namespace": subject_namespace,
+                            "type": "PERSON",
+                        }
+                    },
+                    "is_modifiable": True,
+                    "is_queryable": True,
+                }
             response = await self.client.post(
                 "/rest/openehr/v1/ehr",
                 headers=headers,
-                params=params if params else None,
+                json=body,
             )
 
         data = self._handle_response(response)
@@ -439,9 +527,17 @@ class EHRBaseClient:
         """
         format_str = format.value if isinstance(format, CompositionFormat) else format
 
+        # Extract versioned object UID (uuid::system::version -> uuid::system)
+        uid_parts = composition_uid.split("::")
+        versioned_object_uid = "::".join(uid_parts[:2]) if len(uid_parts) >= 2 else composition_uid
+
+        params: dict[str, str] = {}
+        if format_str:
+            params["format"] = format_str
+
         response = await self.client.get(
-            f"/rest/openehr/v1/ehr/{ehr_id}/composition/{composition_uid}",
-            params={"format": format_str} if format_str else None,
+            f"/rest/openehr/v1/ehr/{ehr_id}/composition/{versioned_object_uid}",
+            params=params if params else None,
         )
 
         data = self._handle_response(response)
@@ -450,7 +546,8 @@ class EHRBaseClient:
     async def update_composition(
         self,
         ehr_id: str,
-        composition_uid: str,
+        versioned_object_uid: str,
+        preceding_version_uid: str,
         composition: dict[str, Any],
         template_id: str | None = None,
         format: str | CompositionFormat = CompositionFormat.FLAT,
@@ -459,23 +556,27 @@ class EHRBaseClient:
 
         Args:
             ehr_id: The EHR ID.
-            composition_uid: The composition UID (versioned).
+            versioned_object_uid: The composition's UUID (used in the request path).
+            preceding_version_uid: Full version string (e.g. ``uuid::domain::1``),
+                sent as the ``If-Match`` header for optimistic concurrency.
             composition: The updated composition data.
             template_id: Template ID.
             format: Composition format.
 
         Returns:
             CompositionResponse with updated composition.
+
+        Raises:
+            PreconditionFailedError: If the preceding version UID does not match
+                the latest version (HTTP 412).
+            NotFoundError: If the composition has been deleted (HTTP 404).
         """
         format_str = format.value if isinstance(format, CompositionFormat) else format
 
-        # Extract base UID without version
-        base_uid = composition_uid.split("::")[0] if "::" in composition_uid else composition_uid
-
         headers = {
             "Prefer": "return=representation",
             "Content-Type": "application/json",
-            "If-Match": composition_uid,
+            "If-Match": preceding_version_uid,
         }
 
         params = {}
@@ -485,7 +586,7 @@ class EHRBaseClient:
             params["format"] = format_str
 
         response = await self.client.put(
-            f"/rest/openehr/v1/ehr/{ehr_id}/composition/{base_uid}",
+            f"/rest/openehr/v1/ehr/{ehr_id}/composition/{versioned_object_uid}",
             json=composition,
             headers=headers,
             params=params if params else None,
@@ -505,13 +606,120 @@ class EHRBaseClient:
             ehr_id: The EHR ID.
             composition_uid: The composition UID.
         """
-        base_uid = composition_uid.split("::")[0] if "::" in composition_uid else composition_uid
+        # Extract versioned object UID (uuid::system::version -> uuid::system)
+        uid_parts = composition_uid.split("::")
+        versioned_object_uid = "::".join(uid_parts[:2]) if len(uid_parts) >= 2 else composition_uid
 
         response = await self.client.delete(
-            f"/rest/openehr/v1/ehr/{ehr_id}/composition/{base_uid}",
+            f"/rest/openehr/v1/ehr/{ehr_id}/composition/{versioned_object_uid}",
         )
         self._handle_response(response)
 
+    # Composition Versioning Operations
+
+    async def get_composition_at_time(
+        self,
+        ehr_id: str,
+        versioned_object_uid: str,
+        version_at_time: str,
+        format: str | CompositionFormat = CompositionFormat.CANONICAL,
+    ) -> CompositionResponse:
+        """Get a composition as it existed at a specific point in time.
+
+        Args:
+            ehr_id: The EHR ID.
+            versioned_object_uid: The composition's UUID.
+            version_at_time: ISO 8601 timestamp.
+            format: Desired response format.
+
+        Returns:
+            CompositionResponse with the composition at that time.
+        """
+        format_str = format.value if isinstance(format, CompositionFormat) else format
+
+        params: dict[str, str] = {"version_at_time": version_at_time}
+        if format_str:
+            params["format"] = format_str
+
+        response = await self.client.get(
+            f"/rest/openehr/v1/ehr/{ehr_id}/composition/{versioned_object_uid}",
+            params=params,
+        )
+
+        data = self._handle_response(response)
+        return CompositionResponse.from_response(data, ehr_id)
+
+    async def get_versioned_composition(
+        self,
+        ehr_id: str,
+        versioned_object_uid: str,
+    ) -> VersionedCompositionResponse:
+        """Get versioned composition metadata.
+
+        Args:
+            ehr_id: The EHR ID.
+            versioned_object_uid: The composition's UUID.
+
+        Returns:
+            VersionedCompositionResponse with metadata (UID, owner ID, time created).
+        """
+        response = await self.client.get(
+            f"/rest/openehr/v1/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}",
+        )
+
+        data = self._handle_response(response)
+        return VersionedCompositionResponse.from_response(data)
+
+    async def get_composition_version(
+        self,
+        ehr_id: str,
+        versioned_object_uid: str,
+        version_uid: str,
+    ) -> CompositionVersionResponse:
+        """Get a specific version of a composition.
+
+        Args:
+            ehr_id: The EHR ID.
+            versioned_object_uid: The composition's UUID.
+            version_uid: The specific version UID (e.g. ``uuid::domain::1``).
+
+        Returns:
+            CompositionVersionResponse with full version and audit metadata.
+        """
+        response = await self.client.get(
+            f"/rest/openehr/v1/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version/{version_uid}",
+        )
+
+        data = self._handle_response(response)
+        return CompositionVersionResponse.from_response(data)
+
+    async def list_composition_versions(
+        self,
+        ehr_id: str,
+        versioned_object_uid: str,
+    ) -> list[CompositionVersionResponse]:
+        """List all versions of a composition.
+
+        Args:
+            ehr_id: The EHR ID.
+            versioned_object_uid: The composition's UUID.
+
+        Returns:
+            List of CompositionVersionResponse with version descriptors.
+        """
+        response = await self.client.get(
+            f"/rest/openehr/v1/ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version",
+        )
+
+        data = self._handle_response(response)
+        if isinstance(data, list):
+            return [CompositionVersionResponse.from_response(v) for v in data]
+        # Some servers return the list under a key
+        versions = data.get("versions", data.get("items", []))
+        if isinstance(versions, list):
+            return [CompositionVersionResponse.from_response(v) for v in versions]
+        return []
+
     # Query Operations
 
     async def query(

openehr_sdk/rm/rm_types.py

@@ -1030,7 +1030,7 @@ class HISTORY(BaseModel):
     archetype_details: ARCHETYPED | None = None
     feeder_audit: FEEDER_AUDIT | None = None
     links: list[LINK] | None = None
-    origin: DV_DATE_TIME | None
+    origin: DV_DATE_TIME | None = None
     period: DV_DURATION | None = None
     duration: DV_DURATION | None = None
     summary: Any | None = None