Python API
Use process, Params and the schema helpers in Python for bank statements, settlements, tax documents and workpapers.
Use the Python API to process files inside a Python program. Install openbooks into the same Python 3.11+ environment that runs your application. The public API is available from openbooks and openbooks.core. See installation if you need to set up a virtual environment.
Process a file
- Download the sample CSV and put it beside your Python script.
- Set up
Paramswith verified context for the input. UseDecimal("1000.00")to preserve the exact opening amount. - Run the script from that directory.
process(path, params)accepts a path or a path string and returns anopenbooks.v1dictionary for a completed decision.
from decimal import Decimal
from pathlib import Path
from openbooks import EngineFault, Params, process
params = Params(
currency="INR",
opening=Decimal("1000.00"),
date_order="dmy",
)
try:
document = process(Path("statement.csv"), params, strict=True)
except EngineFault as error:
raise RuntimeError("Open Books could not run") from error
if document["status"] == "refused":
print(document["error"]["code"], document["error"]["message"])
else:
for row in document["data"]["transactions"]:
amount = Decimal(row["amount"]["amount"])
print(row["date"], row["direction"], amount, row["amount"]["currency"])The sample prints a debit of INR 100.00 and a credit of INR 50.00. Remove opening from Params and rerun to see the sample's PARSE_ERROR refusal.
Handle execution failures
Use strict=True when running jobs that need to distinguish an engine fault from a file that failed verification. An EngineFault can propagate for environmental problems. At the job boundary, handle file access errors as well. With the default policy, some unexpected failures return a refusal marked error.internal. Send those for engine diagnosis.
Params
| Field | Type and default | Use |
|---|---|---|
currency | str or None, None | Three-letter currency when the layout needs a supplied currency. |
opening | Decimal or None, None | Authoritative opening amount for layouts that accept it. |
account | str or None, None | Caller-provided account identifier where supported. |
allow_derived_opening | bool, False | Allow an opening balance derived from source rows where supported. |
date_order | str or None, None | dmy or mdy for numeric dates. Omit to use layout inference and defaults. |
ocr | bool, True | Allow OCR when the document front end needs it. |
model | bool, False | Request the optional typed-head check on PDFs or scans. |
Validate stored output
Check schema_version before reading a document received from another process. validate_output() checks a release's schema and additional rules for evidence, references, and assertions. Use load_schema("refusal") for the refusal variant.
from jsonschema import validate
from openbooks import SCHEMA_VERSION, load_schema, validate_output
if document["schema_version"] != SCHEMA_VERSION:
raise ValueError("Unsupported Open Books schema")
if document["status"] == "ok":
validate_output(document)
elif document["status"] == "refused":
validate(document, load_schema("refusal"))
else:
raise ValueError("Unknown Open Books document status")See the output contract for the refusal schema and money, assertion and evidence fields. See the architecture guide for provider registration and extension points.