helix.fhir.client.sdk 4.2.15__py3-none-any.whl → 4.2.16__py3-none-any.whl

helix_fhir_client_sdk/fhir_client.py

@@ -488,6 +488,37 @@ class FhirClient(
         implementation. This allows for custom session management, connection pooling,
         or persistent session support.
 
+        **Important**: When you provide a custom session factory, YOU are responsible
+        for managing the session lifecycle, including closing it when done. The SDK
+        will NOT automatically close user-provided sessions.
+
+        Example with a persistent session for connection reuse (~4× performance boost):
+
+        .. code-block:: python
+
+            import aiohttp
+            from helix_fhir_client_sdk.fhir_client import FhirClient
+
+            # Create persistent session
+            session = aiohttp.ClientSession()
+
+            try:
+                # Configure FhirClient to use persistent session
+                fhir_client = (
+                    FhirClient()
+                    .url("http://fhir.example.com")
+                    .resource("Patient")
+                    .use_http_session(lambda: session)  # User provides session
+                )
+
+                # Multiple requests reuse the same connection
+                response1 = await fhir_client.get_async()
+                response2 = await fhir_client.clone().resource("Observation").get_async()
+
+            finally:
+                # User must close the session when done
+                await session.close()
+
         :param fn_create_http_session: callable that returns a ClientSession, or None to use default
         """
         self._fn_create_http_session = fn_create_http_session

helix_fhir_client_sdk/fhir_delete_mixin.py

@@ -1,7 +1,11 @@
 import json
 
 from furl import furl
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
 
+from helix_fhir_client_sdk.open_telemetry.attribute_names import FhirClientSdkOpenTelemetryAttributeNames
+from helix_fhir_client_sdk.open_telemetry.span_names import FhirClientSdkOpenTelemetrySpanNames
 from helix_fhir_client_sdk.responses.fhir_client_protocol import FhirClientProtocol
 from helix_fhir_client_sdk.responses.fhir_delete_response import FhirDeleteResponse
 from helix_fhir_client_sdk.structures.get_access_token_result import (
@@ -15,6 +19,8 @@ from helix_fhir_client_sdk.utilities.retryable_aiohttp_response import (
     RetryableAioHttpResponse,
 )
 
+TRACER = trace.get_tracer(__name__)
+
 
 class FhirDeleteMixin(FhirClientProtocol):
     async def delete_async(self) -> FhirDeleteResponse:
@@ -29,50 +35,59 @@ class FhirDeleteMixin(FhirClientProtocol):
             raise ValueError("delete requires the ID of FHIR object to delete")
         if not self._resource:
             raise ValueError("delete requires a FHIR resource type")
-        full_uri: furl = furl(self._url)
-        full_uri /= self._resource
-        full_uri /= id_list
-        # setup retry
-        # set up headers
-        headers: dict[str, str] = {}
-        headers.update(self._additional_request_headers)
-        self._internal_logger.debug(f"Request headers: {headers}")
-
-        access_token_result: GetAccessTokenResult = await self.get_access_token_async()
-        access_token: str | None = access_token_result.access_token
-        # set access token in request if present
-        if access_token:
-            headers["Authorization"] = f"Bearer {access_token}"
-
-        async with RetryableAioHttpClient(
-            fn_get_session=lambda: self.create_http_session(),
-            refresh_token_func=self._refresh_token_function,
-            retries=self._retry_count,
-            exclude_status_codes_from_retry=self._exclude_status_codes_from_retry,
-            use_data_streaming=self._use_data_streaming,
-            compress=False,
-            throw_exception_on_error=self._throw_exception_on_error,
-            log_all_url_results=self._log_all_response_urls,
-            access_token=self._access_token,
-            access_token_expiry_date=self._access_token_expiry_date,
-            tracer_request_func=self._trace_request_function,
-        ) as client:
-            response: RetryableAioHttpResponse = await client.delete(url=full_uri.tostr(), headers=headers)
-            request_id = response.response_headers.get("X-Request-ID", None)
-            self._internal_logger.debug(f"X-Request-ID={request_id}")
-            if response.status == 200:
-                if self._logger:
-                    self._logger.info(f"Successfully deleted: {full_uri}")
 
-            return FhirDeleteResponse(
-                request_id=request_id,
-                url=full_uri.tostr(),
-                responses=await response.get_text_async(),
-                error=f"{response.status}" if not response.status == 200 else None,
-                access_token=access_token,
-                status=response.status,
-                resource_type=self._resource,
-            )
+        with TRACER.start_as_current_span(FhirClientSdkOpenTelemetrySpanNames.DELETE) as span:
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.URL, self._url or "")
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.RESOURCE, self._resource or "")
+            try:
+                full_uri: furl = furl(self._url)
+                full_uri /= self._resource
+                full_uri /= id_list
+                # setup retry
+                # set up headers
+                headers: dict[str, str] = {}
+                headers.update(self._additional_request_headers)
+                self._internal_logger.debug(f"Request headers: {headers}")
+
+                access_token_result: GetAccessTokenResult = await self.get_access_token_async()
+                access_token: str | None = access_token_result.access_token
+                # set access token in request if present
+                if access_token:
+                    headers["Authorization"] = f"Bearer {access_token}"
+
+                async with RetryableAioHttpClient(
+                    fn_get_session=lambda: self.create_http_session(),
+                    refresh_token_func=self._refresh_token_function,
+                    retries=self._retry_count,
+                    exclude_status_codes_from_retry=self._exclude_status_codes_from_retry,
+                    use_data_streaming=self._use_data_streaming,
+                    compress=False,
+                    throw_exception_on_error=self._throw_exception_on_error,
+                    log_all_url_results=self._log_all_response_urls,
+                    access_token=self._access_token,
+                    access_token_expiry_date=self._access_token_expiry_date,
+                    tracer_request_func=self._trace_request_function,
+                ) as client:
+                    response: RetryableAioHttpResponse = await client.delete(url=full_uri.tostr(), headers=headers)
+                    request_id = response.response_headers.get("X-Request-ID", None)
+                    self._internal_logger.debug(f"X-Request-ID={request_id}")
+                    if response.status == 200:
+                        if self._logger:
+                            self._logger.info(f"Successfully deleted: {full_uri}")
+
+                    return FhirDeleteResponse(
+                        request_id=request_id,
+                        url=full_uri.tostr(),
+                        responses=await response.get_text_async(),
+                        error=f"{response.status}" if not response.status == 200 else None,
+                        access_token=access_token,
+                        status=response.status,
+                        resource_type=self._resource,
+                    )
+            except Exception as e:
+                span.record_exception(e)
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+                raise
 
     def delete(self) -> FhirDeleteResponse:
         """

helix_fhir_client_sdk/fhir_merge_mixin.py

@@ -8,12 +8,16 @@ from typing import (
 
 import requests
 from furl import furl
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
 
 from helix_fhir_client_sdk.dictionary_writer import convert_dict_to_str
 from helix_fhir_client_sdk.exceptions.fhir_sender_exception import FhirSenderException
 from helix_fhir_client_sdk.exceptions.fhir_validation_exception import (
     FhirValidationException,
 )
+from helix_fhir_client_sdk.open_telemetry.attribute_names import FhirClientSdkOpenTelemetryAttributeNames
+from helix_fhir_client_sdk.open_telemetry.span_names import FhirClientSdkOpenTelemetrySpanNames
 from helix_fhir_client_sdk.responses.fhir_client_protocol import FhirClientProtocol
 from helix_fhir_client_sdk.responses.fhir_merge_response import FhirMergeResponse
 from helix_fhir_client_sdk.structures.get_access_token_result import (
@@ -30,6 +34,8 @@ from helix_fhir_client_sdk.utilities.retryable_aiohttp_response import (
 )
 from helix_fhir_client_sdk.validators.async_fhir_validator import AsyncFhirValidator
 
+TRACER = trace.get_tracer(__name__)
+
 
 class FhirMergeMixin(FhirClientProtocol):
     async def validate_content(
@@ -105,182 +111,198 @@ class FhirMergeMixin(FhirClientProtocol):
         assert self._url, "No FHIR server url was set"
         assert isinstance(json_data_list, list), "This function requires a list"
 
-        self._internal_logger.debug(
-            f"Calling $merge on {self._url} with client_id={self._client_id} and scopes={self._auth_scopes}"
-        )
-        instance_variables_text = convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))
-        if self._internal_logger:
-            self._internal_logger.info(f"parameters: {instance_variables_text}")
-        else:
-            self._internal_logger.info(f"LOGLEVEL (InternalLogger): {self._log_level}")
-            self._internal_logger.info(f"parameters: {instance_variables_text}")
+        with TRACER.start_as_current_span(FhirClientSdkOpenTelemetrySpanNames.MERGE) as span:
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.URL, self._url or "")
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.RESOURCE, self._resource or "")
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.BATCH_SIZE, batch_size or 0)
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.JSON_DATA_COUNT, len(json_data_list))
+            try:
+                self._internal_logger.debug(
+                    f"Calling $merge on {self._url} with client_id={self._client_id} and scopes={self._auth_scopes}"
+                )
+                instance_variables_text = convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))
+                if self._internal_logger:
+                    self._internal_logger.info(f"parameters: {instance_variables_text}")
+                else:
+                    self._internal_logger.info(f"LOGLEVEL (InternalLogger): {self._log_level}")
+                    self._internal_logger.info(f"parameters: {instance_variables_text}")
 
-        request_id: str | None = None
-        response_status: int | None = None
-        full_uri: furl = furl(self._url)
-        assert self._resource
-        full_uri /= self._resource
-        headers = {"Content-Type": "application/fhir+json"}
-        headers.update(self._additional_request_headers)
-        self._internal_logger.debug(f"Request headers: {headers}")
+                request_id: str | None = None
+                response_status: int | None = None
+                full_uri: furl = furl(self._url)
+                assert self._resource
+                full_uri /= self._resource
+                headers = {"Content-Type": "application/fhir+json"}
+                headers.update(self._additional_request_headers)
+                self._internal_logger.debug(f"Request headers: {headers}")
 
-        responses: list[dict[str, Any]] = []
-        start_time: float = time.time()
-        # set access token in request if present
-        access_token_result: GetAccessTokenResult = await self.get_access_token_async()
-        access_token: str | None = access_token_result.access_token
-        if access_token:
-            headers["Authorization"] = f"Bearer {access_token}"
+                responses: list[dict[str, Any]] = []
+                start_time: float = time.time()
+                # set access token in request if present
+                access_token_result: GetAccessTokenResult = await self.get_access_token_async()
+                access_token: str | None = access_token_result.access_token
+                if access_token:
+                    headers["Authorization"] = f"Bearer {access_token}"
 
-        try:
-            resource_json_list_incoming: list[dict[str, Any]] = [json.loads(json_data) for json_data in json_data_list]
-            resource_json_list_clean: list[dict[str, Any]]
-            errors: list[dict[str, Any]] = []
-            if self._validation_server_url:
-                resource_json_list_clean = await self.validate_content(
-                    errors=errors,
-                    resource_json_list_incoming=resource_json_list_incoming,
-                )
-            else:
-                resource_json_list_clean = resource_json_list_incoming
+                try:
+                    resource_json_list_incoming: list[dict[str, Any]] = [
+                        json.loads(json_data) for json_data in json_data_list
+                    ]
+                    resource_json_list_clean: list[dict[str, Any]]
+                    errors: list[dict[str, Any]] = []
+                    if self._validation_server_url:
+                        resource_json_list_clean = await self.validate_content(
+                            errors=errors,
+                            resource_json_list_incoming=resource_json_list_incoming,
+                        )
+                    else:
+                        resource_json_list_clean = resource_json_list_incoming
 
-            if len(resource_json_list_clean) > 0:
-                chunks: Generator[list[dict[str, Any]], None, None] = ListChunker.divide_into_chunks(
-                    resource_json_list_clean, chunk_size=batch_size
-                )
-                chunk: list[dict[str, Any]]
-                for chunk in chunks:
-                    resource_uri: furl = full_uri.copy()
-                    # if there is only item in the list then send it instead of having it in a list
-                    json_payload: str = json.dumps(chunk[0]) if len(chunk) == 1 else json.dumps(chunk)
-                    # json_payload_bytes: str = json_payload
-                    obj_id = id_ or 1  # TODO: remove this once the node fhir accepts merge without a parameter
-                    assert obj_id
+                    if len(resource_json_list_clean) > 0:
+                        chunks: Generator[list[dict[str, Any]], None, None] = ListChunker.divide_into_chunks(
+                            resource_json_list_clean, chunk_size=batch_size
+                        )
+                        chunk: list[dict[str, Any]]
+                        for chunk in chunks:
+                            resource_uri: furl = full_uri.copy()
+                            # if there is only item in the list then send it instead of having it in a list
+                            json_payload: str = json.dumps(chunk[0]) if len(chunk) == 1 else json.dumps(chunk)
+                            # json_payload_bytes: str = json_payload
+                            obj_id = id_ or 1  # TODO: remove this once the node fhir accepts merge without a parameter
+                            assert obj_id
 
-                    if obj_id is not None and str(obj_id).strip():
-                        resource_uri.path.segments.append(str(obj_id))
-                    # Always append $merge
-                    resource_uri.path.segments.append("$merge")
+                            if obj_id is not None and str(obj_id).strip():
+                                resource_uri.path.segments.append(str(obj_id))
+                            # Always append $merge
+                            resource_uri.path.segments.append("$merge")
 
-                    # Conditionally add the query parameter
-                    if self._smart_merge is False:
-                        resource_uri.add({"smartMerge": "false"})
+                            # Conditionally add the query parameter
+                            if self._smart_merge is False:
+                                resource_uri.add({"smartMerge": "false"})
 
-                    response_text: str | None = None
-                    try:
-                        async with RetryableAioHttpClient(
-                            fn_get_session=lambda: self.create_http_session(),
-                            refresh_token_func=self._refresh_token_function,
-                            tracer_request_func=self._trace_request_function,
-                            retries=self._retry_count,
-                            exclude_status_codes_from_retry=self._exclude_status_codes_from_retry,
-                            use_data_streaming=self._use_data_streaming,
-                            send_data_as_chunked=self._send_data_as_chunked,
-                            compress=self._compress,
-                            throw_exception_on_error=self._throw_exception_on_error,
-                            log_all_url_results=self._log_all_response_urls,
-                            access_token=self._access_token,
-                            access_token_expiry_date=self._access_token_expiry_date,
-                        ) as client:
-                            # should we check if it exists and do a POST then?
-                            response: RetryableAioHttpResponse = await client.post(
-                                url=resource_uri.url,
-                                data=json_payload,
-                                headers=headers,
-                            )
-                            response_status = response.status
-                            request_id = response.response_headers.get("X-Request-ID", None)
-                            self._internal_logger.debug(f"X-Request-ID={request_id}")
-                            if response and response.status == 200:
-                                response_text = await response.get_text_async()
-                                if response_text:
-                                    try:
-                                        raw_response: list[dict[str, Any]] | dict[str, Any] = json.loads(response_text)
-                                        if isinstance(raw_response, list):
-                                            responses = raw_response
+                            response_text: str | None = None
+                            try:
+                                async with RetryableAioHttpClient(
+                                    fn_get_session=lambda: self.create_http_session(),
+                                    refresh_token_func=self._refresh_token_function,
+                                    tracer_request_func=self._trace_request_function,
+                                    retries=self._retry_count,
+                                    exclude_status_codes_from_retry=self._exclude_status_codes_from_retry,
+                                    use_data_streaming=self._use_data_streaming,
+                                    send_data_as_chunked=self._send_data_as_chunked,
+                                    compress=self._compress,
+                                    throw_exception_on_error=self._throw_exception_on_error,
+                                    log_all_url_results=self._log_all_response_urls,
+                                    access_token=self._access_token,
+                                    access_token_expiry_date=self._access_token_expiry_date,
+                                ) as client:
+                                    # should we check if it exists and do a POST then?
+                                    response: RetryableAioHttpResponse = await client.post(
+                                        url=resource_uri.url,
+                                        data=json_payload,
+                                        headers=headers,
+                                    )
+                                    response_status = response.status
+                                    request_id = response.response_headers.get("X-Request-ID", None)
+                                    self._internal_logger.debug(f"X-Request-ID={request_id}")
+                                    if response and response.status == 200:
+                                        response_text = await response.get_text_async()
+                                        if response_text:
+                                            try:
+                                                raw_response: list[dict[str, Any]] | dict[str, Any] = json.loads(
+                                                    response_text
+                                                )
+                                                if isinstance(raw_response, list):
+                                                    responses = raw_response
+                                                else:
+                                                    responses = [raw_response]
+                                            except ValueError as e:
+                                                responses = [{"issue": str(e)}]
                                         else:
-                                            responses = [raw_response]
-                                    except ValueError as e:
-                                        responses = [{"issue": str(e)}]
-                                else:
-                                    responses = []
-                                yield FhirMergeResponse(
+                                            responses = []
+                                        yield FhirMergeResponse(
+                                            request_id=request_id,
+                                            url=resource_uri.url,
+                                            responses=responses + errors,
+                                            error=(json.dumps(responses + errors) if response_status != 200 else None),
+                                            access_token=self._access_token,
+                                            status=response_status if response_status else 500,
+                                            json_data=json_payload,
+                                        )
+                                    else:  # other HTTP errors
+                                        self._internal_logger.info(
+                                            f"POST response for {resource_uri.url}: {response.status}"
+                                        )
+                                        response_text = await response.get_text_async()
+                                        yield FhirMergeResponse(
+                                            request_id=request_id,
+                                            url=resource_uri.url or self._url or "",
+                                            json_data=json_payload,
+                                            responses=[
+                                                {
+                                                    "issue": [
+                                                        {
+                                                            "severity": "error",
+                                                            "code": "exception",
+                                                            "diagnostics": response_text,
+                                                        }
+                                                    ]
+                                                }
+                                            ],
+                                            error=(json.dumps(response_text) if response_text else None),
+                                            access_token=self._access_token,
+                                            status=response.status if response.status else 500,
+                                        )
+                            except requests.exceptions.HTTPError as e:
+                                raise FhirSenderException(
                                     request_id=request_id,
                                     url=resource_uri.url,
-                                    responses=responses + errors,
-                                    error=(json.dumps(responses + errors) if response_status != 200 else None),
-                                    access_token=self._access_token,
-                                    status=response_status if response_status else 500,
+                                    headers=headers,
                                     json_data=json_payload,
-                                )
-                            else:  # other HTTP errors
-                                self._internal_logger.info(f"POST response for {resource_uri.url}: {response.status}")
-                                response_text = await response.get_text_async()
-                                yield FhirMergeResponse(
+                                    response_text=response_text,
+                                    response_status_code=response_status,
+                                    exception=e,
+                                    variables=FhirClientLogger.get_variables_to_log(vars(self)),
+                                    message=f"HttpError: {e}",
+                                    elapsed_time=time.time() - start_time,
+                                ) from e
+                            except Exception as e:
+                                raise FhirSenderException(
                                     request_id=request_id,
-                                    url=resource_uri.url or self._url or "",
+                                    url=resource_uri.url,
+                                    headers=headers,
                                     json_data=json_payload,
-                                    responses=[
-                                        {
-                                            "issue": [
-                                                {
-                                                    "severity": "error",
-                                                    "code": "exception",
-                                                    "diagnostics": response_text,
-                                                }
-                                            ]
-                                        }
-                                    ],
-                                    error=(json.dumps(response_text) if response_text else None),
-                                    access_token=self._access_token,
-                                    status=response.status if response.status else 500,
-                                )
-                    except requests.exceptions.HTTPError as e:
-                        raise FhirSenderException(
+                                    response_text=response_text,
+                                    response_status_code=response_status,
+                                    exception=e,
+                                    variables=FhirClientLogger.get_variables_to_log(vars(self)),
+                                    message=f"Unknown Error: {e}",
+                                    elapsed_time=time.time() - start_time,
+                                ) from e
+                    else:
+                        json_payload = json.dumps(json_data_list)
+                        yield FhirMergeResponse(
                             request_id=request_id,
-                            url=resource_uri.url,
-                            headers=headers,
-                            json_data=json_payload,
-                            response_text=response_text,
-                            response_status_code=response_status,
-                            exception=e,
-                            variables=FhirClientLogger.get_variables_to_log(vars(self)),
-                            message=f"HttpError: {e}",
-                            elapsed_time=time.time() - start_time,
-                        ) from e
-                    except Exception as e:
-                        raise FhirSenderException(
-                            request_id=request_id,
-                            url=resource_uri.url,
-                            headers=headers,
+                            url=full_uri.url,
+                            responses=responses + errors,
+                            error=(json.dumps(responses + errors) if response_status != 200 else None),
+                            access_token=self._access_token,
+                            status=response_status if response_status else 500,
                             json_data=json_payload,
-                            response_text=response_text,
-                            response_status_code=response_status,
-                            exception=e,
-                            variables=FhirClientLogger.get_variables_to_log(vars(self)),
-                            message=f"Unknown Error: {e}",
-                            elapsed_time=time.time() - start_time,
-                        ) from e
-            else:
-                json_payload = json.dumps(json_data_list)
-                yield FhirMergeResponse(
-                    request_id=request_id,
-                    url=full_uri.url,
-                    responses=responses + errors,
-                    error=(json.dumps(responses + errors) if response_status != 200 else None),
-                    access_token=self._access_token,
-                    status=response_status if response_status else 500,
-                    json_data=json_payload,
-                )
-        except AssertionError as e:
-            if self._logger:
-                self._logger.error(
-                    Exception(
-                        f"Assertion: FHIR send failed: {str(e)} for resource: {json_data_list}. "
-                        + f"variables={convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))}"
-                    )
-                )
-            raise e
+                        )
+                except AssertionError as e:
+                    if self._logger:
+                        self._logger.error(
+                            Exception(
+                                f"Assertion: FHIR send failed: {str(e)} for resource: {json_data_list}. "
+                                + f"variables={convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))}"
+                            )
+                        )
+                    raise e
+            except Exception as e:
+                span.record_exception(e)
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+                raise
 
     def merge(
         self,