Declarative Types¶

ColumnSpec accepts an optional type parameter that performs automatic coercion of the extracted values.

Available Types¶

Basic Usage¶

from pyreps import ColumnSpec, ReportSpec

spec = ReportSpec(
    output_format="csv",
    columns=[
        ColumnSpec(label="ID", source="id", type="int"),
        ColumnSpec(label="Active", source="active", type="bool"),
        ColumnSpec(label="Created at", source="created_at", type="date"),
    ],
)

Execution Order¶

The processing pipeline for each field follows this order:

graph LR
    A["Extract value"] --> B{"Exists?"}
    B -->|No| C["required → error"]
    B -->|No| D["default"]
    B -->|Yes| E["Coercion (type)"]
    D --> E
    E --> F["Formatter"]
    F --> G["Final value"]

1. Extraction via dot notation (source)
2. Validation of mandatory fields (required)
3. Default for missing fields
4. Coercion to the declared type (type)
5. Formatter receives the already typed value

ColumnSpec(
    label="Date",
    source="created_at",
    type="date",  # coerce string → date object
    formatter=lambda d: d.strftime("%d/%m/%Y"),  # receives date, not string
)

Accepted Date Formats¶

date¶

datetime¶

Bool — Accepted Values¶

Boolean coercion accepts strings in both pt-BR and en-US:

int and float values follow standard Python rules (0 → False, anything else → True).

Coercion Errors¶

If the conversion fails, a MappingError is raised. Since pyreps uses a streaming pipeline, errors are enriched with the row number and the pipeline stage where they occurred using Python 3.11+ add_note():

MappingError: cannot coerce field 'total' value 'abc' to type 'int'
failure at row 3 during stage: mapping