> ## Documentation Index
> Fetch the complete documentation index at: https://jetxl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Colors, indexing, and error behavior that apply across every option

A few rules apply everywhere in Jetxl. Read this once and the rest of the guides make more sense.

## Colors

Give a color as a hex string. Jetxl accepts several spellings and normalizes them for you.

| You write    | Jetxl uses | Notes                                     |
| ------------ | ---------- | ----------------------------------------- |
| `"FFFF0000"` | `FFFF0000` | Eight digits: alpha, red, green, blue     |
| `"FF0000"`   | `FFFF0000` | Six digits get an opaque `FF` alpha added |
| `"#FF0000"`  | `FFFF0000` | A leading `#` is stripped                 |
| `"red"`      | —          | Named colors don't work                   |
| `"F00"`      | —          | Three-digit shorthand doesn't work        |

You don't need to memorize alpha. Paste the six-digit hex from your design tool and Jetxl makes it opaque.

<Warning>
  When a color is unusable, Jetxl drops it and writes the file without it. You get a spreadsheet with default coloring rather than an error, so check your output if a color doesn't appear.
</Warning>

Chart text colors take the same forms. If you give eight digits, Jetxl discards the alpha, because the chart format Excel uses accepts only six.

## Rows and columns

Indexing isn't uniform, and this causes more mistakes than anything else in the API.

| Where            | Rows    | Columns |
| ---------------- | ------- | ------- |
| `cell_styles`    | 1-based | 0-based |
| `header_content` | 1-based | 0-based |
| Table range      | 1-based | 0-based |
| Chart data range | 1-based | 0-based |
| Chart position   | 0-based | 0-based |
| Image position   | 0-based | 0-based |
| `hidden_columns` | —       | 0-based |

Cell B2 in `cell_styles` is `{"row": 2, "col": 1}`. The row matches what Excel shows you; the column counts from zero, like a Python list.

<Tip>
  When a style lands one row off, check this table first. That's almost always the cause.
</Tip>

## Errors

Jetxl fails in three different ways depending on what's wrong. Errors raised from the Rust core arrive as `OSError`, not `ValueError`, so catch `OSError` when you need to handle them.

<AccordionGroup>
  <Accordion title="Raises immediately" icon="circle-exclamation">
    A number format code that's empty or all letters, such as `"accounting"`, raises an `OSError` naming the bad code. So does an unsupported column type, and exceeding Excel's grid limits.
  </Accordion>

  <Accordion title="Falls back silently" icon="circle-question">
    An unrecognized comparison `operator` becomes `greater_than` instead of raising. Check your spelling, because `greater_then` produces a working file with the wrong rule.
  </Accordion>

  <Accordion title="Drops the setting" icon="circle-minus">
    An unusable color is omitted. So is a conditional format with an unrecognized `rule_type`, and a table missing a required key such as `name`. The rest of the file writes normally, with no warning that the feature didn't apply.
  </Accordion>
</AccordionGroup>

<Tip>
  After adding a conditional format, table or chart, open the file once and confirm it's there. A dropped feature looks identical to one you forgot to add.
</Tip>

## Naming

Functions ending in `_arrow` read Arrow memory. Functions ending in `_to_bytes` return the workbook instead of writing a file. Plural names, such as `write_sheets_arrow`, take a list of sheets.