Python API

read_spec is the main entry point: give it a workbook and a specification and it returns a plain Python dictionary. render_report adds the optional HTML layer, and json_default is the json encoder hook that lets date and time cells serialise.

Pass functions={...} to add your own functions to — or override — the built-in registry. Each receives the extracted value first, then any arguments from the pipeline:

from edjas import read_spec

data = read_spec("data.xlsx", "report.toml",
                 functions={"join": lambda v, sep: sep.join(v)})
# ... lets the specification use:  tags = '[Tags | join ", "]'

Rendering needs Jinja2, which arrives with the demo extra (pip install edjas[demo]); the core install never imports it.

The signatures and descriptions below are read from the live objects by introspection.

read_spec(spreadsheet, spec, functions=None)

Extract data from `spreadsheet` as directed by the TOML `spec` file.

`spreadsheet` may be an Excel workbook or an OpenDocument (`.ods`) one; the
same expressions work against either. `functions` optionally adds to (or
overrides) the built-in registry. The spreadsheet is opened read-only and never
modified.

render_report(spreadsheet, spec, template, templates_dir, functions=None, headings=None, **context)

Extract `spreadsheet` per `spec` and render `template` to an HTML string.

`templates_dir` is the directory Jinja2 loads templates from and `template` is
the entry template's filename within it. The extracted data dict is passed to the
template as `data`; any extra keyword arguments are merged into the render
context. `functions` is forwarded to `edjas.read_spec` to add or override
extraction functions. Autoescaping is on, so values from the spreadsheet are safe
to interpolate into HTML.

`headings` is an optional `{old: new}` mapping that renames headings (dict keys)
in the extracted data before rendering -- handy for shortening the very long column
titles some spreadsheets carry. It defaults to `None`, so headings are left
exactly as extracted and the report stays faithful to the workbook unless a mapping
is supplied.

json_default(obj)

`json` encoder hook: serialise date/datetime/time as ISO-8601.

A datetime at exactly midnight becomes a plain date, matching `isodate`.