# Python API

Use process, Params and the schema helpers in Python for bank statements, settlements, tax documents and workpapers.

Source: https://openbooks.lumeo.co.in/docs/python

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](/docs/installation) if you need to set up a virtual environment.

## Process a file [#process-a-file]

1. [Download the sample CSV](/examples/statement.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.

~~~python
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 [#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 [#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 [#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.

~~~python
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](/docs/output-contract) for the refusal schema and money, assertion and evidence fields. See [the architecture guide](/docs/architecture) for provider registration and extension points.
