imednet.validation package

Validation utilities for iMednet data.

This package provides tools for validating record data against study schemas, including caching of variable metadata and data dictionary management.

class imednet.validation.AsyncSchemaCache

Bases: BaseSchemaCache[AsyncImednetFacade]

Asynchronous implementation of the schema cache.

__init__()

Initialize the asynchronous schema cache.

Return type:

None

class imednet.validation.AsyncSchemaValidator

Bases: BaseSchemaValidator[AsyncImednetFacade]

Validate record payloads using variable metadata from the API (Asynchronous).

__init__(sdk)

Initialize the asynchronous schema validator.

Parameters:

sdk (AsyncImednetFacade) –

Return type:

None

async refresh(study_key)

Populate the schema cache for study_key from the Variables endpoint.

This method never raises ValidationError; any API errors bubble up as ApiError.

Return type:

None

Parameters:

study_key (str) –

async validate_batch(study_key, records)

Validate a batch of record payloads asynchronously.

Return type:

None

Parameters:

• study_key (str) –

• records (list[dict[str, Any]]) –

async validate_record(study_key, record)

Validate a single record payload asynchronously.

Return type:

None

Parameters:

• study_key (str) –

• record (dict[str, Any]) –

class imednet.validation.BaseSchemaCache

Bases: Generic[_TClient]

Cache of variables by form key with optional async refresh.

__init__(is_async)

Initialize the schema cache.

Parameters:

is_async (bool) – Whether this cache is used in an asynchronous context.

Return type:

None

form_key_from_id(form_id)

Resolve a form key from a form ID.

Parameters:

form_id (int) – The form ID to look up.

Returns:

The form key if found, else None.

Return type:

Optional[str]

property forms: dict[str, dict[str, imednet.models.engine.Variable]]

Return cached variables grouped by form key.

populate(variables)

Populate the cache with the given variables.

Return type:

None

Parameters:

variables (Iterable[Variable]) –

refresh(forms, variables, study_key=None)

Refresh the cache, using the appropriate sync or async implementation.

Parameters:

• forms (FormsEndpoint | AsyncFormsEndpoint) – The forms endpoint (sync or async).

• variables (VariablesEndpoint | AsyncVariablesEndpoint) – The variables endpoint (sync or async).

• study_key (Optional[str]) – The study key to refresh variables for.

Returns:

An awaitable if async, else None.

Return type:

Any

variables_for_form(form_key)

Return the variables associated with the given form key.

Parameters:

form_key (str) – The form key to look up.

Returns:

A mapping of variable names to Variable objects.

Return type:

Dict[str, Variable]

class imednet.validation.BaseSchemaValidator

Bases: _ValidatorMixin, Generic[_TClient]

Base validator sharing logic between sync and async implementations.

class imednet.validation.DataDictionary

Bases: object

Container for data dictionary CSV content.

__init__(business_logic, choices, forms, questions)

Parameters:

• business_logic (list[dict[str, str]]) –

• choices (list[dict[str, str]]) –

• forms (list[dict[str, str]]) –

• questions (list[dict[str, str]]) –

Return type:

None

class imednet.validation.DataDictionaryLoader

Bases: object

Load data dictionary files from various sources.

classmethod from_directory(directory)

Load all required CSV files from directory.

Return type:

DataDictionary

Parameters:

directory (Path | str) –

classmethod from_files(*, business_logic, choices, forms, questions)

Load a data dictionary from individual CSV files.

Return type:

DataDictionary

Parameters:

• business_logic (Path | TextIO) –

• choices (Path | TextIO) –

• forms (Path | TextIO) –

• questions (Path | TextIO) –

classmethod from_zip(source)

Load a data dictionary from a ZIP archive containing the required CSVs.

Return type:

DataDictionary

Parameters:

source (Path | BinaryIO) –

class imednet.validation.SchemaCache

Bases: BaseSchemaCache[ImednetFacade]

Synchronous implementation of the schema cache.

__init__()

Initialize the synchronous schema cache.

Return type:

None

class imednet.validation.SchemaValidator

Bases: BaseSchemaValidator[ImednetFacade]

Validate record payloads using variable metadata from the API (Synchronous).

__init__(sdk, *, is_async=False)

Initialize the synchronous schema validator.

Parameters:

• sdk (ImednetFacade) –

• is_async (bool) –

Return type:

None

static __new__(cls, sdk, *args, **kwargs)

Create a new instance of the validator, handling deprecation of is_async.

Parameters:

• sdk (ImednetFacade) – The iMednet facade instance.

• *args (Any) – Positional arguments.

• **kwargs (Any) – Keyword arguments.

Returns:

A SchemaValidator or AsyncSchemaValidator instance.

Return type:

Any

refresh(study_key)

Populate the schema cache for study_key from the Variables endpoint.

This method never raises ValidationError; any API errors bubble up as ApiError.

Return type:

None

Parameters:

study_key (str) –

validate_batch(study_key, records)

Validate a batch of record payloads.

Return type:

None

Parameters:

• study_key (str) –

• records (list[dict[str, Any]]) –

validate_record(study_key, record)

Validate a single record payload.

Return type:

None

Parameters:

• study_key (str) –

• record (dict[str, Any]) –

imednet.validation.validate_record_data(schema, form_key, data)

Validate data for form_key using the provided schema cache.

Raises:

ValidationError – If the form key is not present in the schema or the data fails validation checks.

Return type:

None

Parameters:

• schema (BaseSchemaCache[Any]) –

• form_key (str) –

• data (dict[str, Any]) –

Submodules

imednet.validation.cache module

Caching and validation logic for iMednet variable schemas.

class imednet.validation.cache.AsyncSchemaCache

Bases: BaseSchemaCache[AsyncImednetFacade]

Asynchronous implementation of the schema cache.

__init__()

Initialize the asynchronous schema cache.

Return type:

None

class imednet.validation.cache.AsyncSchemaValidator

Bases: BaseSchemaValidator[AsyncImednetFacade]

Validate record payloads using variable metadata from the API (Asynchronous).

__init__(sdk)

Initialize the asynchronous schema validator.

Parameters:

sdk (AsyncImednetFacade) –

Return type:

None

async refresh(study_key)

Populate the schema cache for study_key from the Variables endpoint.

This method never raises ValidationError; any API errors bubble up as ApiError.

Return type:

None

Parameters:

study_key (str) –

async validate_batch(study_key, records)

Validate a batch of record payloads asynchronously.

Return type:

None

Parameters:

• study_key (str) –

• records (list[dict[str, Any]]) –

async validate_record(study_key, record)

Validate a single record payload asynchronously.

Return type:

None

Parameters:

• study_key (str) –

• record (dict[str, Any]) –

class imednet.validation.cache.BaseSchemaCache

Bases: Generic[_TClient]

Cache of variables by form key with optional async refresh.

__init__(is_async)

Initialize the schema cache.

Parameters:

is_async (bool) – Whether this cache is used in an asynchronous context.

Return type:

None

form_key_from_id(form_id)

Resolve a form key from a form ID.

Parameters:

form_id (int) – The form ID to look up.

Returns:

The form key if found, else None.

Return type:

Optional[str]

property forms: dict[str, dict[str, imednet.models.engine.Variable]]

Return cached variables grouped by form key.

populate(variables)

Populate the cache with the given variables.

Return type:

None

Parameters:

variables (Iterable[Variable]) –

refresh(forms, variables, study_key=None)

Refresh the cache, using the appropriate sync or async implementation.

Parameters:

• forms (FormsEndpoint | AsyncFormsEndpoint) – The forms endpoint (sync or async).

• variables (VariablesEndpoint | AsyncVariablesEndpoint) – The variables endpoint (sync or async).

• study_key (Optional[str]) – The study key to refresh variables for.

Returns:

An awaitable if async, else None.

Return type:

Any

variables_for_form(form_key)

Return the variables associated with the given form key.

Parameters:

form_key (str) – The form key to look up.

Returns:

A mapping of variable names to Variable objects.

Return type:

Dict[str, Variable]

class imednet.validation.cache.BaseSchemaValidator

Bases: _ValidatorMixin, Generic[_TClient]

Base validator sharing logic between sync and async implementations.

class imednet.validation.cache.SchemaCache

Bases: BaseSchemaCache[ImednetFacade]

Synchronous implementation of the schema cache.

__init__()

Initialize the synchronous schema cache.

Return type:

None

class imednet.validation.cache.SchemaValidator

Bases: BaseSchemaValidator[ImednetFacade]

Validate record payloads using variable metadata from the API (Synchronous).

__init__(sdk, *, is_async=False)

Initialize the synchronous schema validator.

Parameters:

• sdk (ImednetFacade) –

• is_async (bool) –

Return type:

None

static __new__(cls, sdk, *args, **kwargs)

Create a new instance of the validator, handling deprecation of is_async.

Parameters:

• sdk (ImednetFacade) – The iMednet facade instance.

• *args (Any) – Positional arguments.

• **kwargs (Any) – Keyword arguments.

Returns:

A SchemaValidator or AsyncSchemaValidator instance.

Return type:

Any

refresh(study_key)

Populate the schema cache for study_key from the Variables endpoint.

This method never raises ValidationError; any API errors bubble up as ApiError.

Return type:

None

Parameters:

study_key (str) –

validate_batch(study_key, records)

Validate a batch of record payloads.

Return type:

None

Parameters:

• study_key (str) –

• records (list[dict[str, Any]]) –

validate_record(study_key, record)

Validate a single record payload.

Return type:

None

Parameters:

• study_key (str) –

• record (dict[str, Any]) –

imednet.validation.cache.calculate_readiness_score(schema, form_key, data)

Calculate the schema readiness score for a record’s data.

Return type:

tuple[float, list[str]]

Returns:

A tuple of (score, list of validation failure reasons).

Parameters:

• schema (BaseSchemaCache[Any]) –

• form_key (str) –

• data (dict[str, Any]) –

imednet.validation.cache.validate_record_data(schema, form_key, data)

Validate data for form_key using the provided schema cache.

Raises:

ValidationError – If the form key is not present in the schema or the data fails validation checks.

Return type:

None

Parameters:

• schema (BaseSchemaCache[Any]) –

• form_key (str) –

• data (dict[str, Any]) –

imednet.validation.cache.validate_record_entry(schema, record)

Validate a single record entry against the schema.

Resolves the form key from “formKey”, “form_key”, “formId”, or “form_id”.

Parameters:

• schema (BaseSchemaCache[Any]) – The schema cache to use for validation.

• record (dict[str, Any]) – The record data dictionary.

Raises:

ValidationError – If the form key is not present in the schema or the data fails validation checks.

Return type:

None

imednet.validation.cache.validator(value)

Validate that the value is a string.

Parameters:

value (Any) – The value to validate.

Raises:

ValidationError – If the value is not a string.

Return type:

None

imednet.validation.data_dictionary module

Loading and container for iMednet Data Dictionary files.

class imednet.validation.data_dictionary.DataDictionary

Bases: object

Container for data dictionary CSV content.

__init__(business_logic, choices, forms, questions)

Parameters:

• business_logic (list[dict[str, str]]) –

• choices (list[dict[str, str]]) –

• forms (list[dict[str, str]]) –

• questions (list[dict[str, str]]) –

Return type:

None

class imednet.validation.data_dictionary.DataDictionaryLoader

Bases: object

Load data dictionary files from various sources.

classmethod from_directory(directory)

Load all required CSV files from directory.

Return type:

DataDictionary

Parameters:

directory (Path | str) –

classmethod from_files(*, business_logic, choices, forms, questions)

Load a data dictionary from individual CSV files.

Return type:

DataDictionary

Parameters:

• business_logic (Path | TextIO) –

• choices (Path | TextIO) –

• forms (Path | TextIO) –

• questions (Path | TextIO) –

classmethod from_zip(source)

Load a data dictionary from a ZIP archive containing the required CSVs.

Return type:

DataDictionary

Parameters:

source (Path | BinaryIO) –