Skip to Content
Open Books for developers

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

  1. Download the sample CSV and put it beside your Python script.
  2. Set up Params with verified context for the input. Use Decimal("1000.00") to preserve the exact opening amount.
  3. Run the script from that directory. process(path, params) accepts a path or a path string and returns an openbooks.v1 dictionary 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

FieldType and defaultUse
currencystr or None, NoneThree-letter currency when the layout needs a supplied currency.
openingDecimal or None, NoneAuthoritative opening amount for layouts that accept it.
accountstr or None, NoneCaller-provided account identifier where supported.
allow_derived_openingbool, FalseAllow an opening balance derived from source rows where supported.
date_orderstr or None, Nonedmy or mdy for numeric dates. Omit to use layout inference and defaults.
ocrbool, TrueAllow OCR when the document front end needs it.
modelbool, FalseRequest 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.

View this page as Markdown