imednet.core package

The Client emits JSON formatted logs and can record OpenTelemetry

spans when a tracer is provided. See Logging and Tracing for details.

Submodules

imednet.core.client module

Core HTTP client for interacting with the iMednet REST API.

This module defines the Client class which handles: - Authentication headers (API key and security key). - Configuration of base URL, timeouts, and retry logic. - Making HTTP GET and POST requests. - Error mapping to custom errors. - Context-manager support for automatic cleanup.

class imednet.core.client.Client(api_key=None, security_key=None, base_url=None, timeout=30.0, retries=3, backoff_factor=1.0, tracer=None, retry_policy=None, auth=None)[source]

Bases: HTTPClientBase[Client, SyncRequestExecutor]

Core HTTP client for the iMednet API.

Parameters:

  • api_key (Optional[str]) –

  • security_key (Optional[str]) –

  • base_url (Optional[str]) –

  • timeout (Union[float, httpx.Timeout]) –

  • retries (int) –

  • backoff_factor (float) –

  • tracer (Optional[Tracer]) –

  • retry_policy (RetryPolicy | None) –

  • auth (Optional[AuthStrategy]) –

base_url

Base URL for API requests.

timeout

Default timeout for requests.

retries

Number of retry attempts for transient errors.

backoff_factor

Multiplier for exponential backoff.

close()[source]

Close the underlying HTTP client.

Return type:

None

get(path, params=None, **kwargs)[source]

Make a GET request.

Parameters:

  • path (str) – URL path or full URL.

  • params (Optional[Dict[str, Any]]) – Query parameters.

  • kwargs (Any) –

Return type:

Response

post(path, json=None, **kwargs)[source]

Make a POST request.

Parameters:

  • path (str) – URL path or full URL.

  • json (Optional[Any]) – JSON body for the request.

  • kwargs (Any) –

Return type:

Response

imednet.core.base_client module

class imednet.core.base_client.BaseClient(api_key=None, security_key=None, base_url=None, timeout=30.0, retries=3, backoff_factor=1.0, tracer=None, auth=None)[source]

Bases: object

Common initialization logic for HTTP clients.

Parameters:

  • api_key (Optional[str]) –

  • security_key (Optional[str]) –

  • base_url (Optional[str]) –

  • timeout (Union[float, httpx.Timeout]) –

  • retries (int) –

  • backoff_factor (float) –

  • tracer (Optional[Tracer]) –

  • auth (Optional[AuthStrategy]) –

imednet.core.context module

Logging and tracing

The imednet.core.client.Client can emit JSON formatted logs of each HTTP request when you configure logging:

from imednet.utils import configure_json_logging
from imednet.core.client import Client

configure_json_logging()
client = Client(api_key="...", security_key="...")

If opentelemetry is installed, pass a tracer instance or rely on the global tracer provider. Each request is executed within a span and works with opentelemetry-instrumentation-httpx for automatic context propagation of the HTTPX requests used by the SDK:

from opentelemetry import trace
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

HTTPXClientInstrumentor().instrument()
tracer = trace.get_tracer("my-app")
client = Client(api_key="...", security_key="...", tracer=tracer)

Manage mutable SDK context, like default study key.

class imednet.core.context.Context(default_study_key=None)[source]

Bases: object

Holds default values for SDK calls, such as default study key.

Parameters:

default_study_key (str | None) –

clear_default_study_key()[source]

Clear the default study key.

Return type:

None

default_study_key: Optional[str] = None

Default study key for API calls. :noindex:

set_default_study_key(study_key)[source]

Set the default study key to use for subsequent API calls.

Parameters:

study_key (str) – The study key string.

Return type:

None

imednet.core.paginator module

Pagination helpers for iterating through API responses.

class imednet.core.paginator.AsyncJsonListPaginator(client, path, params=None, page_size=100, page_param='page', size_param='size', data_key='data', metadata_key='metadata')[source]

Bases: AsyncPaginator

Asynchronous variant of JsonListPaginator.

Parameters:

  • client (ClientT) –

  • path (str) –

  • params (Dict[str, Any] | None) –

  • page_size (int) –

  • page_param (str) –

  • size_param (str) –

  • data_key (str) –

  • metadata_key (str) –

class imednet.core.paginator.AsyncPaginator(client, path, params=None, page_size=100, page_param='page', size_param='size', data_key='data', metadata_key='metadata')[source]

Bases: BasePaginator[AsyncRequestorProtocol]

Asynchronous variant of Paginator.

Parameters:

  • client (ClientT) –

  • path (str) –

  • params (Dict[str, Any] | None) –

  • page_size (int) –

  • page_param (str) –

  • size_param (str) –

  • data_key (str) –

  • metadata_key (str) –

class imednet.core.paginator.BasePaginator(client, path, params=None, page_size=100, page_param='page', size_param='size', data_key='data', metadata_key='metadata')[source]

Bases: Generic[ClientT]

Shared paginator implementation.

Parameters:

  • client (ClientT) –

  • path (str) –

  • params (Dict[str, Any] | None) –

  • page_size (int) –

  • page_param (str) –

  • size_param (str) –

  • data_key (str) –

  • metadata_key (str) –

class imednet.core.paginator.JsonListPaginator(client, path, params=None, page_size=100, page_param='page', size_param='size', data_key='data', metadata_key='metadata')[source]

Bases: Paginator

Paginator for endpoints returning a raw list.

Parameters:

  • client (ClientT) –

  • path (str) –

  • params (Dict[str, Any] | None) –

  • page_size (int) –

  • page_param (str) –

  • size_param (str) –

  • data_key (str) –

  • metadata_key (str) –

class imednet.core.paginator.Paginator(client, path, params=None, page_size=100, page_param='page', size_param='size', data_key='data', metadata_key='metadata')[source]

Bases: BasePaginator[RequestorProtocol]

Iterate synchronously over paginated API results.

Parameters:

  • client (ClientT) –

  • path (str) –

  • params (Dict[str, Any] | None) –

  • page_size (int) –

  • page_param (str) –

  • size_param (str) –

  • data_key (str) –

  • metadata_key (str) –

Retry policy

The RetryPolicy interface controls if failed requests should be retried. The SDK uses DefaultRetryPolicy which retries when httpx raises a RequestError. Provide your own policy to customize this behaviour.

from imednet.core.client import Client
from imednet.core.retry import RetryPolicy, RetryState
from imednet.errors import ServerError

class ServerRetry(RetryPolicy):
    def should_retry(self, state: RetryState) -> bool:
        return isinstance(state.exception, ServerError)

client = Client("A", "B", retry_policy=ServerRetry())