Classes related to the validation API

Validation Logic

class dicom_validator.validator.iod_validator.IODValidator(dataset: Dataset, dicom_info: DicomInfo, *, log_level: int = 20, suppress_vr_warnings: bool = False, error_handler: ValidationResultHandler | None = None, file_path: str = '')

Performs the actual IOD validation of a single DICOM dataset.

__init__(dataset: Dataset, dicom_info: DicomInfo, *, log_level: int = 20, suppress_vr_warnings: bool = False, error_handler: ValidationResultHandler | None = None, file_path: str = '') → None

Create an IODValidator instance.

Parameters:

• dataset (Dataset) – The dataset to be validated.

• dicom_info (dict) – The DICOM information as extracted from the standard.

• log_level (int) – The log level of the logger, if using the default error handler.

• suppress_vr_warnings (bool) – If True, skip the VR validation of DICOM tags.

• error_handler (ValidationResultHandler) – Handles errors found during validation. Defaults to a handler that logs all errors to the console.

validate() → ValidationResult

Validates current dataset. All errors are contained in the ValidationResult object after execution. By default, e.g. if no other handler has been set, all errors are logged to the console.

class dicom_validator.validator.dicom_file_validator.DicomFileValidator(dicom_info: DicomInfo, log_level: int = 20, force_read: bool = False, suppress_vr_warnings: bool = False, error_handler: ValidationResultHandler | None = None)

Validates a single DICOM file or all DICOM files in a directory.

__init__(dicom_info: DicomInfo, log_level: int = 20, force_read: bool = False, suppress_vr_warnings: bool = False, error_handler: ValidationResultHandler | None = None) → None

Initializes a DicomFileValidator object.

Parameters:

• dicom_info (DicomInfo) – DICOM information as read from the JSON files created from the standard

• log_level (int) – The log level to use with the default error handler

• force_read (bool) – If True, the DICOM file is tried to read even if it may not be valid

• suppress_vr_warnings (bool) – By default, values not valid for the given VR are reported, using the pydicom validation. If set to True, this validation is not performed.

• error_handler (ValidationResultHandler or None) – If set, this handler will be used to handle the validation result, otherwise the default handler is used that logs errors to the console.

validate(path: str | PathLike) → dict[str, ValidationResult]

Validate a single DICOM file or all files under a directory.

Parameters:

path (str | os.PathLike) – Path to a DICOM file or a directory containing DICOM files.

Returns:

A mapping from file path to its validation result.

Return type:

dict[str, ValidationResult]

validate_dir(dir_path: str) → dict[str, ValidationResult]

Validate all DICOM files contained in a directory tree.

Parameters:

dir_path (str) – Path to a directory that will be traversed recursively.

Returns:

A mapping from file path to its validation result for all files found.

Return type:

dict[str, ValidationResult]

validate_file(file_path: str) → dict[str, ValidationResult]

Validate a single DICOM file.

Parameters:

file_path (str) – Path to a DICOM file.

Returns:

A mapping containing exactly one entry for the given file.

Return type:

dict[str, ValidationResult]

Validation result

class dicom_validator.validator.validation_result.DicomTag(tag: int, parents: list[int] | None = None)

Represents a DICOM tag together with parent sequences, if any.

class dicom_validator.validator.validation_result.ErrorCode(*values)

Defines the kind of error found for a DICOM tag in a module.

class dicom_validator.validator.validation_result.ErrorScope(*values)

Defines the scope of an error found for a DICOM tag in a module. Some errors are specific to functional groups while having the same error code as errors unrelated to functional groups.

class dicom_validator.validator.validation_result.Status(*values)

The result state after validation.

class dicom_validator.validator.validation_result.TagError(type: TagType = TagType.Undefined, code: ErrorCode = ErrorCode.NoError, scope: ErrorScope = ErrorScope.General, context: dict | None = None)

Represents error found for a specific DICOM tag.

class dicom_validator.validator.validation_result.TagType(*values)

The DICOM tag type used in a specific module.

class dicom_validator.validator.validation_result.ValidationResult(sop_class_uid: str = '', file_path: str = '', status: Status = Status.Passed, errors: int = 0, module_errors: dict[str, dict[DicomTag, TagError]] | None = None)

The validation result for a specific DICOM dataset.

Error handling

class dicom_validator.validator.error_handler.LoggingResultHandler(dicom_info: DicomInfo, logger: Logger)

Handles the result of the validation of a single DICOM file by logging all errors.

handle_failed_validation_start(result: ValidationResult) → None

Placeholder method. Called in case the validation could not be started. Only the error code is set in the result. The validation is aborted after this call.

handle_module_errors_start(module_name: str, tag_errors: dict[DicomTag, TagError]) → None

Placeholder method. Called before the errors for a single module are handled.

handle_tag_error(tag_id: DicomTag, error: TagError) → None

Placeholder method. Called to handle a single tag error. The actual error handling (logging, recording) shall be implemented here.

handle_tag_parents_start(parents: list[BaseTag]) → None

Placeholder method. Called to handle parent sequence tags. Is called once for one or more tag errors with the same parent sequences.

handle_validation_result_end(validation_result: ValidationResult) → None

Placeholder method. Called after the validation result have been handled.

handle_validation_result_start(validation_result: ValidationResult) → None

Placeholder method. Called after the validation result is available and before the result handling starts.

handle_validation_start(result: ValidationResult) → None

Placeholder method. Called before the validation has started. Only the SOP Class UID is set at this point.

class dicom_validator.validator.error_handler.ValidationResultHandler(*args, **kwargs)

Protocol to be implemented by any validation result handler passed to the IODValidator.

abstractmethod handle_validation_result(result: ValidationResult)

Called after the validation has finished. All found errors are recorded in the validation result.

abstractmethod handle_validation_start(result: ValidationResult)

Called before the validation has started. Only the SOP Class UID is set at this point.

class dicom_validator.validator.error_handler.ValidationResultHandlerBase(*args, **kwargs)

Provides a skeleton implementation for a result handler. An easy way to implement another handler is to derive from this class and implement the actual handling in some or all placeholder methods.

handle_failed_validation_start(result: ValidationResult) → None

Placeholder method. Called in case the validation could not be started. Only the error code is set in the result. The validation is aborted after this call.

handle_module_errors(module_name: str, tag_errors: dict[DicomTag, TagError]) → None

Called to handle the errors in a single module. Only calls other methods that may contain the actual handling.

handle_module_errors_end(module_name: str, tag_errors: dict[DicomTag, TagError]) → None

Placeholder method. Called after the errors for a single module are handled.

handle_module_errors_start(module_name: str, tag_errors: dict[DicomTag, TagError]) → None

Placeholder method. Called before the errors for a single module are handled.

handle_tag_error(tag_id: DicomTag, error: TagError) → None

Placeholder method. Called to handle a single tag error. The actual error handling (logging, recording) shall be implemented here.

handle_tag_parents_end(parents: list[BaseTag]) → None

Placeholder method. Called to handle parent sequence tags. Is called once after one or more tag errors with the same parent sequences appeared.

handle_tag_parents_start(parents: list[BaseTag]) → None

Placeholder method. Called to handle parent sequence tags. Is called once for one or more tag errors with the same parent sequences.

handle_validation_result(result: ValidationResult) → None

Called after the validation has finished. All found errors are recorded in the validation result. Only calls other methods that may contain the actual handling.

handle_validation_result_end(validation_result: ValidationResult) → None

Placeholder method. Called after the validation result have been handled.

handle_validation_result_start(validation_result: ValidationResult) → None

Placeholder method. Called after the validation result is available and before the result handling starts.

handle_validation_start(result: ValidationResult) → None

Placeholder method. Called before the validation has started. Only the SOP Class UID is set at this point.