FIX: Indentation, ruff lint warnings and docs

AGENTS.md

@@ -100,10 +100,11 @@ Private constants use a leading underscore: `_ALLOWED_TABLES`. Public shared con
 ### Classes — use `__slots__` on every class. Regular classes declare a tuple; dataclasses use `slots=True`. Subclasses declare only their own additional slots.
 
 ```python
-@dataclass(frozen=True, slots=True)   # immutable value objects
+@dataclass(frozen=True, slots=True)  # immutable value objects
 class AccountType:
     account_type: str
 
+
 @dataclass(frozen=False, slots=True)  # mutable state holders
 class Account:
     account: str
@@ -114,7 +115,7 @@ class Account:
 
 ```python
 class Housekeeping:
-    FK_RELATIONSHIPS = [...]          # class variable, not in __slots__
+    FK_RELATIONSHIPS = [...]  # class variable, not in __slots__
     _ALLOWED_TABLES: frozenset[str] = frozenset([...])
 ```
 
@@ -135,6 +136,7 @@ Use `frozenset[str]` for any identifier or name whitelist used in membership tes
 def __enter__(self) -> "TestHarness":
     return self.setup()
 
+
 def __exit__(self, *args: object) -> None:
     self.teardown()
 ```

docs/guides/exports.md

@@ -238,7 +238,7 @@ import bank_statement_parser as bsp
 bsp.db.export_csv()
 
 # Export multi star-schema tables to Excel
-bsp.db.export_excel(type='multi')
+bsp.db.export_excel(type="multi")
 
 # Export JSON
 bsp.db.export_json()
@@ -248,8 +248,9 @@ bsp.db.export_reporting_data()
 
 # Export to a custom directory
 from pathlib import Path
-bsp.db.export_csv(folder=Path('~/exports'))
-bsp.db.export_excel(path=Path('~/exports/report.xlsx'))
+
+bsp.db.export_csv(folder=Path("~/exports"))
+bsp.db.export_excel(path=Path("~/exports/report.xlsx"))
 ```
 
 ## Report Classes

docs/reference/python-api.md

@@ -9,143 +9,117 @@ All public symbols are available from the top-level package:
 import bank_statement_parser as bsp
 ```
 
-## Meta
+## Ungrouped
 
-### `bsp.__app_name__`
-
-*constant*
-
-### `bsp.__version__`
-
-*constant*
-
-## Namespaced report backend
-
-### `bsp.db`
-
-*module* — `bank_statement_parser.modules.reports_db`
-
-SQLite-backed report classes and export helpers.
-
-## Statement processing
+### `bsp.Failure`
 
-### `bsp.Statement`
+*class* — `bank_statement_parser.modules.data`
 
-*class* — `bank_statement_parser.modules.statements`
+Payload for a PDF result where no usable statement data was produced.
 
-Represents a single bank statement PDF with data extraction and validation.
+### `bsp.ForexApiConfig`
 
-### `bsp.StatementBatch`
+*class* — `bank_statement_parser.modules.data`
 
-*class* — `bank_statement_parser.modules.statements`
+Configuration for the forex exchange-rate fetching service.
 
-Handles batch processing of multiple bank statement PDFs.
+### `bsp.Housekeeping`
 
-### `bsp.process_pdf_statement()`
+*class* — `bank_statement_parser.data`
 
-*function* — `bank_statement_parser.modules.statements`
+Orphan-detection and cascaded-delete helper for the raw SQLite database.
 
-Process a single bank statement PDF and save results to parquet files.
+### `bsp.ParquetFiles`
 
-### `bsp.copy_statements_to_project()`
+*class* — `bank_statement_parser.modules.data`
 
-*function* — `bank_statement_parser.modules.statements`
+Paths to the statement-level temporary Parquet files written on the SUCCESS path.
 
-Copy processed statement PDFs into the project ``statements/`` directory.
+### `bsp.PdfResult`
 
-### `bsp.delete_temp_files()`
+*class* — `bank_statement_parser.modules.data`
 
-*function* — `bank_statement_parser.modules.statements`
+Top-level result returned by :func:`~bank_statement_parser.modules.statements.process_pdf_statement`.
 
-Delete temporary parquet files created during batch processing.
+### `bsp.ProjectConfigMissing`
 
-## Low-level persistence helpers
+*class* — `bank_statement_parser.modules.errors`
 
-### `bsp.update_parquet()`
+Project config folder missing or empty.
 
-*function* — `bank_statement_parser.modules.parquet`
+### `bsp.ProjectDatabaseMissing`
 
-Update parquet files with processed results from all PDFs in a batch.
+*class* — `bank_statement_parser.modules.errors`
 
-### `bsp.update_db()`
+Project database file not found.
 
-*function* — `bank_statement_parser.modules.database`
+### `bsp.ProjectPaths`
 
-Insert processed batch results into the SQLite database.
+*class* — `bank_statement_parser.modules.paths`
 
-## Data structures
+All file-system paths for a bank_statement_parser project, derived from a single root directory.
 
-### `bsp.PdfResult`
+### `bsp.Review`
 
 *class* — `bank_statement_parser.modules.data`
 
-Top-level result returned by :func:`~bank_statement_parser.modules.statements.process_pdf_statement`.
+Payload for a PDF where extraction succeeded but CAB validation failed.
 
-### `bsp.Success`
+### `bsp.Statement`
 
-*class* — `bank_statement_parser.modules.data`
+*class* — `bank_statement_parser.modules.statements`
 
-Payload for a fully-validated PDF result.
+Represents a single bank statement PDF with data extraction and validation.
 
-### `bsp.Review`
+### `bsp.StatementBatch`
 
-*class* — `bank_statement_parser.modules.data`
+*class* — `bank_statement_parser.modules.statements`
 
-Payload for a PDF where extraction succeeded but CAB validation failed.
+Handles batch processing of multiple bank statement PDFs.
 
-### `bsp.Failure`
+### `bsp.StatementError`
 
-*class* — `bank_statement_parser.modules.data`
+*class* — `bank_statement_parser.modules.errors`
 
-Payload for a PDF result where no usable statement data was produced.
+Root exception for statement processing errors.
 
 ### `bsp.StatementInfo`
 
 *class* — `bank_statement_parser.modules.data`
 
 Statement-level metadata extracted from a successfully validated PDF.
 
-### `bsp.ParquetFiles`
+### `bsp.Success`
 
 *class* — `bank_statement_parser.modules.data`
 
-Paths to the statement-level temporary Parquet files written on the SUCCESS path.
-
-## Debug / diagnostics
-
-### `bsp.debug_pdf_statement()`
-
-*function* — `bank_statement_parser.modules.debug`
-
-Re-process a single failing PDF and write a debug.json diagnostic file.
-
-### `bsp.debug_statements()`
+Payload for a fully-validated PDF result.
 
-*function* — `bank_statement_parser.modules.debug`
+### `bsp.TestGateFailure`
 
-Re-process all failing statements from a completed batch and write debug files.
+*class* — `bank_statement_parser.modules.errors`
 
-## Errors
+Raised when bsp's own pytest suite fails during TestHarness.setup().
 
-### `bsp.StatementError`
+### `bsp.TestHarness`
 
-*class* — `bank_statement_parser.modules.errors`
+*class* — `bank_statement_parser.testing`
 
-Root exception for statement processing errors.
+Programmatic test environment for integration testing by dependent projects.
 
-### `bsp.ProjectDatabaseMissing`
+### `bsp.__app_name__`
 
-*class* — `bank_statement_parser.modules.errors`
+*constant*
 
-Project database file not found.
+### `bsp.__version__`
 
-### `bsp.ProjectConfigMissing`
+*constant*
 
-*class* — `bank_statement_parser.modules.errors`
+### `bsp.build_datamart()`
 
-Project config folder missing or empty.
+*function* — `bank_statement_parser.data`
 
-## Config helpers
+Empty and rebuild all mart tables (DimDate, DimAccount, DimStatement, FactTransaction, FactBalance) from the raw source tables.
 
 ### `bsp.copy_default_import_config()`
 
@@ -159,97 +133,101 @@ Copy all default import TOML configuration files to a destination directory.
 
 Copy the project folder structure (directories only) to a destination.
 
-### `bsp.validate_or_initialise_project()`
+### `bsp.copy_statements_to_project()`
 
-*function* — `bank_statement_parser.modules.paths`
+*function* — `bank_statement_parser.modules.statements`
 
-Validate an existing project or initialise a new one at *project_path*.
+Copy processed statement PDFs into the project ``statements/`` directory.
 
-### `bsp.ProjectPaths`
+### `bsp.create_db()`
 
-*class* — `bank_statement_parser.modules.paths`
+*function* — `bank_statement_parser.data`
 
-All file-system paths for a bank_statement_parser project, derived from a single root directory.
+Create (or recreate) the raw SQLite database with all tables and indexes.
 
-## Low-level PDF helpers
+### `bsp.db`
 
-### `bsp.pdf_open()`
+*module* — `bank_statement_parser.modules.reports_db`
 
-*function* — `bank_statement_parser.modules.pdf_functions`
+SQLite-backed report classes and export helpers.
 
-Open a PDF file and return the PDF object with performance logging.
+### `bsp.debug_pdf_statement()`
 
-### `bsp.page_crop()`
+*function* — `bank_statement_parser.modules.debug`
 
-*function* — `bank_statement_parser.modules.pdf_functions`
+Re-process a single failing PDF and write a debug.json diagnostic file.
 
-Crop a PDF page to the specified bounding box coordinates, with smart defaults.
+### `bsp.debug_statements()`
 
-### `bsp.page_text()`
+*function* — `bank_statement_parser.modules.debug`
 
-*function* — `bank_statement_parser.modules.pdf_functions`
+Re-process all failing statements from a completed batch and write debug files.
 
-Extract all text content from a PDF page.
+### `bsp.delete_temp_files()`
 
-### `bsp.region_search()`
+*function* — `bank_statement_parser.modules.statements`
 
-*function* — `bank_statement_parser.modules.pdf_functions`
+Delete temporary parquet files created during batch processing.
 
-Search for a regex pattern within a PDF region and return the first match text.
+### `bsp.get_exchange_rates()`
+
+*function* — `bank_statement_parser.modules.forex`
+
+Fetch daily USD-based exchange rates and persist them to ``exchange_rates``.
 
 ### `bsp.get_table_from_region()`
 
 *function* — `bank_statement_parser.modules.pdf_functions`
 
 Extract a structured table from a PDF region using configurable extraction settings.
 
-## Data-mart / database
+### `bsp.page_crop()`
 
-### `bsp.build_datamart()`
+*function* — `bank_statement_parser.modules.pdf_functions`
 
-*function* — `bank_statement_parser.data`
+Crop a PDF page to the specified bounding box coordinates, with smart defaults.
 
-Empty and rebuild all mart tables (DimDate, DimAccount, DimStatement, FactTransaction, FactBalance) from the raw source tables.
+### `bsp.page_text()`
 
-### `bsp.create_db()`
+*function* — `bank_statement_parser.modules.pdf_functions`
 
-*function* — `bank_statement_parser.data`
+Extract all text content from a PDF page.
 
-Create (or recreate) the raw SQLite database with all tables and indexes.
+### `bsp.pdf_open()`
 
-### `bsp.Housekeeping`
+*function* — `bank_statement_parser.modules.pdf_functions`
 
-*class* — `bank_statement_parser.data`
+Open a PDF file and return the PDF object with performance logging.
 
-Orphan-detection and cascaded-delete helper for the raw SQLite database.
+### `bsp.process_pdf_statement()`
 
-## Forex / currency conversion
+*function* — `bank_statement_parser.modules.statements`
 
-### `bsp.get_exchange_rates()`
+Process a single bank statement PDF and save results to parquet files.
 
-*function* — `bank_statement_parser.modules.forex`
+### `bsp.region_search()`
 
-Fetch daily USD-based exchange rates and persist them to ``exchange_rates``.
+*function* — `bank_statement_parser.modules.pdf_functions`
 
-### `bsp.ForexApiConfig`
+Search for a regex pattern within a PDF region and return the first match text.
 
-*class* — `bank_statement_parser.modules.data`
+### `bsp.update_db()`
 
-Configuration for the forex exchange-rate fetching service.
+*function* — `bank_statement_parser.modules.database`
 
-## Testing harness
+Insert processed batch results into the SQLite database.
 
-### `bsp.TestHarness`
+### `bsp.update_parquet()`
 
-*class* — `bank_statement_parser.testing`
+*function* — `bank_statement_parser.modules.parquet`
 
-Programmatic test environment for integration testing by dependent projects.
+Update parquet files with processed results from all PDFs in a batch.
 
-### `bsp.TestGateFailure`
+### `bsp.validate_or_initialise_project()`
 
-*class* — `bank_statement_parser.modules.errors`
+*function* — `bank_statement_parser.modules.paths`
 
-Raised when bsp's own pytest suite fails during TestHarness.setup().
+Validate an existing project or initialise a new one at *project_path*.
 
 ## DB Report Backend