Core API Reference

qualink.core — Core classes, enums, and data structures.

from qualink.core import (
    Constraint, ConstraintMetadata, ConstraintResult, ConstraintStatus,
    Level,
    LoggingMixin, configure_logging, get_logger,
    CheckStatus, ValidationIssue, ValidationMetrics, ValidationReport, ValidationResult,
    ValidationSuite,
)

`qualink.core.constraint`

class ConstraintStatus(Enum)

Outcome of evaluating a single constraint.

Member	Value
`ConstraintStatus.SUCCESS`	`'success'`
`ConstraintStatus.FAILURE`	`'failure'`
`ConstraintStatus.SKIPPED`	`'skipped'`

@dataclass(frozen=True)

class ConstraintMetadata

Descriptive metadata attached to a constraint.

Field	Type	Default
`name`	`str`	required
`description`	`str`	`""`
`column`	`str	None`
`extra`	`dict[str, Any]`	`field(default_factory=dict)`

@dataclass

class ConstraintResult

The result produced after evaluating a constraint.

Field	Type	Default
`status`	`ConstraintStatus`	required
`metric`	`float	None`
`message`	`str`	`""`
`constraint_name`	`str`	`""`

Properties:

is_success: bool

class Constraint(LoggingMixin, ABC)

Abstract base class that every validation constraint must implement.

@abstractmethod async evaluate(ctx: SessionContext, table_name: str) → ConstraintResult

Evaluate this constraint against table_name registered in ctx.

@abstractmethod name() → str

Name of this constraint.

metadata() → ConstraintMetadata

Optional rich metadata.

`qualink.core.level`

class Level(IntEnum)

The severity level of a validation check.

Usage Guidelines

Error - critical data quality issues that prevent processing (missing required fields, PK violations, integrity violations).
Warning - issues that should be investigated but don't block processing (below-threshold quality, unusual patterns).
Info - informational metrics and observations (row counts, profiling results, performance benchmarks).

Member	Value
`Level.INFO`	`0`
`Level.WARNING`	`1`
`Level.ERROR`	`2`

as_str() → str

is_at_least(other: Level) → bool

`qualink.core.logging_mixin`

class LoggingMixin

Mixin that provides a per-class ``self.logger`` cached property.

logging.getLogger("qualink.constraints").setLevel(logging.DEBUG)

Properties:

logger: logging.Logger

configure_logging(level: int = logging.DEBUG, fmt: str = '%(asctime)s [%(levelname)s] %(name)s: %(message)s', datefmt: str = '%Y-%m-%d %H:%M:%S') → None

Attach a StreamHandler to the qualink root logger.

Safe to call more than once — handlers are not duplicated.

get_logger(name: str) → logging.Logger

Return a logger under the qualink namespace.

`qualink.core.result`

class CheckStatus

Outcome status after evaluating a check group.

@dataclass

class ValidationIssue

A single issue found during validation.

Field	Type	Default
`check_name`	`str`	required
`constraint_name`	`str`	required
`level`	`Level`	required
`message`	`str`	required
`metric`	`float	None`
`column`	`str	None`
`description`	`str`	`""`
`metadata_extra`	`dict[str, Any]`	`field(default_factory=dict)`

@dataclass

class ValidationMetrics

Aggregate metrics for a validation run.

Field	Type	Default
`total_checks`	`int`	`0`
`total_constraints`	`int`	`0`
`passed`	`int`	`0`
`failed`	`int`	`0`
`skipped`	`int`	`0`
`error_count`	`int`	`0`
`warning_count`	`int`	`0`
`execution_time_ms`	`int`	`0`
`custom_metrics`	`dict[str, float]`	`field(default_factory=dict)`

Properties:

pass_rate: float

success_rate() → float

@dataclass

class ValidationReport

Detailed report produced by a validation run.

Field	Type	Default
`suite_name`	`str`	required
`metrics`	`ValidationMetrics`	`field(default_factory=ValidationMetrics)`
`check_results`	`dict[str, list[ConstraintResult]]`	`field(default_factory=dict)`
`issues`	`list[ValidationIssue]`	`field(default_factory=list)`

add_issue(issue: ValidationIssue) → None

@dataclass

class ValidationResult

Top-level outcome of running a ValidationSuite.

Field	Type	Default
`success`	`bool`	required
`status`	`str`	required
`report`	`ValidationReport`	required

@classmethod success_result(metrics: ValidationMetrics, report: ValidationReport) → ValidationResult

@classmethod failure_result(report: ValidationReport) → ValidationResult

`qualink.core.suite`

class ValidationSuite(LoggingMixin)

Entry point for running data-quality checks.

ValidationSuite(name: str = "", description: str | None = None, ctx: SessionContext | None = None, table_name: str = 'data', checks: list[Check] | None = None, run_parallel: bool = False)

Param	Type	Default
`name`	`str`	`""`
`description`	`str	None`
`ctx`	`SessionContext	None`
`table_name`	`str`	`'data'`
`checks`	`list[Check]	None`
`run_parallel`	`bool`	`False`

@staticmethod builder(name: str) → ValidationSuiteBuilder

Create a builder for constructing a validation suite.

on_data(ctx: SessionContext, table_name: str) → ValidationSuiteBuilder

Begin a validation run against table_name in the DataFusion ctx.

async run() → ValidationResult

Execute a built suite with its stored configuration.

class ValidationSuiteBuilder(LoggingMixin)

Fluent builder that collects checks and runs them via DataFusion.

ValidationSuiteBuilder(name: str = 'ValidationRun')

Param	Type	Default
`name`	`str`	`'ValidationRun'`

description(desc: str) → ValidationSuiteBuilder

with_name(name: str) → ValidationSuiteBuilder

table_name(name: str) → ValidationSuiteBuilder

on_data(ctx: SessionContext, table_name: str) → ValidationSuiteBuilder

add_check(check: Check) → ValidationSuiteBuilder

add_checks(checks: list[Check]) → ValidationSuiteBuilder

run_parallel(enabled: bool = False) → ValidationSuiteBuilder

Enable or disable concurrent check execution (default: enabled).

async run() → ValidationResult

Execute all checks against the DataFusion context.

build() → ValidationSuite

Return a configured ValidationSuite (for deferred execution).