helix.fhir.client.sdk 4.2.3__py3-none-any.whl → 4.2.18__py3-none-any.whl

helix_fhir_client_sdk/fhir_auth_mixin.py

@@ -8,11 +8,13 @@ from threading import Lock
 from typing import TYPE_CHECKING, Any, cast
 
 from furl import furl
+from opentelemetry import trace
 
 from helix_fhir_client_sdk.function_types import (
     RefreshTokenFunction,
     RefreshTokenResult,
 )
+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.structures.get_access_token_result import (
     GetAccessTokenResult,
@@ -31,6 +33,9 @@ if TYPE_CHECKING:
     from helix_fhir_client_sdk.fhir_client import FhirClient
 
 
+TRACER = trace.get_tracer(__name__)
+
+
 class FhirAuthMixin(FhirClientProtocol):
     _time_to_live_in_secs_for_cache: int = 10 * 60
 
@@ -119,15 +124,15 @@ class FhirAuthMixin(FhirClientProtocol):
                 access_token=self._access_token,
                 expiry_date=self._access_token_expiry_date,
             )
+        with TRACER.start_as_current_span(FhirClientSdkOpenTelemetrySpanNames.GET_ACCESS_TOKEN):
+            refresh_token_result: RefreshTokenResult = await self._refresh_token_function(
+                url=None, status_code=0, current_token=None, expiry_date=None, retry_count=0
+            )
+            assert isinstance(refresh_token_result, RefreshTokenResult)
 
-        refresh_token_result: RefreshTokenResult = await self._refresh_token_function(
-            url=None, status_code=0, current_token=None, expiry_date=None, retry_count=0
-        )
-        assert isinstance(refresh_token_result, RefreshTokenResult)
-
-        self.set_access_token(refresh_token_result.access_token)
-        self.set_access_token_expiry_date(refresh_token_result.expiry_date)
-        return GetAccessTokenResult(access_token=self._access_token, expiry_date=self._access_token_expiry_date)
+            self.set_access_token(refresh_token_result.access_token)
+            self.set_access_token_expiry_date(refresh_token_result.expiry_date)
+            return GetAccessTokenResult(access_token=self._access_token, expiry_date=self._access_token_expiry_date)
 
     def authenticate_async_wrapper(self) -> RefreshTokenFunction:
         """
@@ -165,7 +170,8 @@ class FhirAuthMixin(FhirClientProtocol):
         :return: auth server url or None
         """
         async with RetryableAioHttpClient(
-            fn_get_session=lambda: self.create_http_session(),
+            fn_get_session=self._fn_create_http_session or self.create_http_session,
+            caller_managed_session=self._fn_create_http_session is not None,
             exclude_status_codes_from_retry=[404],
             throw_exception_on_error=False,
             use_data_streaming=False,
@@ -267,7 +273,8 @@ class FhirAuthMixin(FhirClientProtocol):
         }
 
         async with RetryableAioHttpClient(
-            fn_get_session=lambda: self.create_http_session(),
+            fn_get_session=self._fn_create_http_session or self.create_http_session,
+            caller_managed_session=self._fn_create_http_session is not None,
             use_data_streaming=False,
             compress=False,
             exclude_status_codes_from_retry=None,

helix_fhir_client_sdk/fhir_client.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import logging
 import ssl
 import uuid
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
 from datetime import datetime
 from logging import Logger
 from os import environ
@@ -26,6 +26,8 @@ from compressedfhir.utilities.compressed_dict.v1.compressed_dict_storage_mode im
     CompressedDictStorageMode,
 )
 from furl import furl
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
 from requests.adapters import BaseAdapter
 
 from helix_fhir_client_sdk.dictionary_writer import convert_dict_to_str
@@ -46,6 +48,7 @@ from helix_fhir_client_sdk.graph.fhir_graph_mixin import FhirGraphMixin
 from helix_fhir_client_sdk.graph.simulated_graph_processor_mixin import (
     SimulatedGraphProcessorMixin,
 )
+from helix_fhir_client_sdk.open_telemetry.span_names import FhirClientSdkOpenTelemetrySpanNames
 from helix_fhir_client_sdk.queue.request_queue_mixin import RequestQueueMixin
 from helix_fhir_client_sdk.responses.fhir_client_protocol import FhirClientProtocol
 from helix_fhir_client_sdk.responses.fhir_get_response import FhirGetResponse
@@ -55,6 +58,8 @@ from helix_fhir_client_sdk.structures.get_access_token_result import (
 from helix_fhir_client_sdk.utilities.async_runner import AsyncRunner
 from helix_fhir_client_sdk.utilities.fhir_client_logger import FhirClientLogger
 
+TRACER = trace.get_tracer(__name__)
+
 
 class FhirClient(
     SimulatedGraphProcessorMixin,
@@ -145,9 +150,13 @@ class FhirClient(
         self._log_all_response_urls: bool = False
         """ If True, logs all response URLs and status codes.  Can take a lot of memory for when there are many responses. """
 
-        self._storage_mode = CompressedDictStorageMode(storage_type="raw")
+        # Default to "raw" storage mode - no in-memory compression, resources stored as plain Python dicts
+        self._storage_mode: CompressedDictStorageMode = CompressedDictStorageMode(storage_type="raw")
+
+        self._create_operation_outcome_for_error: bool | None = False
 
-        self._create_operation_outcome_for_error = False
+        # Optional callable to create HTTP sessions. When set, create_http_session() will use this.
+        self._fn_create_http_session: Callable[[], ClientSession] | None = None
 
     def action(self, action: str) -> FhirClient:
         """
@@ -450,9 +459,14 @@ class FhirClient(
 
     def compress(self, compress: bool) -> FhirClient:
         """
-        Sets the compress flag
+        Sets whether to use HTTP compression (gzip) when sending request data to the server.
+
+        This controls compression of the HTTP request body only, not in-memory storage.
+        Default is True (compression enabled).
+
+        To disable all compression, call: .compress(False)
 
-        :param compress: whether to compress the response
+        :param compress: whether to compress HTTP request body (default: True)
         """
         self._compress = compress
         return self
@@ -466,31 +480,48 @@ class FhirClient(
         self._throw_exception_on_error = throw_exception_on_error
         return self
 
-    def set_persistent_session(self, session: ClientSession | None) -> FhirClient:
+    def use_http_session(self, fn_create_http_session: Callable[[], ClientSession] | None) -> FhirClient:
         """
-        Sets the persistent session to use for requests
+        Sets a custom callable to create HTTP sessions.
 
-        :param session: persistent session
-        """
-        self._persistent_session = session
-        return self
+        When set, create_http_session() will use this callable instead of the default
+        implementation. This allows for custom session management, connection pooling,
+        or persistent session support.
 
-    def use_persistent_session(self, value: bool) -> FhirClient:
-        """
-        Sets the use_persistent_session flag
+        **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.
 
-        :param value: whether to use the persistent session
-        """
-        self._use_persistent_session = value
-        return self
+        Example with a persistent session for connection reuse (~4× performance boost):
 
-    def close_session_after_request(self, value: bool) -> FhirClient:
-        """
-        Sets the _close_session flag (default is True)
+        .. 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
+                )
 
-        :param value: whether to close the session after each request
+                # 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._close_session = value
+        self._fn_create_http_session = fn_create_http_session
         return self
 
     # noinspection PyUnusedLocal
@@ -606,33 +637,34 @@ class FhirClient(
 
         :return: response
         """
-        instance_variables_text = convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))
-        if self._logger:
-            # self._logger.info(f"LOGLEVEL: {self._log_level}")
-            self._logger.debug(f"parameters: {instance_variables_text}")
-        else:
-            self._internal_logger.debug(f"LOGLEVEL (InternalLogger): {self._log_level}")
-            self._internal_logger.debug(f"parameters: {instance_variables_text}")
-        ids: list[str] | None = None
-        if self._id:
-            ids = self._id if isinstance(self._id, list) else [self._id]
-        # actually make the request
-        full_response: FhirGetResponse | None = None
-        async for response in self._get_with_session_async(
-            ids=ids,
-            fn_handle_streaming_chunk=data_chunk_handler,
-            page_number=None,
-            id_above=None,
-            additional_parameters=None,
-            resource_type=None,
-        ):
-            if response:
-                if full_response:
-                    full_response = full_response.append(response)
-                else:
-                    full_response = response
-        assert full_response
-        return full_response
+        with TRACER.start_as_current_span(FhirClientSdkOpenTelemetrySpanNames.GET):
+            instance_variables_text = convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))
+            if self._logger:
+                # self._logger.info(f"LOGLEVEL: {self._log_level}")
+                self._logger.debug(f"parameters: {instance_variables_text}")
+            else:
+                self._internal_logger.debug(f"LOGLEVEL (InternalLogger): {self._log_level}")
+                self._internal_logger.debug(f"parameters: {instance_variables_text}")
+            ids: list[str] | None = None
+            if self._id:
+                ids = self._id if isinstance(self._id, list) else [self._id]
+            # actually make the request
+            full_response: FhirGetResponse | None = None
+            async for response in self._get_with_session_async(
+                ids=ids,
+                fn_handle_streaming_chunk=data_chunk_handler,
+                page_number=None,
+                id_above=None,
+                additional_parameters=None,
+                resource_type=None,
+            ):
+                if response:
+                    if full_response:
+                        full_response = full_response.append(response)
+                    else:
+                        full_response = response
+            assert full_response
+            return full_response
 
     async def get_raw_resources_async(
         self,
@@ -673,27 +705,37 @@ class FhirClient(
 
         :return: async generator of responses
         """
-        instance_variables_text = convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))
-        if self._logger:
-            # self._logger.info(f"LOGLEVEL: {self._log_level}")
-            self._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}")
-        ids: list[str] | None = None
-        if self._id:
-            ids = self._id if isinstance(self._id, list) else [self._id]
-        # actually make the request
-        response: FhirGetResponse | None
-        async for response in self._get_with_session_async(
-            ids=ids,
-            fn_handle_streaming_chunk=data_chunk_handler,
-            page_number=None,
-            id_above=None,
-            additional_parameters=None,
-            resource_type=None,
-        ):
-            yield response
+        span = TRACER.start_span(FhirClientSdkOpenTelemetrySpanNames.GET_STREAMING)
+        try:
+            instance_variables_text = convert_dict_to_str(FhirClientLogger.get_variables_to_log(vars(self)))
+            if self._logger:
+                # self._logger.info(f"LOGLEVEL: {self._log_level}")
+                self._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}")
+            ids: list[str] | None = None
+            if self._id:
+                ids = self._id if isinstance(self._id, list) else [self._id]
+            # actually make the request
+            response: FhirGetResponse | None
+            async for response in self._get_with_session_async(
+                ids=ids,
+                fn_handle_streaming_chunk=data_chunk_handler,
+                page_number=None,
+                id_above=None,
+                additional_parameters=None,
+                resource_type=None,
+            ):
+                yield response
+        except BaseException as exc:  # propagate cancellation/errors but keep span informative
+            # Record exception in span
+            span.record_exception(exc)
+            span.set_status(Status(StatusCode.ERROR, str(exc)))
+            raise
+        finally:
+            # Ensure span is ended after generator is exhausted or error occurs
+            span.end()
 
     def get(self) -> FhirGetResponse:
         """
@@ -804,8 +846,12 @@ class FhirClient(
 
     def create_http_session(self) -> ClientSession:
         """
-        Creates an HTTP Session
+        Creates the SDK's default HTTP Session.
+
+        This method always creates a new aiohttp ClientSession with standard configuration.
+        The SDK manages the lifecycle of sessions created by this method.
 
+        Note: If you want to provide your own session factory, use use_http_session() instead.
         """
         trace_config = aiohttp.TraceConfig()
         # trace_config.on_request_start.append(on_request_start)
@@ -828,17 +874,17 @@ class FhirClient(
         Whether to ask the server to include the total count in the result
 
 
-        :param include_total: whether to include total count
+        :param include_total: whether to include the total count
         """
         self._include_total = include_total
         return self
 
     def filter(self, filter_: list[BaseFilter]) -> FhirClient:
         """
-        Allows adding in a custom filters that derives from BaseFilter
+        Allows adding in custom filters that derive from BaseFilter
 
 
-        :param filter_: list of custom filter instances that derives from BaseFilter.
+        :param filter_: list of custom filter instances that derive from BaseFilter.
         """
         assert isinstance(filter_, list), "This function requires a list"
         self._filters.extend(filter_)
@@ -879,6 +925,8 @@ class FhirClient(
         fhir_client._client_id = self._client_id
         fhir_client._auth_server_url = self._auth_server_url
         fhir_client._login_token = self._login_token
+        fhir_client._access_token = self._access_token
+        fhir_client._access_token_expiry_date = self._access_token_expiry_date
         fhir_client._refresh_token_function = self._refresh_token_function
         fhir_client._exclude_status_codes_from_retry = self._exclude_status_codes_from_retry
         fhir_client._chunk_size = self._chunk_size
@@ -891,6 +939,19 @@ class FhirClient(
         fhir_client._time_to_live_in_secs_for_cache = self._time_to_live_in_secs_for_cache
         fhir_client._validation_server_url = self._validation_server_url
         fhir_client._smart_merge = self._smart_merge
+        fhir_client._compress = self._compress
+        fhir_client._storage_mode = self._storage_mode
+        fhir_client._send_data_as_chunked = self._send_data_as_chunked
+        fhir_client._use_post_for_search = self._use_post_for_search
+        fhir_client._maximum_time_to_retry_on_429 = self._maximum_time_to_retry_on_429
+        fhir_client._retry_count = self._retry_count
+        fhir_client._throw_exception_on_error = self._throw_exception_on_error
+        fhir_client._trace_request_function = self._trace_request_function
+        fhir_client._log_all_response_urls = self._log_all_response_urls
+        fhir_client._create_operation_outcome_for_error = self._create_operation_outcome_for_error
+        fhir_client._fn_create_http_session = self._fn_create_http_session
+        if self._max_concurrent_requests is not None:
+            fhir_client.set_max_concurrent_requests(self._max_concurrent_requests)
         return fhir_client
 
     def set_log_all_response_urls(self, value: bool) -> FhirClient:
@@ -913,18 +974,30 @@ class FhirClient(
 
     def set_storage_mode(self, value: CompressedDictStorageMode) -> FhirClient:
         """
-        Sets the storage mode
+        Sets the in-memory storage mode for FHIR resources.
+
+        This controls how FHIR resources are stored in memory after being received.
+        The default is "raw" (no compression - resources stored as plain Python dicts).
+
+        Available storage types:
+        - "raw": No compression, standard Python dictionaries (default)
+        - "compressed": Zlib/gzip compression in memory
+        - "msgpack": MessagePack binary serialization
+        - "compressed_msgpack": MessagePack + compression
+
+        Note: This is separate from HTTP compression (controlled by .compress()).
+        With default settings, no in-memory compression is applied.
 
-        :param value: storage mode
+        :param value: storage mode (default: raw)
         """
         self._storage_mode = value
         return self
 
-    def set_create_operation_outcome_for_error(self, value: bool) -> FhirClient:
+    def set_create_operation_outcome_for_error(self, value: bool | None) -> FhirClient:
         """
         Sets the create_operation_outcome_for_error flag
 
-        :param value: whether to create operation outcome for error
+        :param value: whether to create an operation outcome for error (True, False, or None)
         """
         self._create_operation_outcome_for_error = value
         return self

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,53 +35,60 @@ 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,
-            persistent_session=self._persistent_session,
-            use_persistent_session=self._use_persistent_session,
-            close_session_on_exit=self._close_session,
-        ) 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.info(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=self._fn_create_http_session or self.create_http_session,
+                    caller_managed_session=self._fn_create_http_session is not None,
+                    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:
         """
@@ -117,7 +130,8 @@ class FhirDeleteMixin(FhirClientProtocol):
             headers["Authorization"] = f"Bearer {access_token}"
 
         async with RetryableAioHttpClient(
-            fn_get_session=lambda: self.create_http_session(),
+            fn_get_session=self._fn_create_http_session or self.create_http_session,
+            caller_managed_session=self._fn_create_http_session is not None,
             refresh_token_func=self._refresh_token_function,
             retries=self._retry_count,
             exclude_status_codes_from_retry=self._exclude_status_codes_from_retry,
@@ -131,7 +145,7 @@ class FhirDeleteMixin(FhirClientProtocol):
         ) as client:
             response: RetryableAioHttpResponse = await client.delete(url=full_url, headers=headers)
             request_id = response.response_headers.get("X-Request-ID", None)
-            self._internal_logger.info(f"X-Request-ID={request_id}")
+            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}")