Skip to content

ColumnSpec & ReportSpec

Core contracts that define the structure and behavior of the report.

ColumnSpec

ColumnSpec(label: str, source: str, required: bool = False, default: Any = None, formatter: Formatter | None = None, type: ColumnType | None = None) dataclass

Configuration for a single report column.

Attributes:

Name Type Description
label str

The display name of the column (used as header).
source str

The key in the input record to fetch data from. Can use dot notation (e.g., 'user.name').
required bool

If True, raises MappingError if the source key is missing.
default Any

Default value to use if the source key is missing and not required.
formatter Formatter | None

Optional callable to transform the value after mapping and coercion.
type ColumnType | None

Optional type to coerce to. Allowed: 'str', 'int', 'float', 'bool', 'date', 'datetime'.

to_dict() -> dict[str, Any]

Convert ColumnSpec to a dictionary for serialization.

Source code in src/pyreps/contracts.py 
57
58
59
60
61
62
63
64
65
def to_dict(self) -> dict[str, Any]:
    """Convert ColumnSpec to a dictionary for serialization."""
    return {
        "label": self.label,
        "source": self.source,
        "required": self.required,
        "default": self.default,
        "type": self.type,
    }

ColumnType

ColumnType = Literal["str", "int", "float", "bool", "date", "datetime"]

See Declarative Types for coercion details.

ReportSpec

ReportSpec(columns: tuple[ColumnSpec, ...], output_format: OutputFormat = 'csv', encoding: str = 'utf-8', metadata: Mapping[str, Any] = dict()) dataclass

Complete specification for a report generation.

Attributes:

Name Type Description
columns tuple[ColumnSpec, ...]

Tuple of ColumnSpec defining the report schema.
output_format OutputFormat

Target format. Allowed: 'csv', 'xlsx', 'pdf'.
encoding str

Text encoding for the output file (default: 'utf-8').
metadata Mapping[str, Any]

Optional mapping for format-specific options (keys: 'csv', 'xlsx', 'pdf').

to_dict() -> dict[str, Any]

Convert ReportSpec to a dictionary for serialization.

Source code in src/pyreps/contracts.py 
105
106
107
108
109
110
111
112
def to_dict(self) -> dict[str, Any]:
    """Convert ReportSpec to a dictionary for serialization."""
    return {
        "output_format": self.output_format,
        "encoding": self.encoding,
        "columns": [col.to_dict() for col in self.columns],
        "metadata": dict(self.metadata),
    }

Auxiliary Types

OutputFormat = Literal["csv", "xlsx", "pdf"]
Record = Mapping[str, Any]
Formatter = Callable[[Any], Any]