Validation¶

validation ¶

Checks that confirm a table's declarations hold against its data.

Nothing here runs unless the caller asks, through :meth:tusk.Database.validate or add_table(validate=…).

CHECKS `module-attribute` ¶

CHECKS = {
    "non_null_primary_key": check_non_null_primary_key,
    "unique_primary_key": check_unique_primary_key,
    "datetime_row_creation_time": check_datetime_row_creation_time,
}

RELATIONSHIP_CHECKS `module-attribute` ¶

RELATIONSHIP_CHECKS = {
    "matching_key_dtypes": check_matching_key_dtypes,
    "overlapping_keys": check_overlapping_keys,
}

DATABASE_CHECKS `module-attribute` ¶

DATABASE_CHECKS = {
    "consistent_time_zones": check_consistent_time_zones
}

check_non_null_primary_key ¶

check_non_null_primary_key(frame, schema)

Confirm the declared primary key holds no null.

A table with no primary_key is skipped.

Parameters:

Name	Type	Description	Default
`frame`	`LazyFrame`	The table's lazy frame.	required
`schema`	`TableSchema`	The table's schema, naming the column to check.	required

Raises:

Type	Description
`ValidationError`	If the primary key column holds a null.

check_unique_primary_key ¶

check_unique_primary_key(frame, schema)

Confirm the declared primary key holds no repeated value.

A table with no primary_key is skipped. Nulls count as one distinct value, so repeated nulls fail and a single null passes.

Parameters:

Name	Type	Description	Default
`frame`	`LazyFrame`	The table's lazy frame.	required
`schema`	`TableSchema`	The table's schema, naming the column to check.	required

Raises:

Type	Description
`ValidationError`	If the primary key column holds a repeated value.

check_datetime_row_creation_time ¶

check_datetime_row_creation_time(frame, schema)

Confirm the declared row creation time is a Datetime, not a Date.

A table with no row_creation_time is skipped. Reads the schema only.

Parameters:

Name	Type	Description	Default
`frame`	`LazyFrame`	The table's lazy frame. Unused.	required
`schema`	`TableSchema`	The table's schema, naming the column to check.	required

Raises:

Type	Description
`ValidationError`	If the column is not a Datetime.

check_consistent_time_zones ¶

check_consistent_time_zones(database)

Confirm every Datetime column in the database agrees on time zone awareness.

Reads the schemas only. Time zone values may differ; only mixing aware with naive fails.

Parameters:

Name	Type	Description	Default
`database`	`Database`	The database to check.	required

Raises:

Type	Description
`ValidationError`	If some Datetime columns are tz-aware and others naive.

check_row_creation_time_awareness ¶

check_row_creation_time_awareness(database)

Report whether the database's row creation times are tz-aware.

Reads the schemas only. Anything but a Datetime carrying a time zone counts as naive. Time zone values may differ.

Parameters:

Name	Type	Description	Default
`database`	`Database`	The database to check.	required

Returns:

Name	Type	Description
`awareness`	`bool \| None`	`True` if every declared `row_creation_time` is tz-aware, `False` if every one is naive, `None` if no table declares one.

Raises:

Type	Description
`ValidationError`	If some row creation times are tz-aware and others naive.

check_cutoff_time_zone ¶

check_cutoff_time_zone(database, cutoff_time)

Confirm a cutoff matches the database's row creation times in tz awareness.

Reads the schemas only. A timeless database accepts any cutoff.

Parameters:

Name	Type	Description	Default
`database`	`Database`	The database the cutoff will filter.	required
`cutoff_time`	`datetime`	The cutoff.	required

Raises:

Type	Description
`ValidationError`	If the cutoff's time zone awareness differs from the row creation times', or if those disagree among themselves.

check_matching_key_dtypes ¶

check_matching_key_dtypes(database, relationship)

Confirm a foreign key has the same dtype as the primary key it points at.

Reads the schemas only. The dtypes must match exactly: pyarrow refuses to join Int64 to Int32, polars refuses Int64 to Float64 and refuses every String/Categorical/Enum crossing, and polars also refuses two Enums whose categories differ. Anything looser passes validation here and then fails the join.

Parameters:

Name	Type	Description	Default
`database`	`Database`	The database holding both tables.	required
`relationship`	`Relationship`	The link to check.	required

Raises:

Type	Description
`ValidationError`	If the two dtypes differ.

check_overlapping_keys ¶

check_overlapping_keys(database, relationship)

Confirm the foreign key matches at least one of the parent's primary keys.

Stops at the first match rather than proving every foreign key resolves. Orphan rows are ordinary in real data; no overlap at all means the link itself is wrong -- the wrong column, or two id spaces that never met.

Null foreign keys are ignored, and a child holding no non-null foreign key is skipped: it has nothing to match.

Parameters:

Name	Type	Description	Default
`database`	`Database`	The database holding both tables.	required
`relationship`	`Relationship`	The link to check.	required

Raises:

Type	Description
`ValidationError`	If no foreign key value appears in the parent.

validate_table ¶

validate_table(frame, schema, checks=True)

Run the selected table checks against one table.

Checks run in the order given; the first failure raises :class:~tusk.exceptions.ValidationError and stops the run. A name that is not in :data:CHECKS raises :class:ValueError.

Parameters:

Name	Type	Description	Default
`frame`	`LazyFrame`	The table's lazy frame.	required
`schema`	`TableSchema`	The table's schema.	required
`checks`	`bool \| str \| Iterable[str]`	`True` for every table check, `False` for none, a check name, or an iterable of check names.	`True`

validate_relationship ¶

validate_relationship(database, relationship, checks=True)

Run the selected relationship checks against one relationship.

Checks run in the order given; the first failure raises :class:~tusk.exceptions.ValidationError and stops the run. A name that is not in :data:RELATIONSHIP_CHECKS raises :class:ValueError.

Parameters:

Name	Type	Description	Default
`database`	`Database`	The database holding both tables.	required
`relationship`	`Relationship`	The link to check.	required
`checks`	`bool \| str \| Iterable[str]`	`True` for every relationship check, `False` for none, a check name, or an iterable of check names.	`True`

validate_database ¶

validate_database(
    database,
    *,
    database_checks=True,
    table_checks=True,
    relationship_checks=True,
)

Run the selected checks against a database.

Table checks run against every table in insertion order, then relationship checks against every relationship, then database-wide checks once. The first failure raises :class:~tusk.exceptions.ValidationError and stops the run. A name outside the registry its selector draws from raises :class:ValueError.

Parameters:

Name	Type	Description	Default
`database`	`Database`	The database to check.	required
`database_checks`	`bool \| str \| Iterable[str]`	Selects from :data:`DATABASE_CHECKS`.	`True`
`table_checks`	`bool \| str \| Iterable[str]`	Selects from :data:`CHECKS`.	`True`
`relationship_checks`	`bool \| str \| Iterable[str]`	Selects from :data:`RELATIONSHIP_CHECKS`.	`True`

Validation¶

validation ¶

CHECKS module-attribute ¶

RELATIONSHIP_CHECKS module-attribute ¶

DATABASE_CHECKS module-attribute ¶

check_non_null_primary_key ¶

check_unique_primary_key ¶

check_datetime_row_creation_time ¶

check_consistent_time_zones ¶

check_row_creation_time_awareness ¶

check_cutoff_time_zone ¶

check_matching_key_dtypes ¶

check_overlapping_keys ¶

validate_table ¶

validate_relationship ¶

validate_database ¶

CHECKS `module-attribute` ¶

RELATIONSHIP_CHECKS `module-attribute` ¶

DATABASE_CHECKS `module-attribute` ¶