Testing¶
The check at the end of a pipeline test, the whole test in one call, and
frames for a property test. The first two fail with an AssertionError,
so a test runner reports a failed test rather than an error — see
Testing pipelines.
assert_valid¶
assert_valid
¶
assert_valid(df: DataFrame, spec: SpecLike, *, references: References = None, options: ValidationOptions | None = None, **keywords: Unpack[ValidationKeywords]) -> DataFrame
assert_valid(df: LazyFrame, spec: SpecLike, *, references: References = None, options: ValidationOptions | None = None, **keywords: Unpack[ValidationKeywords]) -> LazyFrame
assert_valid(df: DataFrame | LazyFrame, spec: SpecLike, *, references: References = None, options: ValidationOptions | None = None, **keywords: Unpack[ValidationKeywords]) -> DataFrame | LazyFrame
Asserts that df meets spec, and returns the validated frame.
validate() as an assertion, for the end of a test: it takes the same
options, returns what validate() returns -- so it chains -- and on a
failure raises AssertionError, which every test runner reports as a
failed test rather than an error. The message names the spec, each
finding by its key, and up to ten of the rows that fail, as a table.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame | LazyFrame
|
What the code under test produced. A |
required |
spec
|
TableSpec | FrameSpec class
|
What it should meet. |
required |
references
|
mapping
|
Parent frames for |
None
|
options
|
ValidationOptions
|
Every option at once; or pass them as keywords. |
None
|
Raises:
| Type | Description |
|---|---|
AssertionError
|
When |
Examples:
>>> spec = TableSpec("Totals", {"total": ColSpec(pl.Float64, bounds=(0, 100))})
>>> assert_valid(pl.DataFrame({"total": [10.0, 20.0]}), spec).height
2
>>> try:
... assert_valid(pl.DataFrame({"total": [10.0, 250.0]}), spec)
... except AssertionError as failure:
... print(failure)
Totals: 1 finding(s) in 2 row(s)...
- total__bounds: Column 'total': found 1 value(s) out of bounds [0, 100] ...
First failing rows:
┌───────┬───────────────────┐
│ total ┆ __polspec_finding │
╞═══════╪═══════════════════╡
│ 250.0 ┆ total__bounds │
└───────┴───────────────────┘
check_pipeline¶
check_pipeline
¶
check_pipeline(fn: Callable[..., DataFrame | LazyFrame], inputs: Mapping[str, Any], output: SpecLike, *, n: int | Mapping[str, int] = 1000, seed: int | None = None, references: References = None, options: ValidationOptions | None = None, **keywords: Unpack[ValidationKeywords]) -> tuple[DataFrame | LazyFrame, dict[str, DataFrame | LazyFrame]]
Generates fn's inputs, runs it, and asserts its result meets output.
Each entry of inputs names one of fn's keyword arguments, and is a
spec -- generated for the call -- or a frame, passed as it is. The specs
are generated together, through a Registry, so a foreign key from one
input to another lines up without being wired by hand, and each from its
own seed derived from seed and its name. The result is checked with
assert_valid, its foreign keys into the inputs resolved against the
generated frames.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fn
|
callable
|
The pipeline stage, called with the inputs as keyword arguments. |
required |
inputs
|
mapping of str to spec or frame
|
|
required |
output
|
TableSpec | FrameSpec class
|
What |
required |
n
|
int or mapping of str to int
|
Rows to generate: one count for every spec, or one per argument. |
1,000
|
seed
|
int
|
Seeds the inputs, so the same call is the same test every run.
Under pytest, each test's own seed, from |
None
|
references
|
mapping
|
Parent frames for foreign keys into specs that are not inputs. |
None
|
options
|
ValidationOptions
|
How |
None
|
Returns:
| Type | Description |
|---|---|
tuple
|
What |
Raises:
| Type | Description |
|---|---|
AssertionError
|
When the result does not meet |
Examples:
>>> customers = TableSpec("Customers", {"id": ColSpec(pl.Int64, bounds=(1, 500), unique=True)})
>>> orders = TableSpec(
... "Orders",
... {"customer_id": ColSpec(pl.Int64, bounds=(1, 500)), "total": ColSpec(pl.Float64, bounds=(0, 100))},
... foreign_keys=[ForeignKey("customer_id", references="Customers", ref_columns="id")],
... )
>>> spend = TableSpec("Spend", {"customer_id": pl.Int64, "spend": ColSpec(pl.Float64, bounds=(0, None))})
>>> def summarise(customers, orders):
... return orders.group_by("customer_id").agg(spend=pl.col("total").sum())
>>> result, inputs = check_pipeline(
... summarise,
... inputs={"customers": customers, "orders": orders},
... output=spend,
... n={"customers": 100, "orders": 1_000},
... )
>>> inputs["orders"].height, set(result["customer_id"]) <= set(inputs["customers"]["id"])
(1000, True)
strategy¶
strategy
¶
strategy(spec: SpecLike, *, min_rows: int = 0, max_rows: int = 100, references: References = None, fixed: Mapping[str, Any] | None = None) -> SearchStrategy[DataFrame]
A Hypothesis strategy of frames spec accepts.
Each frame is generate(spec, n, seed=s) for a drawn row count n
between min_rows and max_rows and a drawn seed s, so it meets the
spec by construction and follows its distributions, rules and keys.
Hypothesis shrinks both numbers: a failing example is reported on the
fewest rows that fail. The values themselves come from the seed and do
not shrink one by one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spec
|
TableSpec | FrameSpec class
|
What every frame meets. |
required |
min_rows
|
int
|
The range of row counts drawn. |
0 and 100
|
max_rows
|
int
|
The range of row counts drawn. |
0 and 100
|
references
|
mapping
|
Parent frames for |
None
|
fixed
|
mapping
|
Columns pinned in every frame, as |
None
|
Raises:
| Type | Description |
|---|---|
ImportError
|
When Hypothesis is not installed. |
ValueError
|
For a row range that is negative or empty. |
Examples:
>>> from hypothesis import given, settings
>>> spec = TableSpec("Orders", {"total": ColSpec(pl.Float64, bounds=(0, 100))})
>>> @settings(max_examples=25, deadline=None)
... @given(orders=strategy(spec, max_rows=50))
... def test_totals_stay_in_range(orders):
... assert orders.height <= 50
... assert (orders["total"] <= 100).all()
>>> test_totals_stay_in_range()