Python API reference

The importable surface, documented from the docstrings the 100 percent docstring gate enforces.

Excel (.xlsx / .xlsm) loader plugin for the pain001 ISO 20022 library.

The single public entry point is pain001_loader_xlsx.loader.XlsxLoader, discovered by pain001 via the pain001.loaders entry-point group declared in this package’s pyproject.toml.

Direct usage is supported but unnecessary for the common case:

pip install pain001 pain001-loader-xlsx
pain001 -t pain.001.001.03 -d payments.xlsx
class pain001_loader_xlsx.XlsxLoader[source]

Bases: object

Read flat-record payment data from an Excel .xlsx / .xlsm file.

Satisfies the structural pain001.plugins.AbstractLoader Protocol. Construction takes no arguments; the registry instantiates it once per process at first lookup.

Sheet selection: the first sheet wins. Cross-sheet payment batches are out of scope; users with that requirement should consolidate to a single sheet (or open an issue describing the layout).

meta = PluginMeta(name='xlsx', version='0.0.90', description='Read flat-record payment data from Excel .xlsx / .xlsm files.', api_version=(0, 54), source='built-in')
extensions = ('.xlsx', '.xlsm')
load(path)[source]

Read every data row from path and return them all at once.

Parameters:

path (str) – Filesystem path to the spreadsheet.

Returns:

A LoaderResult carrying one dict per data row (header-cell-value -> data-cell-value) and the original path as source hint.

Raises:

ValueError – When the workbook has no sheets, no header row, or when an IBAN column has been typed as a numeric cell.

Return type:

LoaderResult

load_streaming(path, chunk_size)[source]

Yield chunk_size-row LoaderResult chunks.

Parameters:
  • path (str) – Filesystem path to the spreadsheet.

  • chunk_size (int) – Maximum rows per yielded result.

Returns:

An iterable of LoaderResult; the final chunk may be smaller than chunk_size.

Return type:

Iterable[LoaderResult]

Excel (.xlsx / .xlsm) loader plugin for pain001.

Reads payment rows from the first sheet of an OOXML spreadsheet, treating row 1 as the header and rows 2..N as records. Cells are read with data_only=True so formulas evaluate to their cached last-saved value (the same value the user sees in Excel).

Implements the pain001.plugins.AbstractLoader Protocol without subclassing - structural typing means this plugin only needs the four declared attributes (meta, extensions, load, load_streaming) to satisfy the contract.

The loader is registered with pain001 via the pain001.loaders entry-point group in pyproject.toml; users get .xlsx dispatch automatically after pip install pain001-loader-xlsx.

IBAN handling

Excel’s General cell format silently strips leading zeros from numeric-looking strings - a known data-corruption mode in SAP / Oracle / Workday exports. To protect against this the loader refuses any row whose debtor_account_IBAN / creditor_account_IBAN / charge_account_IBAN cell is typed as a number (Excel General) and asks the user to re-type the column as Text first. Caught early, the warning saves the user from wiring an IBAN with a missing digit to a bank.

class pain001_loader_xlsx.loader.XlsxLoader[source]

Bases: object

Read flat-record payment data from an Excel .xlsx / .xlsm file.

Satisfies the structural pain001.plugins.AbstractLoader Protocol. Construction takes no arguments; the registry instantiates it once per process at first lookup.

Sheet selection: the first sheet wins. Cross-sheet payment batches are out of scope; users with that requirement should consolidate to a single sheet (or open an issue describing the layout).

meta = PluginMeta(name='xlsx', version='0.0.90', description='Read flat-record payment data from Excel .xlsx / .xlsm files.', api_version=(0, 54), source='built-in')
extensions = ('.xlsx', '.xlsm')
load(path)[source]

Read every data row from path and return them all at once.

Parameters:

path (str) – Filesystem path to the spreadsheet.

Returns:

A LoaderResult carrying one dict per data row (header-cell-value -> data-cell-value) and the original path as source hint.

Raises:

ValueError – When the workbook has no sheets, no header row, or when an IBAN column has been typed as a numeric cell.

Return type:

LoaderResult

load_streaming(path, chunk_size)[source]

Yield chunk_size-row LoaderResult chunks.

Parameters:
  • path (str) – Filesystem path to the spreadsheet.

  • chunk_size (int) – Maximum rows per yielded result.

Returns:

An iterable of LoaderResult; the final chunk may be smaller than chunk_size.

Return type:

Iterable[LoaderResult]

Turn Excel cell values into the strings a CSV would have carried.

pain001’s CSV loader is csv.DictReader, so every value it produces is a str. The generated XML is rendered from those strings. For an .xlsx file to produce byte-identical XML to the equivalent CSV — the acceptance criterion for this package — the values this loader emits have to be the same strings.

That is harder than it sounds, because Excel does not store what it displays. A cell showing 100.00 is the float 100.0; a cell showing 0023456 may be the int 23456 with the leading zeros gone for good. Recovering the displayed text needs the cell’s number_format, and where the information is genuinely destroyed this module’s job is to say so rather than guess.

The rules, in order:

  • str — used as Excel displays it: OOXML’s _xHHHH_ escapes (ECMA-376 Part 1, ST_Xstring) are decoded, so a cell holding a carriage return yields one rather than the six characters _x000D_. This is the good case, and the reason the documentation tells users to format columns as Text.

  • None — the empty string, matching how DictReader reports an empty field.

  • bool — "TRUE" / "FALSE", which is what Excel shows.

  • int / float — rendered through the cell’s number_format when that format pins the number of decimals (0.00 -> two), and otherwise with the shortest representation that round-trips.

  • datetime / date / time — rejected. See pain001_loader_xlsx.errors.

No quote is added in front of a value starting with =, +, - or @. pain001 writes ISO 20022 XML, which nothing evaluates, and since 0.0.74 its CSV loader keeps such values raw too (pain001 ADR-0008), so the same sheet renders the same XML either way.

pain001_loader_xlsx._normalise.decimals_in(number_format)[source]

Return the decimal places pinned by number_format, if any.

Parameters:

number_format (str | None) – The cell’s Excel number format, as openpyxl reports it. None for cells that carry none.

Returns:

The count of digits after the decimal point that the format pins, or None when the format leaves it open (General, text, or a format with no decimal section).

Return type:

int | None

Example

>>> decimals_in("0.00")
2
>>> decimals_in("#,##0.000")
3
>>> decimals_in("General") is None
True
pain001_loader_xlsx._normalise.decode_escapes(text)[source]

Decode OOXML _xHHHH_ escapes into the characters Excel shows.

openpyxl returns shared and inline strings with the escapes intact. An escaped surrogate pair decodes to the one character it encodes; a lone surrogate stays, for not_xml() to report.

Parameters:

text (str) – A string cell’s value as openpyxl read it.

Returns:

The text with every escape decoded.

Return type:

str

Example

>>> decode_escapes("Line1_x000D_\nLine2")
'Line1\r\nLine2'
>>> decode_escapes("_x005F_x0041_")
'_x0041_'
pain001_loader_xlsx._normalise.not_xml(text)[source]

Return the first character in text that XML 1.0 cannot carry.

Parameters:

text (str) – Decoded cell text.

Returns:

The offending character, or None when every character is allowed.

Return type:

str | None

Example

>>> not_xml("ACME\x07Ltd")
'\x07'
>>> not_xml("Line1\r\nLine2") is None
True
pain001_loader_xlsx._normalise.to_text(value, number_format)[source]

Convert one cell value to the string a CSV would have held.

Parameters:
  • value (Any) – The cell value openpyxl produced.

  • number_format (str | None) – The cell’s Excel number format, used to recover the displayed precision of numeric cells.

Returns:

The cell as text.

Return type:

str

Example

>>> to_text("DE89370400440532013000", "@")
'DE89370400440532013000'
>>> to_text(100.0, "0.00")
'100.00'
>>> to_text(None, None)
''
>>> to_text("+44 20 7946 0000", None)
'+44 20 7946 0000'