{"record":{"id":"34fe4acaaba217a1","repo":"pola-rs/polars","slug":"supplying-columns-param-value-is-mandatory-for-s","errorCode":null,"errorMessage":"supplying 'columns' param value is mandatory for sparklines","messagePattern":"supplying 'columns' param value is mandatory for sparklines","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/_write_utils.py","lineNumber":302,"sourceCode":"\n\ndef _xl_inject_sparklines(\n    ws: Worksheet,\n    df: DataFrame,\n    table_start: tuple[int, int],\n    col: str,\n    *,\n    include_header: bool,\n    params: Sequence[str] | dict[str, Any],\n) -> None:\n    \"\"\"Inject sparklines into (previously-created) empty table columns.\"\"\"\n    from xlsxwriter.utility import xl_rowcol_to_cell\n\n    m: dict[str, Any] = {}\n    data_cols = params.get(\"columns\") if isinstance(params, dict) else params\n    if not data_cols:\n        msg = \"supplying 'columns' param value is mandatory for sparklines\"\n        raise ValueError(msg)\n    elif not _adjacent_cols(df, data_cols, min_max=m):\n        msg = \"sparkline data range/cols must all be adjacent\"\n        raise RuntimeError(msg)\n\n    spk_row, spk_col, _, _ = _xl_column_range(\n        df, table_start, col, include_header=include_header, as_range=False\n    )\n    data_start_col = table_start[1] + m[\"min\"][\"idx\"]\n    data_end_col = table_start[1] + m[\"max\"][\"idx\"]\n\n    if not isinstance(params, dict):\n        options = {}\n    else:\n        # strip polars-specific params before passing to xlsxwriter\n        options = {\n            name: val\n            for name, val in params.items()\n            if name not in (\"columns\", \"insert_after\", \"insert_before\")","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/_write_utils.py#L284-L320","documentation":"ValueError raised by _inject_sparklines during write_excel when a sparkline definition supplies no data columns. Each sparkline entry must reference the frame columns it summarizes — either the dict form {'columns': [...]} or the bare list form ['a','b']. A missing 'columns' key, an empty list, or other falsy value leaves the sparkline with no data range.","triggerScenarios":"pl.write_excel(df, sparklines={'spark': {'insert_before': 'b'}}) (dict without 'columns'), or sparklines={'spark': []} (empty list). Only style/position options were provided.","commonSituations":"Using the dict form to set options like insert_before and forgetting the mandatory 'columns' entry; generating sparkline configs programmatically where the columns list comes back empty (bad key name, empty selection).","solutions":["Add the 'columns' entry: sparklines={'spark': {'columns': ['a', 'b', 'c'], 'insert_before': 'd'}}.","Or use the list shorthand when no other options are needed: sparklines={'spark': ['a', 'b', 'c']}.","Validate every sparkline config resolves to a non-empty column list before calling write_excel."],"exampleFix":"# before\npl.write_excel(df, sparklines={'spark': {'insert_before': 'd'}})\n\n# after\npl.write_excel(df, sparklines={'spark': {'columns': ['a', 'b', 'c'], 'insert_before': 'd'}})","handlingStrategy":"validation","validationCode":"for name, spec in sparklines.items():\n    cols = spec.get('columns') if isinstance(spec, dict) else spec\n    if not cols:\n        raise ValueError(f\"sparkline {name!r} needs a non-empty 'columns' value\")\npl.write_excel(df, sparklines=sparklines)","typeGuard":null,"tryCatchPattern":"try:\n    pl.write_excel(df, sparklines=sparklines)\nexcept ValueError as e:\n    if \"'columns' param value is mandatory\" in str(e):\n        fixed = {k: ({'columns': list(v), **{}} if not isinstance(v, dict) and v else v) for k, v in sparklines.items()}\n        pl.write_excel(df, sparklines=fixed)\n    else:\n        raise","preventionTips":["Every sparkline entry must carry its data columns — list form or a 'columns' key.","Validate generated sparkline configs against df.columns in one helper.","Prefer the list shorthand for minimal configs; it cannot omit columns."],"tags":["excel","spreadsheet","write-excel","sparklines","parameter-validation"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}