helix.fhir.client.sdk 4.2.14__tar.gz → 4.2.16__tar.gz

{helix_fhir_client_sdk-4.2.14/helix.fhir.client.sdk.egg-info → helix_fhir_client_sdk-4.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: helix.fhir.client.sdk
-Version: 4.2.14
+Version: 4.2.16
 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:
 

{helix_fhir_client_sdk-4.2.14 → helix_fhir_client_sdk-4.2.16}/README.md

@@ -75,9 +75,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:
 

helix_fhir_client_sdk-4.2.16/VERSION

@@ -0,0 +1 @@
+4.2.16

{helix_fhir_client_sdk-4.2.14 → helix_fhir_client_sdk-4.2.16/helix.fhir.client.sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: helix.fhir.client.sdk
-Version: 4.2.14
+Version: 4.2.16
 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:
 

{helix_fhir_client_sdk-4.2.14 → helix_fhir_client_sdk-4.2.16}/helix.fhir.client.sdk.egg-info/SOURCES.txt

@@ -166,6 +166,7 @@ tests/async/test_async_real_fhir_server_get_patients.py
 tests/async/test_async_real_fhir_server_get_patients_error.py
 tests/async/test_benchmark_compress.py
 tests/async/test_benchmark_merge.py
+tests/async/test_retryable_client_session_management.py
 tests/async/fhir_server/__init__.py
 tests/async/fhir_server/test_async_real_fhir_server_get_graph_large.py
 tests/async/fhir_server/test_async_real_fhir_server_get_patients_large.py

{helix_fhir_client_sdk-4.2.14 → helix_fhir_client_sdk-4.2.16}/helix_fhir_client_sdk/fhir_auth_mixin.py

@@ -180,7 +180,6 @@ class FhirAuthMixin(FhirClientProtocol):
             access_token_expiry_date=self._access_token_expiry_date,
             refresh_token_func=self._refresh_token_function,
             tracer_request_func=self._trace_request_function,
-            persistent_session=self._persistent_session,
         ) as client:
             if self._auth_wellknown_url:
                 host_name: str = furl(self._auth_wellknown_url).host
@@ -282,7 +281,6 @@ class FhirAuthMixin(FhirClientProtocol):
             access_token_expiry_date=self._access_token_expiry_date,
             refresh_token_func=self._refresh_token_function,
             tracer_request_func=self._trace_request_function,
-            persistent_session=self._persistent_session,
         ) as client:
             response: RetryableAioHttpResponse = await client.post(url=auth_server_url, headers=headers, data=payload)
             # token = response.text.encode('utf8')

{helix_fhir_client_sdk-4.2.14 → helix_fhir_client_sdk-4.2.16}/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
@@ -155,6 +155,9 @@ class FhirClient(
 
         self._create_operation_outcome_for_error: bool | None = 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:
         """
         Set the action
@@ -477,13 +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.
+
+        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.
+
+        **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
 
-        :param session: persistent session
+            # 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._persistent_session = session
+        self._fn_create_http_session = fn_create_http_session
         return self
 
     # noinspection PyUnusedLocal
@@ -808,9 +846,16 @@ class FhirClient(
 
     def create_http_session(self) -> ClientSession:
         """
-        Creates an HTTP Session
+        Creates an HTTP Session.
 
+        If a custom session factory was set via use_http_session(), it will be used.
+        Otherwise, creates a default aiohttp ClientSession with standard configuration.
         """
+        # Use a custom session factory if provided
+        if self._fn_create_http_session is not None:
+            return self._fn_create_http_session()
+
+        # Default implementation
         trace_config = aiohttp.TraceConfig()
         # trace_config.on_request_start.append(on_request_start)
         if self._log_level == "DEBUG":
@@ -907,6 +952,7 @@ class FhirClient(
         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

{helix_fhir_client_sdk-4.2.14 → helix_fhir_client_sdk-4.2.16}/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,51 +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,
-            persistent_session=self._persistent_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.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:
         """
@@ -126,7 +140,6 @@ class FhirDeleteMixin(FhirClientProtocol):
             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,
         ) as client:
             response: RetryableAioHttpResponse = await client.delete(url=full_url, headers=headers)
             request_id = response.response_headers.get("X-Request-ID", None)