Skip to content

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 LazyFrame comes back lazy.

required
spec TableSpec | FrameSpec class

What it should meet.

required
references mapping

Parent frames for spec's foreign keys, as validate() takes them.

None
options ValidationOptions

Every option at once; or pass them as keywords.

None

Raises:

Type Description
AssertionError

When df does not meet spec.

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

fn's arguments: a spec to generate, or a frame to pass.

required
output TableSpec | FrameSpec class

What fn must return.

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 --polspec-seed and the test's name; elsewhere 0.

None
references mapping

Parent frames for foreign keys into specs that are not inputs.

None
options ValidationOptions

How output is validated; or pass the options as keywords.

None

Returns:

Type Description
tuple

What fn returned, validated, and the inputs it was called with, by argument name -- for any assertion the spec cannot make.

Raises:

Type Description
AssertionError

When the result does not meet output.

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 spec's foreign keys, as generate() takes them.

None
fixed mapping

Columns pinned in every frame, as generate(fixed=) takes them. A pin of a sequence has to be as long as every frame, so give scalars unless min_rows and max_rows are equal.

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()