invr 0.2.3

Declarative data validation engine using invariants executed on Polars DataFrames.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

use crate::infrastructure::polars::kind::PolarsKind;
use crate::invariant::Invariant;
use crate::scope::Scope;
use crate::violation::Violation;
use polars::frame::DataFrame;

/// Executes a direct (non-lazy) check ensuring that a specified column
/// exists in the provided `DataFrame`.
///
/// This check is evaluated immediately and does NOT participate in the
/// Polars lazy execution pipeline.
///
/// Scope:
/// - Requires `Scope::Column`
///
/// Behavior:
/// - Verifies that the invariant kind is `PolarsKind::ColumnExists`
/// - Extracts the column name from the invariant scope
/// - Calls `df.column(name)` to check existence
/// - Returns a `Violation` if the column is missing
///
/// A return value of `None` indicates that:
/// - The column exists, OR
/// - The invariant kind / scope does not match this check.
pub fn run_direct(df: &DataFrame, inv: &Invariant<PolarsKind>) -> Option<Violation> {
    if !matches!(inv.kind(), PolarsKind::ColumnExists) {
        return None;
    }

    let Scope::Column { name } = inv.scope() else {
        return None;
    };

    if df.column(name).is_err() {
        Some(Violation::new(
            inv.id().clone(),
            inv.severity(),
            inv.scope().clone(),
            format!("column '{name}' does not exist"),
        ))
    } else {
        None
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::domain::severity::Severity;
    use crate::scope::Scope;
    use polars::df;

    fn make_invariant_column_exists(column: &str) -> Invariant<PolarsKind> {
        Invariant::new(
            "col_exists_test".to_string().parse().unwrap(),
            PolarsKind::ColumnExists,
            Scope::Column {
                name: column.to_string(),
            },
        )
        .with_severity(Severity::Error)
    }

    #[test]
    fn test_column_exists_ok() {
        let df = df! {
            "a" => &[1, 2, 3],
            "b" => &[4, 5, 6]
        }
        .unwrap();

        let inv = make_invariant_column_exists("a");

        let result = run_direct(&df, &inv);

        assert!(result.is_none());
    }

    #[test]
    fn test_column_exists_missing() {
        let df = df! {
            "a" => &[1, 2, 3]
        }
        .unwrap();

        let inv = make_invariant_column_exists("missing");

        let result = run_direct(&df, &inv);

        assert!(result.is_some());

        let violation = result.unwrap();
        assert_eq!(violation.invariant_id().as_str(), "col_exists_test");
    }

    #[test]
    fn test_column_exists_wrong_kind_returns_none() {
        let df = df! {
            "a" => &[1, 2, 3]
        }
        .unwrap();

        let inv = Invariant::new(
            "other_kind_test".to_string().parse().unwrap(),
            PolarsKind::RowCountMin,
            Scope::Dataset,
        )
        .with_severity(Severity::Error);

        let result = run_direct(&df, &inv);

        assert!(result.is_none());
    }
}