Metadata-Version: 2.4
Name: xlfmt
Version: 0.1.0
Summary: Turn an Excel number format and a value into the string Excel shows.
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/xlfmt/
Keywords: excel,xlsx,number-format,openpyxl
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# xlfmt

`m` in an Excel format means minutes when it sits next to hours or seconds, and months otherwise. Excel also thinks 1900 was a leap year. `xlfmt` turns a format code and a value into the string Excel shows, including fractions and `[Red]`.

```python
from openpyxl import load_workbook
from openpyxl.utils.datetime import CALENDAR_MAC_1904
from xlfmt import format_value

wb = load_workbook("report.xlsx")
ws = wb.active
cell = ws["B2"]

# cell.value         -> 0.4375
# cell.number_format -> "h:mm AM/PM"

text = format_value(cell.value, cell.number_format, date1904=wb.epoch == CALENDAR_MAC_1904)
# text -> "10:30 AM"
```

`text` is a `str`. When the matching section names a color, `text.color` is that color (`"Red"`, `"Color 3"`, …). Excel paints the color; it is not part of the text.

```python
text = format_value(-1234, '#,##0 ;[Red](#,##0)')
# text == "(1,234)"
# text.color == "Red"
```

Pass `date1904=True` for workbooks that use the 1904 date system. In the 1900 system, serial 60 is February 29, 1900.

## Install

```bash
pip install xlfmt
```

## Develop

```bash
uv sync
uv run pytest
```

`uv sync` installs the package plus the dev group (`pytest` and `openpyxl`). openpyxl is not a runtime dependency.
