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 exceptions. - 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, log_level=20, tracer=None, retry_policy=None)[source]

Bases: HTTPClientBase

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) –
log_level (Union[int, str]) –
tracer (Optional[Tracer]) –
retry_policy (RetryPolicy | None) –

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.

HTTPX_CLIENT_CLS: alias of Client

IS_ASYNC: bool = False

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, log_level=20, tracer=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) –
log_level (Union[int, str]) –
tracer (Optional[Tracer]) –

DEFAULT_BASE_URL = 'https://edc.prod.imednetapi.com'

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="...", log_level="INFO")

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.exceptions module

Custom exceptions for the iMednet SDK.

Defines a hierarchy of exceptions corresponding to HTTP and validation errors.

exception imednet.core.exceptions.ApiError(response, status_code=None)[source]

Bases: ImednetError

Raised for generic API errors (non-2xx HTTP status codes).

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

status_code: HTTP status code returned by the API.

response: Parsed JSON or raw text of the error response.

exception imednet.core.exceptions.AuthenticationError(response, status_code=None)[source]

Bases: ApiError

Raised when authentication to the API fails (HTTP 401).

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.AuthorizationError(response, status_code=None)[source]

Bases: ApiError

Raised when access to the API is forbidden (HTTP 403).

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.BadRequestError(response, status_code=None)[source]

Bases: ValidationError

Raised for HTTP 400 bad requests.

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.ConflictError(response, status_code=None)[source]

Bases: ApiError

Raised for HTTP 409 conflict errors.

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.ForbiddenError(response, status_code=None)[source]

Bases: AuthorizationError

Raised for HTTP 403 forbidden errors.

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.ImednetError[source]

Bases: Exception

Base exception for all iMednet SDK errors.

exception imednet.core.exceptions.NotFoundError(response, status_code=None)[source]

Bases: ApiError

Raised when a requested resource is not found (HTTP 404).

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.RateLimitError(response, status_code=None)[source]

Bases: ApiError

Raised when the API rate limit is exceeded (HTTP 429).

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.RequestError[source]

Bases: ImednetError

Raised when a network request fails after retries.

exception imednet.core.exceptions.ServerError(response, status_code=None)[source]

Bases: ApiError

Raised when the API returns a server error (HTTP 5xx).

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.UnauthorizedError(response, status_code=None)[source]

Bases: AuthenticationError

Raised for HTTP 401 unauthorized errors.

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.UnknownVariableTypeError(response, status_code=None)[source]

Bases: ValidationError

Raised when an unrecognized variable type is encountered.

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

exception imednet.core.exceptions.ValidationError(response, status_code=None)[source]

Bases: ApiError

Raised when a request is malformed or validation fails (HTTP 400).

Parameters:

response (Any) –
status_code (int | None) –

Return type:

None

imednet.core.paginator module

Pagination helpers for iterating through API responses.

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

Asynchronous variant of Paginator.

Parameters:

client (Any) –
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: object

Shared paginator implementation.

Parameters:

client (Any) –
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

Iterate synchronously over paginated API results.

Parameters:

client (Any) –
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.core.exceptions import ServerError

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

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