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

helix_fhir_client_sdk/fhir_merge_resources_mixin.py

@@ -299,7 +299,8 @@ class FhirMergeResourcesMixin(FhirClientProtocol):
                 response_text: str | None = None
                 try:
                     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,
                         tracer_request_func=self._trace_request_function,
                         retries=self._retry_count,
@@ -515,7 +516,8 @@ class FhirMergeResourcesMixin(FhirClientProtocol):
                     response_text: str | None = None
                     try:
                         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,
                             tracer_request_func=self._trace_request_function,
                             retries=self._retry_count,
@@ -675,11 +677,12 @@ class FhirMergeResourcesMixin(FhirClientProtocol):
                     access_token: str | None = access_token_result.access_token
 
                     await AsyncFhirValidator.validate_fhir_resource(
-                        fn_get_session=lambda: self.create_http_session(),
+                        fn_get_session=self._fn_create_http_session or self.create_http_session,
                         json_data=resource.json(),
                         resource_name=cast(str | None, resource.get("resourceType")) or self._resource or "",
                         validation_server_url=self._validation_server_url,
                         access_token=access_token,
+                        caller_managed_session=self._fn_create_http_session is not None,
                     )
                     resource_json_list_clean.append(resource)
             except FhirValidationException as e:
@@ -700,11 +703,12 @@ class FhirMergeResourcesMixin(FhirClientProtocol):
                 try:
                     with resource.transaction():
                         await AsyncFhirValidator.validate_fhir_resource(
-                            fn_get_session=lambda: self.create_http_session(),
+                            fn_get_session=self._fn_create_http_session or self.create_http_session,
                             json_data=resource.json(),
                             resource_name=resource.get("resourceType") or self._resource or "",
                             validation_server_url=self._validation_server_url,
                             access_token=access_token1,
+                            caller_managed_session=self._fn_create_http_session is not None,
                         )
                         resource_json_list_clean.append(resource)
                 except FhirValidationException as e:

helix_fhir_client_sdk/fhir_patch_mixin.py

@@ -2,8 +2,12 @@ import json
 import time
 
 from furl import furl
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
 
 from helix_fhir_client_sdk.exceptions.fhir_sender_exception import FhirSenderException
+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_update_response import FhirUpdateResponse
 from helix_fhir_client_sdk.structures.get_access_token_result import (
@@ -18,6 +22,8 @@ from helix_fhir_client_sdk.utilities.retryable_aiohttp_response import (
     RetryableAioHttpResponse,
 )
 
+TRACER = trace.get_tracer(__name__)
+
 
 class FhirPatchMixin(FhirClientProtocol):
     async def send_patch_request_async(self, data: str) -> FhirUpdateResponse:
@@ -33,93 +39,103 @@ class FhirPatchMixin(FhirClientProtocol):
             raise ValueError("update should have only one id")
         if not self._resource:
             raise ValueError("update requires a FHIR resource type")
-        self._internal_logger.debug(
-            f"Calling patch method on {self._url} with client_id={self._client_id} and scopes={self._auth_scopes}"
-        )
-        full_uri: furl = furl(self._url)
-        full_uri /= self._resource
-        full_uri /= self._id
-        request_id: str | None = None
 
-        start_time: float = time.time()
+        with TRACER.start_as_current_span(FhirClientSdkOpenTelemetrySpanNames.PATCH) as span:
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.URL, self._url or "")
+            span.set_attribute(FhirClientSdkOpenTelemetryAttributeNames.RESOURCE, self._resource or "")
+            try:
+                self._internal_logger.debug(
+                    f"Calling patch method on {self._url} with client_id={self._client_id} and scopes={self._auth_scopes}"
+                )
+                full_uri: furl = furl(self._url)
+                full_uri /= self._resource
+                full_uri /= self._id
+                request_id: str | None = None
 
-        # Set up headers
-        headers = {"Content-Type": "application/json-patch+json"}
-        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}"
+                start_time: float = time.time()
 
-        response_text: str | None = None
-        response_status: int | None = None
+                # Set up headers
+                headers = {"Content-Type": "application/json-patch+json"}
+                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}"
 
-        try:
-            deserialized_data = json.loads(data)
-            # actually make the request
-            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:
-                response: RetryableAioHttpResponse = await client.patch(
-                    url=full_uri.url, json=deserialized_data, headers=headers
-                )
-                response_status = response.status
-                response_text = await response.get_text_async()
-                request_id = response.response_headers.get("X-Request-ID", None)
-                self._internal_logger.debug(f"X-Request-ID={request_id}")
+                response_text: str | None = None
+                response_status: int | None = None
 
-                if response_status == 200:
-                    if self._logger:
-                        self._logger.info(f"Successfully updated: {full_uri}")
-                elif response_status == 404:
-                    if self._logger:
-                        self._logger.info(f"Request resource was not found: {full_uri}")
+                try:
+                    deserialized_data = json.loads(data)
+                    # actually make the request
+                    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,
+                        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:
+                        response: RetryableAioHttpResponse = await client.patch(
+                            url=full_uri.url, json=deserialized_data, headers=headers
+                        )
+                        response_status = response.status
+                        response_text = await response.get_text_async()
+                        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 updated: {full_uri}")
+                        elif response_status == 404:
+                            if self._logger:
+                                self._logger.info(f"Request resource was not found: {full_uri}")
+                        else:
+                            # other HTTP errors
+                            self._internal_logger.info(f"PATCH response for {full_uri.url}: {response_status}")
+                except Exception as e:
+                    raise FhirSenderException(
+                        request_id=request_id,
+                        url=full_uri.url,
+                        headers=headers,
+                        json_data=data,
+                        response_text=response_text,
+                        response_status_code=response_status,
+                        exception=e,
+                        variables=FhirClientLogger.get_variables_to_log(vars(self)),
+                        message=f"Error: {e}",
+                        elapsed_time=time.time() - start_time,
+                    ) from e
+                # check if response is json
+                if response_text:
+                    try:
+                        responses = json.loads(response_text)
+                    except ValueError as e:
+                        responses = {"issue": str(e)}
                 else:
-                    # other HTTP errors
-                    self._internal_logger.info(f"PATCH response for {full_uri.url}: {response_status}")
-        except Exception as e:
-            raise FhirSenderException(
-                request_id=request_id,
-                url=full_uri.url,
-                headers=headers,
-                json_data=data,
-                response_text=response_text,
-                response_status_code=response_status,
-                exception=e,
-                variables=FhirClientLogger.get_variables_to_log(vars(self)),
-                message=f"Error: {e}",
-                elapsed_time=time.time() - start_time,
-            ) from e
-        # check if response is json
-        if response_text:
-            try:
-                responses = json.loads(response_text)
-            except ValueError as e:
-                responses = {"issue": str(e)}
-        else:
-            responses = {}
-        return FhirUpdateResponse(
-            request_id=request_id,
-            url=full_uri.tostr(),
-            responses=json.dumps(responses),
-            error=json.dumps(responses),
-            access_token=access_token,
-            status=response_status if response_status else 500,
-            resource_type=self._resource,
-        )
+                    responses = {}
+                return FhirUpdateResponse(
+                    request_id=request_id,
+                    url=full_uri.tostr(),
+                    responses=json.dumps(responses),
+                    error=json.dumps(responses),
+                    access_token=access_token,
+                    status=response_status if response_status else 500,
+                    resource_type=self._resource,
+                )
+            except Exception as e:
+                span.record_exception(e)
+                span.set_status(Status(StatusCode.ERROR, str(e)))
+                raise
 
     def send_patch_request(self, data: str) -> FhirUpdateResponse:
         """

helix_fhir_client_sdk/fhir_update_mixin.py

@@ -3,7 +3,11 @@ from collections.abc import AsyncGenerator
 from compressedfhir.fhir.fhir_resource import FhirResource
 from compressedfhir.fhir.fhir_resource_list import FhirResourceList
 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_update_response import FhirUpdateResponse
 from helix_fhir_client_sdk.structures.get_access_token_result import (
@@ -15,6 +19,8 @@ from helix_fhir_client_sdk.utilities.retryable_aiohttp_client import (
 )
 from helix_fhir_client_sdk.validators.async_fhir_validator import AsyncFhirValidator
 
+TRACER = trace.get_tracer(__name__)
+
 
 class FhirUpdateMixin(FhirClientProtocol):
     async def update_single_resource_async(self, *, resource: FhirResource) -> FhirUpdateResponse:
@@ -69,60 +75,71 @@ class FhirUpdateMixin(FhirClientProtocol):
             raise ValueError("update should have only one id")
         if not self._resource:
             raise ValueError("update requires a FHIR resource type")
-        full_uri: furl = furl(self._url)
-        full_uri /= self._resource
-        full_uri /= id_ or self._id
-        # set up headers
-        headers = {"Content-Type": "application/fhir+json"}
-        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}"
-
-        if self._validation_server_url:
-            await AsyncFhirValidator.validate_fhir_resource(
-                fn_get_session=lambda: self.create_http_session(),
-                json_data=json_data,
-                resource_name=self._resource,
-                validation_server_url=self._validation_server_url,
-                access_token=access_token,
-            )
-
-        # actually make the request
-        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:
-            response = await client.put(url=full_uri.url, data=json_data, 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 updated: {full_uri}")
-
-            return FhirUpdateResponse(
-                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.UPDATE) 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_ or self._id
+                # set up headers
+                headers = {"Content-Type": "application/fhir+json"}
+                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}"
+
+                if self._validation_server_url:
+                    await AsyncFhirValidator.validate_fhir_resource(
+                        fn_get_session=self._fn_create_http_session or self.create_http_session,
+                        json_data=json_data,
+                        resource_name=self._resource,
+                        validation_server_url=self._validation_server_url,
+                        access_token=access_token,
+                        caller_managed_session=self._fn_create_http_session is not None,
+                    )
+
+                # actually make the request
+                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,
+                    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:
+                    response = await client.put(url=full_uri.url, data=json_data, 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 updated: {full_uri}")
+
+                    return FhirUpdateResponse(
+                        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 update(self, json_data: str) -> FhirUpdateResponse:
         """

helix_fhir_client_sdk/open_telemetry/attribute_names.py

@@ -2,3 +2,6 @@ class FhirClientSdkOpenTelemetryAttributeNames:
     """Constants for OpenTelemetry attribute names used in the FHIR Client SDK."""
 
     URL: str = "fhir.client_sdk.url"
+    RESOURCE: str = "fhir.client_sdk.resource"
+    JSON_DATA_COUNT: str = "fhir.client_sdk.json_data.count"
+    BATCH_SIZE: str = "fhir.client_sdk.batch.size"

helix_fhir_client_sdk/open_telemetry/span_names.py

@@ -6,3 +6,7 @@ class FhirClientSdkOpenTelemetrySpanNames:
     GET_ACCESS_TOKEN: str = "fhir.client_sdk.access_token.get"
     HTTP_GET: str = "fhir.client_sdk.http.get"
     HANDLE_RESPONSE: str = "fhir.client_sdk.handle_response"
+    DELETE: str = "fhir.client_sdk.delete"
+    UPDATE: str = "fhir.client_sdk.update"
+    PATCH: str = "fhir.client_sdk.patch"
+    MERGE: str = "fhir.client_sdk.merge"

helix_fhir_client_sdk/queue/request_queue_mixin.py

@@ -119,7 +119,8 @@ class RequestQueueMixin(ABC, 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,
                 refresh_token_func=self._refresh_token_function,
                 tracer_request_func=self._trace_request_function,
                 retries=self._retry_count,
@@ -287,7 +288,8 @@ class RequestQueueMixin(ABC, 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,
                 refresh_token_func=self._refresh_token_function,
                 tracer_request_func=self._trace_request_function,
                 retries=self._retry_count,

helix_fhir_client_sdk/utilities/retryable_aiohttp_client.py

@@ -37,6 +37,7 @@ class RetryableAioHttpClient:
         refresh_token_func: RefreshTokenFunction | None,
         tracer_request_func: TraceRequestFunction | None,
         fn_get_session: Callable[[], ClientSession] | None = None,
+        caller_managed_session: bool = False,
         exclude_status_codes_from_retry: list[int] | None = None,
         use_data_streaming: bool | None,
         compress: bool | None = False,
@@ -47,8 +48,32 @@ class RetryableAioHttpClient:
         access_token_expiry_date: datetime | None,
     ) -> None:
         """
-        RetryableClient provides a way to make HTTP calls with automatic retry and automatic refreshing of access tokens
+        RetryableClient provides a way to make HTTP calls with automatic retry and automatic refreshing of access tokens.
 
+        Session Lifecycle Management:
+        - If caller_managed_session is False (default): The SDK manages the session lifecycle.
+          The session will be automatically closed when exiting the context manager.
+        - If caller_managed_session is True: The caller is responsible for managing the session lifecycle.
+          The SDK will NOT close the session - the caller must close it themselves.
+
+        :param retries: Number of retry attempts for failed requests
+        :param timeout_in_seconds: Timeout for HTTP requests
+        :param backoff_factor: Factor for exponential backoff between retries
+        :param retry_status_codes: HTTP status codes that trigger a retry
+        :param refresh_token_func: Function to refresh authentication tokens
+        :param tracer_request_func: Function to trace/log requests
+        :param fn_get_session: Optional callable that returns a ClientSession. If None, a basic
+                               ClientSession will be created internally.
+        :param caller_managed_session: If True, the caller is responsible for closing the session.
+                                       If False (default), the SDK will close the session on exit.
+        :param exclude_status_codes_from_retry: Status codes to exclude from retry logic
+        :param use_data_streaming: Whether to stream response data
+        :param compress: Whether to compress request data
+        :param send_data_as_chunked: Whether to use chunked transfer encoding
+        :param throw_exception_on_error: Whether to raise exceptions on HTTP errors
+        :param log_all_url_results: Whether to log all URL results
+        :param access_token: Access token for authentication
+        :param access_token_expiry_date: Expiry date of the access token
         """
         self.retries: int = retries
         self.timeout_in_seconds: float | None = timeout_in_seconds
@@ -58,6 +83,8 @@ class RetryableAioHttpClient:
         )
         self.refresh_token_func_async: RefreshTokenFunction | None = refresh_token_func
         self.trace_function_async: TraceRequestFunction | None = tracer_request_func
+        self._caller_managed_session: bool = caller_managed_session
+        # If no session factory provided, use a default one that creates a basic ClientSession
         self.fn_get_session: Callable[[], ClientSession] = (
             fn_get_session if fn_get_session is not None else lambda: ClientSession()
         )
@@ -81,7 +108,9 @@ class RetryableAioHttpClient:
         exc_val: BaseException | None,
         exc_tb: type[BaseException] | None | None,
     ) -> None:
-        if self.session is not None:
+        # Only close the session if SDK created it (fn_get_session was not provided)
+        # If the caller provided fn_get_session, they are responsible for closing the session
+        if not self._caller_managed_session and self.session is not None:
             await self.session.close()
 
     @staticmethod
@@ -115,7 +144,7 @@ class RetryableAioHttpClient:
             try:
                 if headers:
                     kwargs["headers"] = headers
-                # if there is no data then remove from kwargs so as not to confuse aiohttp
+                # if there is no data, then remove from kwargs so as not to confuse aiohttp
                 if "data" in kwargs and kwargs["data"] is None:
                     del kwargs["data"]
                 # compression and chunked can only be enabled if there is content sent
@@ -399,7 +428,7 @@ class RetryableAioHttpClient:
         if retry_after_text:
             # noinspection PyBroadException
             try:
-                if retry_after_text.isnumeric():  # it is number of seconds
+                if retry_after_text.isnumeric():  # it is a number of seconds
                     await asyncio.sleep(int(retry_after_text))
                 else:
                     wait_till: datetime = datetime.strptime(retry_after_text, "%a, %d %b %Y %H:%M:%S GMT")
@@ -413,7 +442,7 @@ class RetryableAioHttpClient:
                     if time_diff > 0:
                         await asyncio.sleep(time_diff)
             except Exception:
-                # if there was some exception parsing the Retry-After header, sleep for 60 seconds
+                # if there was some exception, parsing the Retry-After header, sleep for 60 seconds
                 await asyncio.sleep(60)
         else:
             await asyncio.sleep(60)

helix_fhir_client_sdk/validators/async_fhir_validator.py

@@ -23,6 +23,7 @@ class AsyncFhirValidator:
         resource_name: str,
         validation_server_url: str,
         access_token: str | None,
+        caller_managed_session: bool = False,
     ) -> None:
         """
         Calls the validation server url to validate the given resource
@@ -32,6 +33,7 @@ class AsyncFhirValidator:
         :param resource_name: name of resource
         :param validation_server_url: url to validation server
         :param access_token: access token to use
+        :param caller_managed_session: if True, the caller is responsible for closing the session
         """
         # check each resource against the validation server
         headers = {"Content-Type": "application/fhir+json"}
@@ -42,6 +44,7 @@ class AsyncFhirValidator:
         full_validation_uri /= "$validate"
         async with RetryableAioHttpClient(
             fn_get_session=fn_get_session,
+            caller_managed_session=caller_managed_session,
             use_data_streaming=False,
             access_token=access_token,
             access_token_expiry_date=None,

{helix_fhir_client_sdk-4.2.15.dist-info → helix_fhir_client_sdk-4.2.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: helix.fhir.client.sdk
-Version: 4.2.15
+Version: 4.2.17
 Summary: helix.fhir.client.sdk
 Home-page: https://github.com/icanbwell/helix.fhir.client.sdk
 Author: Imran Qureshi
@@ -111,9 +111,46 @@ response: Optional[FhirGetResponse] = await FhirGetResponse.from_async_generator
 ```
 
 # Data Streaming
-For FHIR servers that support data streaming (e.g., b.well FHIR server), you can just set the `use_data_streaming` parameter to stream the data as it i received.
+For FHIR servers that support data streaming (e.g., b.well FHIR server), you can just set the `use_data_streaming` parameter to stream the data as it is received.
 The data will be streamed in AsyncGenerators as described above.
 
+# Persistent Sessions (Connection Reuse)
+By default, the SDK creates a new HTTP session for each request. For better performance (~4× faster), 
+you can use persistent sessions to reuse connections across multiple requests.
+
+**Important**: When you provide a custom session factory using `use_http_session()`, YOU are responsible 
+for managing the session lifecycle, including closing it when done. The SDK will NOT automatically close 
+user-provided sessions.
+
+```python
+import aiohttp
+from helix_fhir_client_sdk.fhir_client import FhirClient
+
+# Create a persistent session for connection reuse
+session = aiohttp.ClientSession()
+
+try:
+    # Configure FhirClient to use persistent session
+    fhir_client = (
+        FhirClient()
+        .url("https://fhir.example.com")
+        .resource("Patient")
+        .use_http_session(lambda: session)  # User provides session factory
+    )
+    
+    # Multiple requests reuse the same connection (~4× performance boost)
+    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()
+```
+
+**Session Lifecycle Rules**:
+- **No custom factory** (default): SDK creates and closes the session automatically
+- **Custom factory provided**: User is responsible for closing the session
+
 # Storage Compression
 The FHIR client SDK supports two types of compression: