Excel and pandas¶
The package has one core and one adapter. rn_forge.data holds the Excel
helpers, which need only openpyxl and tablib. rn_forge.data.pandas holds
the pandas helpers and imports the core; the core never imports it, so importing
rn_forge.data loads no pandas. The pandas extra installs pandas for the
adapter, and the facade does not re-export the adapter.
Workbooks¶
ExcelUtils creates, reads and writes openpyxl workbooks and formats rows.
CellFormat carries the formatting to apply and WorkbookTemplate describes a
sheet's columns and default formats.
from openpyxl.styles import Font
from rn_forge.data import CellFormat, ExcelUtils
workbook = ExcelUtils.new_workbook()
sheet = workbook.active
sheet.append(["id", "total"])
sheet.append([1001, 42.5])
ExcelUtils.format_row(sheet[2], CellFormat(font=Font(bold=True)))
ExcelUtils.write_workbook(workbook, "build/orders.xlsx")
ExcelUtils.FORMAT_CURRENCY, FORMAT_DATE and FORMAT_PERCENTAGE are ready
made formats.
Exporting a dataset¶
write_xlsx writes a tablib.Dataset to .xlsx bytes with a number format per
column, which tablib's own xlsx writer does not offer. It iterates the dataset
directly into a write-only workbook. The caller holds the whole tablib.Dataset
in memory, and the whole workbook is returned as one bytes object; this is not
end-to-end streaming.
from datetime import date
import tablib
from rn_forge.data import write_xlsx
dataset = tablib.Dataset(headers=["name", "due", "total"])
dataset.append(["alice", date(2026, 1, 31), 42.5])
payload = write_xlsx(
dataset, column_formats={"due": "yyyy-mm-dd", "total": "#,##0.00"}
)
A format for a name that is not a header raises KeyError.
pandas¶
Use the adapter when the code wants pandas for transformation and openpyxl for
workbook-level formatting. ExcelAdapter converts between workbooks and
DataFrames, and PandasUtils reads typed fields from rows.
from rn_forge.data import ExcelUtils
from rn_forge.data.pandas import ExcelAdapter, PandasUtils
frames = ExcelAdapter.read_dataframe("orders.xlsx")
workbook = ExcelAdapter.from_dataframe(frames)
ExcelUtils.write_workbook(workbook, "build/orders-copy.xlsx")
row = frames["Sheet1"].iloc[0]
customer = PandasUtils.get_string_field(row, "customer_id")
total = PandasUtils.get_decimal_field(row, "total", precision=2)
PandasUtils.get_string_field converts values as follows:
| Value | required=False |
required=True |
|---|---|---|
None, float("nan"), pandas.NA, pandas.NaT |
"" |
Raises AppException("Field is required: <name>") |
0 |
"0" |
"0" |
0.0 |
"0.0" |
"0.0" |
False |
"False" |
"False" |
"" or whitespace-only string |
"" |
"" |
| Other non-missing value | str(value).strip() |
str(value).strip() |
get_decimal_field returns Decimal(0) for empty strings and optional missing
values, and Decimal("0.00") for numeric zero at the default precision. A
False cell raises decimal.InvalidOperation.
series_value and series_columns give typed access to a row's value and
labels, and SeriesRow is the row type.