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:
objectRead flat-record payment data from an Excel
.xlsx/.xlsmfile.Satisfies the structural
pain001.plugins.AbstractLoaderProtocol. 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
pathand return them all at once.- Parameters:
path (str) – Filesystem path to the spreadsheet.
- Returns:
A
LoaderResultcarrying 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
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:
objectRead flat-record payment data from an Excel
.xlsx/.xlsmfile.Satisfies the structural
pain001.plugins.AbstractLoaderProtocol. 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
pathand return them all at once.- Parameters:
path (str) – Filesystem path to the spreadsheet.
- Returns:
A
LoaderResultcarrying 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
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 howDictReaderreports an empty field.bool—"TRUE"/"FALSE", which is what Excel shows.int/float— rendered through the cell’snumber_formatwhen that format pins the number of decimals (0.00-> two), and otherwise with the shortest representation that round-trips.datetime/date/time— rejected. Seepain001_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.
Nonefor cells that carry none.- Returns:
The count of digits after the decimal point that the format pins, or
Nonewhen 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:
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
textthat XML 1.0 cannot carry.- Parameters:
text (str) – Decoded cell text.
- Returns:
The offending character, or
Nonewhen 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:
- Returns:
The cell as text.
- Return type:
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'