refactor: _handle_parquet_write_error returns error dict instead of mutating

[boscorat]

Parent issue

#194 — function purification

Problem

_handle_parquet_write_error (statements.py:800) has 5 parameters and multiple side effects:

• Mutates batch_line dict in-place (lines 820-822)
• Mutates error_message_list in-place (line 823)
• Prints to stdout (line 824)
• Prints to stderr via traceback.print_exc() (line 825)

The caller must pass mutable containers and rely on in-place mutation for the result.

Proposal

Return an error dataclass or dict instead of mutating the inputs. Let the caller apply mutations. e.g. def build_parquet_error(name, pdf, exc) -> ParquetError. Move the prints to the caller or remove them.

Code relationships

Target function:

• _handle_parquet_write_error() — statements.py:800

Callers (will need updating):

• process_pdf_statement() — statements.py:828 (calls it 4 times, lines 971, 986, 1029)

Related:

• batch_line dict — built in process_pdf_statement (line 900+), passed to update_parquet and update_db
• PdfResult dataclass — data.py (the final result type)

Existing tests

None. No direct tests exist for _handle_parquet_write_error. Refactoring will not break any existing tests.

Siblings

• refactor: BatchMetadata dataclass to replace 13 duplicated parameters #195 — BatchMetadata dataclass
• refactor: ExtractionContext dataclass for extraction pipeline #196 — ExtractionContext dataclass
• refactor: decompose Statement constructor into pure factory + persistence #197 — Statement constructor decomposition
• refactor: decompose process_pdf_statement into pure extraction + persistence #198 — process_pdf_statement decomposition
• refactor: stop mutating inputs in extraction pipeline #199 — Stop mutating inputs
• refactor: add optional conn parameter to build_datamart and related functions #200 — DB connection threading
• refactor: move processing out of StatementBatch constructor #201 — StatementBatch constructor
• refactor: remove dead logs and file_path parameters from pipeline functions #202 — Dead parameter cleanup
• refactor: Parquet class accepts pre-loaded data instead of reading from disk #203 — Parquet class purification