7 Interface Ambiguity and Type Degradation

[fderuiter]

Interface Ambiguity and Type Degradation
Attempting to support both synchronous and asynchronous execution through a unified entry point (ImednetSDK with an enable_async=True flag) destroys static type checking. If the sync and async clients share the same endpoint classes (e.g., sdk.records), modern IDEs and tools like mypy cannot accurately predict the return type. Developers will be constantly uncertain whether a method call returns a standard object or an unawaited coroutine.

Actionable Solution: Strictly bifurcate the synchronous and asynchronous API surfaces. Create entirely separate endpoint classes (e.g., AsyncRecordsEndpoint) and map them exclusively to the AsyncImednetSDK. A method must return either a data object or a coroutine, never a dynamic switch between the two based on a hidden initialization flag.

[fderuiter]

Phase 1: Establish Asynchronous Operations

Since we already defined synchronous operations (like GetOperation) using composition, we must mirror these with explicit asynchronous counterparts. These will rely on the AsyncClient (which uses httpx.AsyncClient).

Action: Create src/imednet/core/endpoint/operations/async_get.py (and similarly for async_list, async_create, etc.).

# src/imednet/core/endpoint/operations/async_get.py
from typing import Optional, Dict, Any, TypeVar, Generic
from imednet.utils.url import build_safe_path
from imednet.core.async_client import AsyncClient

T = TypeVar("T")

class AsyncGetOperation(Generic[T]):
    """Strictly asynchronous composition operation for fetching a single resource."""
    
    def __init__(self, client: AsyncClient, path_template: str, model: type[T]):
        self._client = client
        self._path_template = path_template
        self._model = model

    async def execute(self, resource_id: str, study_key: Optional[str] = None, params: Optional[Dict[str, Any]] = None) -> T:
        resolved_study_key = study_key # Fallback logic using contextvars goes here
        
        base_path = self._path_template.format(studyKey=resolved_study_key)
        endpoint_path = build_safe_path(base_path, resource_id)
        
        # Notice this is an asynchronous HTTP call mapped to an awaited response
        response = await self._client.get(endpoint_path, params=params)
        response.raise_for_status()
        
        return self._model.model_validate(response.json())

Phase 2: Bifurcate the Endpoint Namespaces

You must completely separate the endpoint classes. A single RecordsEndpoint cannot serve both masters.

Action: Update src/imednet/endpoints/records.py to define two explicitly named classes. (Alternatively, you can separate these into src/imednet/endpoints/sync/ and src/imednet/endpoints/async/ directories if the classes grow too large).

# src/imednet/endpoints/records.py
from imednet.core.client import Client
from imednet.core.async_client import AsyncClient
from imednet.core.endpoint.operations.get import GetOperation
from imednet.core.endpoint.operations.async_get import AsyncGetOperation
from imednet.models.records import RecordModel

# --- 1. STRICTLY SYNCHRONOUS ENDPOINT ---
class RecordsEndpoint:
    def __init__(self, client: Client):
        self._client = client
        self.get = GetOperation(
            client=client, 
            path_template="/studies/{studyKey}/records", 
            model=RecordModel
        ).execute

# --- 2. STRICTLY ASYNCHRONOUS ENDPOINT ---
class AsyncRecordsEndpoint:
    def __init__(self, client: AsyncClient):
        self._client = client
        self.get = AsyncGetOperation(
            client=client, 
            path_template="/studies/{studyKey}/records", 
            model=RecordModel
        ).execute

Phase 3: Hard-Wire the SDK Entrypoints

Now, we eradicate the enable_async flag from the base ImednetSDK. The synchronous SDK simply mounts the synchronous endpoints, and the asynchronous SDK mounts the asynchronous endpoints.

Action: Refactor src/imednet/sdk.py and src/imednet/async_sdk.py.

# src/imednet/sdk.py
from imednet.core.client import Client
from imednet.endpoints.records import RecordsEndpoint

class ImednetSDK:
    def __init__(self, api_key: str, security_key: str): # DELETE: enable_async=False
        # 1. Initialize strictly synchronous transport
        self._client = Client(api_url="...", api_key=api_key)
        
        # 2. Mount strictly synchronous endpoints
        self.records = RecordsEndpoint(self._client)
        # self.studies = StudiesEndpoint(self._client)
        # ...

# src/imednet/async_sdk.py
from imednet.core.async_client import AsyncClient
from imednet.endpoints.records import AsyncRecordsEndpoint

class AsyncImednetSDK:
    def __init__(self, api_key: str, security_key: str):
        # 1. Initialize strictly asynchronous transport
        self._client = AsyncClient(api_url="...", api_key=api_key)
        
        # 2. Mount strictly asynchronous endpoints
        self.records = AsyncRecordsEndpoint(self._client)
        # self.studies = AsyncStudiesEndpoint(self._client)
        # ...

---

Phase 4: Execution Checklist & Definition of Done (DoD)

To prove this refactor restores type degradation, you will rely heavily on static analysis rather than just unit testing.

Validation via Testing (mypy):
Create a dummy file tests/unit/test_type_signatures.py purely to run mypy against.

# tests/unit/test_type_signatures.py
from imednet.sdk import ImednetSDK
from imednet.async_sdk import AsyncImednetSDK
from imednet.models.records import RecordModel

def test_sync_types() -> None:
    sdk = ImednetSDK(api_key="mock", security_key="mock")
    # IDEs and mypy will instantly recognize `record` as RecordModel
    record: RecordModel = sdk.records.get(resource_id="123", study_key="STUDY")

async def test_async_types() -> None:
    async_sdk = AsyncImednetSDK(api_key="mock", security_key="mock")
    # IDEs and mypy will insist on `await` and recognize `async_record` as RecordModel
    async_record: RecordModel = await async_sdk.records.get(resource_id="123", study_key="STUDY")

Definition of Done (DoD):

• The enable_async parameter is completely purged from all SDK initialization signatures.
• The synchronous client uses GetOperation (and siblings), ensuring def execute().
• The asynchronous client uses AsyncGetOperation (and siblings), ensuring async def execute().
• Running poetry run mypy src/imednet tests/unit/test_type_signatures.py succeeds with zero type ambiguity errors (Any or Union[..., Coroutine]).
• No endpoint class dynamically inspects its internal transport to decide whether to return a standard object or a coroutine. Everything is hard-wired.