Skip to content

Add excel.sheet formatting contract for WranglesXL - #1136

Open
ebhills wants to merge 3 commits into
mainfrom
codex/excel-sheet-formatting
Open

Add excel.sheet formatting contract for WranglesXL#1136
ebhills wants to merge 3 commits into
mainfrom
codex/excel-sheet-formatting

Conversation

@ebhills

@ebhills ebhills commented Aug 19, 2026

Copy link
Copy Markdown
Collaborator

Closes #1135

Paired client implementation: https://github.com/wrangleworks/WranglesXL/pull/1199
Related client issue: https://github.com/wrangleworks/WranglesXL/issues/1198

Summary

  • add a nested formatting.columns contract to excel.sheet
  • support align, number_format, bold, and checkbox
  • preserve the formatting payload for WranglesXL
  • validate formatting keys and values at runtime
  • keep differently formatted writes as ordered output segments

Behavior and compatibility

Recipes without formatting are unchanged. Matching batched writes still combine into one dataframe payload. A formatting change for the same sheet and cell starts a new payload segment so rows retain their original order and formatting intent.

This changes only excel.sheet; the file connector formatting behavior is unaffected.

Validation

  • .venv\\Scripts\\python.exe -m pytest tests\\connectors\\test_excel.py: 11 passed
  • git diff --check origin/main...HEAD: passed

Rollback

Revert commit 4ae4e107 to remove the new contract and restore the previous aggregation behavior.

@ebhills
ebhills requested a review from mborodii-prog August 19, 2026 13:56
@ebhills ebhills added this to the v1.20 milestone Aug 19, 2026
@mborodii-prog

Copy link
Copy Markdown
Contributor

@ebhills I did few changes:
In wrangles/connectors/excel.py:

Renamed number_format → num_format in _FORMATTING_OPTIONS, the validation branch, and its error message.
Renamed the number_format property → num_format in the connector's JSON schema block (_schema["write"]), with an updated description noting it matches the file connector's column_formats.num_format.
Added a doc comment above _FORMATTING_OPTIONS/_ALIGNMENTS explaining the syntax is intentionally aligned with _formatting.py, and updated the top-level formatting schema description to say the same.
In tests/connectors/test_excel.py:

Updated test_excel_sheet_write_preserves_column_formatting to use num_format instead of number_format.
Added test_excel_sheet_formatting_options_match_xlsxwriter_syntax, which:
asserts FORMATTING_OPTIONS is a subset of the real set* properties on xlsxwriter.format.Format (introspected via dir()), so a future option added to excel.sheet that isn't a real XlsxWriter property fails CI;
asserts _ALIGNMENTS - {"general"} is a subset of the values XlsxWriter's set_align() actually accepts (introspected via typing.get_args() on its Literal type annotation, since set_align() silently no-ops on unrecognized strings rather than raising).

@ebhills

ebhills commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator Author

@mborodii-prog - one more formatting option that we need in this first go is text wrap. Can you please add it too?

@mborodii-prog

Copy link
Copy Markdown
Contributor

@ebhills Added text_wrap as a new boolean formatting option, with tests passing

@mborodii-prog
mborodii-prog force-pushed the codex/excel-sheet-formatting branch from f027d6d to e732925 Compare August 21, 2026 08:01
@mborodii-prog

Copy link
Copy Markdown
Contributor

@ebhills this PR is tested in DEV, also opened aditional PR for XL to support num_format and text_wrap. To test it by own in DEv you can use image dev-1.20.0rc56 in execute-recipe-dev. As for me we're good to go agead with that PR:
recipe
'''

write:

  • excel.sheet:
    name: Results
    formatting:
    columns:
    Price:
    num_format: '$#,##0.00'
    align: center
    bold: true
    Discount:
    num_format: '0%'
    align: right
    Rating:
    num_format: '0.0'
    align: center
    In_Stock:
    align: right
    bold: true
    checkbox: true
    Description:
    text_wrap: true
    align: center
    Date_Added:
    num_format: 'yyyy-mm-dd'

'''

sample data:
image
output:
image

@mborodii-prog
mborodii-prog marked this pull request as ready for review August 21, 2026 13:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add an excel.sheet formatting contract for WranglesXL

2 participants