Skip to content

Pandas

rn_forge.data.pandas

The pandas adapter: row field extraction and Excel DataFrame conversion.

Requires the pandas extra.

ExcelAdapter

Adapters between workbook primitives and pandas DataFrames.

Use this layer when the calling code wants pandas for transformation but openpyxl for workbook-level formatting or templating.

Example::

data = ExcelAdapter.read_dataframe("orders.xlsx")
workbook = ExcelAdapter.from_dataframe(data)
ExcelUtils.write_workbook(workbook, "build/orders-copy.xlsx")

from_dataframe(data) staticmethod

Convert DataFrame data to an in-memory workbook.

load_dataframe(source) staticmethod

Load an in-memory workbook into a sheet-name keyed DataFrame mapping.

load_workbook(source) staticmethod

Load a workbook from an in-memory byte buffer.

read_dataframe(path) staticmethod

Read a workbook file into a sheet-name keyed DataFrame mapping.

read_workbook(path) staticmethod

Read a workbook from a filesystem path.

workbook_to_bytes(workbook) staticmethod

Serialise a workbook to an in-memory byte buffer.

write_workbook(workbook, path) staticmethod

Write a workbook to disk.

PandasUtils

Field extraction from pandas DataFrame and Series rows.

Requires pandas — install with rn-forge-data[pandas].

Example::

row = df.iloc[0]
customer_id = PandasUtils.get_string_field(row, "customer_id")
total = PandasUtils.get_decimal_field(row, "total", precision=2)

get_decimal_field(row, field_name, precision=2, required=True) staticmethod

Return field_name from row as a :class:~decimal.Decimal.

Parameters:

Name Type Description Default
row Series

A pandas.Series row.

required
field_name str

Column name to extract.

required
precision int

Number of decimal places to round to (default 2).

2
required bool

When True (default), raise :exc:~rn_forge.commons.AppException if the field is NaN / missing.

True

get_field(row, field_name, required=True) staticmethod

Return the value of field_name from row, or None if NaN.

Parameters:

Name Type Description Default
row Series

A pandas.Series (e.g. from df.itertuples() or df.iterrows()).

required
field_name str

Column name to extract.

required
required bool

When True (default), raise :exc:~rn_forge.commons.AppException if the field is NaN / missing.

True

get_string_field(row, field_name, required=True) staticmethod

Return field_name from row as a stripped string.

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()

is_na(value) staticmethod

Return whether value is considered missing by pandas.

Mirrors :func:pandas.isna but always returns a plain bool.

series_columns(row)

Return the index labels of row as a plain list.

series_value(row, field_name)

Return row[field_name], normalized to Any.

Series.__getitem__ has a wide overload set; pinning the result to Any here keeps the variation out of every call site.