Columns¶

The data type of the column.

Overrides the column's name in the generated/validated DataFrame. Declaring columns as class attributes on a FrameSpec requires a valid Python identifier, which cannot contain spaces or other special characters -- col_name lets the attribute keep a clean Python name (unit_price) while the actual column is named whatever the data uses ("Unit Price"). Everything else that refers to this column by name -- ColRule, unique_together, tags lookups, validate() -- uses col_name, not the attribute name.

The name the column's seed is derived from, when it is not the column's own. Generation seeds each column from the frame seed and the column name, so renaming a column changes the values it produces; a column declared with seed_name="old" keeps producing the data it did as "old", its rules included. Nothing is promised across polspec versions. Two columns of one spec cannot share a seed name, nor may one name another column: they would draw identical values.

Whether the column allows null values.

The inclusive range of values allowed in the column, as a Bound or a 2-sequence. Only supported for numeric and temporal data types. Either endpoint may be None to leave that side unconstrained -- bounds=(0, None) for a non-negative column, bounds=(None, 0) for a non-positive one.

An open end means different things to the two consumers of this field, deliberately. validate() treats it as genuinely unconstrained and omits that half of the check. generate() cannot sample an unbounded range, so it falls back to the same default it would use with no bounds at all -- bounds=(0, None) on Int64 generates 0..1,000,000 while validating any value >= 0. This mirrors how bounds=None already behaves rather than adding a third rule.

Tag or tags classifying the column, for later selection.

Whether values in the column must be distinct. Generation draws the column without replacement; nulls are exempt. Cannot be combined with weights, a non-uniform distribution, or rules, none of which survive a draw without replacement.

Probability of a value being null. Must be between 0 and 1, and only has effect alongside nullable=True -- so that turning nullability off does not also require deleting the rate beside it. Declaring a rate of your own without nullable=True warns, since that reads as asking for nulls rather than as a leftover.

The inclusive range of string lengths, where that applies.

For a List column, the inclusive range of elements a value holds; generation defaults to 0..5. On a List or Array column every other field that describes a value -- bounds, choices, weights, format, pattern, string_length, distribution -- describes each element; nullable and null_probability describe the list itself, and generation never puts a null inside one. An Array takes its length from the dtype and refuses list_length.

For a Struct column, what is claimed about each field's values: a ColSpec per field, keyed by name. The dtype is the schema -- every field's name and type comes from it -- and fields is what is claimed about the values within it, so a struct of twenty fields where one needs bounds spells one field. A field the mapping omits is generated from its dtype alone.

A field is a value, not a column: unique, rules, validators, seed_name and col_name are refused on one, since each is a statement about a column among columns. Everything that describes a value is allowed -- nullable included, which says whether the field may be null inside a struct that is present -- and fields too, so a struct may nest to any depth. A finding about a field names it: point.lat.

A List or Array of a Struct takes fields too: it describes the element, as bounds and format already do.

The shape a String column's values take, by name: "uuid4", "email", "ipv4", "ipv6", "mac", "hostname", "iso_country" or "iso_currency". Generation fills the column from that format's own sampler and validation checks every value against it, so a column carrying format="email" is generated to satisfy its own spec. A format owns the column's whole domain: it cannot be combined with choices or string_length, and only a String column can carry one. What it promises is syntax -- an address that is well-formed, not one that is deliverable.

A regular expression every value of a String column must match, checked by validation only. Generation does not read it: a String column with a pattern is filled with ordinary random text, and the round trip that holds for every other field does not hold here -- the same boundary as validators. Prefer format for a shape polspec can generate; use pattern for a shape it cannot. Cannot be combined with format, which already is a pattern with a sampler. Polars regex syntax; a pattern that does not compile is refused at declaration.

The name of the probability distribution for the column's values (e.g. "uniform", "normal").

Parameters specific to the chosen distribution.

A finite set of allowed values. A dict maps each choice to its weight.

Weights associated with choices, biasing selection probabilities.

Rules (ColRule) that overwrite the column's values on the rows their condition matches.

A single-column business rule, or several: each either a pl.Expr boolean predicate (referencing only this column) or a Check (for a custom name, description or null handling). Unlike FrameSpec.__checks__, these travel with the column's own declaration.

The boolean condition each row must satisfy: a Polars expression, or a predicate built with polspec.col(). A predicate can be written to a YAML or Python spec file; a raw expression cannot.

A human-readable identifier for the check constraint (e.g. 'total_gte_subtotal'). If omitted, defaults to the string representation of the expression.

An optional description detailing the business logic or rationale for this check.

Whether rows evaluating to null in the check condition are considered valid (standard SQL CHECK constraint semantics). If False, null results are treated as failures.