API Reference

This page documents the public API for Transtractor.

Parser

The main entry point for parsing bank statement PDFs.

class transtractor.Parser[source]

Bases: object

A PDF bank statement parser.

This parser will be initialised with a set of default bank statement extraction configurations. When parsing a PDF, it will attempt to identify applicable configurations based on keywords extracted from the PDF. You can also load custom configurations from JSON files for additional statement formats.

Example

parser = Parser() parser.load(‘custom_config.json’) statement_data = parser.parse(‘statement.pdf’) print(statement_data) statement_data.to_csv(‘output.csv’)

__init__()[source]

Initialise the Parser with default database.

debug(pdf_file_path: str, output_file: str)[source]

Write a summary of the statement data and quality checks for each statement extraction configuration applied.

Parameters:

  • pdf_file_path – Path to the PDF file to be processed

  • output_file – Path to the output debug text file

Raises:

ParseError – If statement is not recognisable or not parsed correctly

debug_layout(layout_file_path: str, output_file: str)[source]

Write a summary of the statement data and quality checks for each statement extraction configuration applied.

Parameters:

  • layout_file_path – Path to the layout file to be processed

  • output_file – Path to the output debug text file

Raises:

ParseError – If statement is not recognisable or not parsed correctly

layout(pdf_file_path: str, output_file: str) → None[source]

Extract, write and return a text layout representation of the PDF page.

Parameters:

pdf_file_path – Path to the PDF file to be processed

load(json_file_path: str) → None[source]

Load a custom parsing configuration from a JSON file.

Configurations loaded via this method will be registered in the internal database and will overwrite any existing configuration with the same key.

Parameters:

json_file_path – Path to the JSON configuration file

Raises:

ConfigLoadError – Configuration file is invalid or cannot be loaded

See the docs for detailed instructions for creating custom configuration JSON files.

parse(pdf_file_path: str) → StatementData[source]

Parse the bank statement PDF and return a StatementData object.

Parameters:

pdf_file_path – Path to the PDF file to be processed

Returns:

StatementData object representing the parsed bank statement data

Raises:

ParseError – If statement is not recognisable or not parsed correctly

parse_layout(layout_file_path: str) → StatementData[source]

Parse the bank statement layout string and return a StatementData object.

Parameters:

layout_file_path – Path to the layout file to be processed

Returns:

StatementData object representing the parsed bank statement data

Raises:

ParseError – If statement is not recognisable or not parsed correctly

spec(pdf_file_path: str, output_file: str) → None[source]

Extract and write a JSON I/O spec representation of a PDF file.

Parameters:

  • pdf_file_path – Path to the PDF file to be processed

  • output_file – Path to the output JSON spec file

Raises:

ParseError – If statement is not recognisable or not parsed correctly

spec_layout(layout_file_path: str, output_file: str) → None[source]

Extract and write a JSON I/O spec representation of a layout text file.

Parameters:

  • layout_file_path – Path to the layout text file to be processed

  • output_file – Path to the output JSON spec file

Raises:

ParseError – If statement is not recognisable or not parsed correctly

test(pdf_dir: str, output_file: str = '', log_level: str = 'INFO') → None[source]

Try to parse all PDFs in a given directory and sub-directories using the current parser configuration database. Optionally outputs a CSV file summarising the test results.

Parameters:

  • pdf_dir – Path to the directory containing PDF files to be tested

  • output_file – Optional path to output CSV file for test results

  • log_level – Logging level for test output (e.g., “INFO”, “WARNING”)

Returns:

None

Note: Set log_level to “WARNING” or higher to suppress terminal output.

validate_spec(spec_file_path: str) → None[source]

Validate a JSON I/O spec file against the current parser configuration.

Parameters:

spec_file_path – Path to the JSON spec file to be validated

Raises:

SpecError – If the TextItems in the spec file cannot be parsed, or parsed differently to what is expected in the spec file’s StatementData.

StatementData

Represents the parsed bank statement data, including account information and transactions.

class transtractor.structs.statement_data.StatementData(key: str = '', filename: str = '', account_number: str = '', start_date: int = 0, opening_balance: float = 0.0, closing_balance: float = 0.0, transactions: list[~transtractor.structs.transaction.Transaction] = <factory>, benchmark: ~transtractor.structs.benchmark.Benchmark = <factory>)[source]

Bases: object

Class representing bank statement data.

__init__(key: str = '', filename: str = '', account_number: str = '', start_date: int = 0, opening_balance: float = 0.0, closing_balance: float = 0.0, transactions: list[~transtractor.structs.transaction.Transaction] = <factory>, benchmark: ~transtractor.structs.benchmark.Benchmark = <factory>) → None
account_number: str
benchmark: Benchmark
closing_balance: float
filename: str
key: str
opening_balance: float
start_date: int
to_csv(file_path: str) → None[source]

Export the statement data to a CSV file.

Parameters:

file_path (str) – Path to the output CSV file

to_pandas_dict() → dict[str, list][source]

Convert the statement data to a dictionary suitable for pandas DataFrame.

Returns:

Dictionary containing date, description, amount, and balance lists

Return type:

dict[str, list]

transactions: list[Transaction]

Transaction

Represents an individual transaction within a bank statement.

class transtractor.structs.transaction.Transaction(date: date | int, date_index: int, description: str, amount: float, balance: float, account_number: str = '')[source]

Bases: object

Class representing a bank transaction.

__init__(date: date | int, date_index: int, description: str, amount: float, balance: float, account_number: str = '')[source]

Initialize a Transaction.

Parameters:

  • date – Either a date object or milliseconds since epoch (int)

  • date_index – Transaction index for the day

  • description – Transaction description

  • amount – Transaction amount (will be rounded to 2 decimal places)

  • balance – Account balance (will be rounded to 2 decimal places)

  • account_number – Account number associated with the transaction

account_number: str
amount: float
balance: float
date: date
date_index: int
description: str