Skip to content

Anonymisation Guide

Anonymise a single bank statement PDF by scrambling all personal data while preserving the document's visual structure and layout.

Requires the optional anonymise dependency:

pip install uk-bank-statement-parser[anonymise]

How it works

  1. Numeric ID detection — a document-level scan identifies sort codes, account numbers, IBANs, and card numbers. Each is replaced with a deterministic fake value (last two digits tiled across the full length, e.g. 40-37-28 → 28-28-28). always_anonymise overrides take priority.

  2. Protected phrase detection — fragments matching dates, payment type codes, URLs, numeric values, or entries in never_anonymise configs are marked as protected and left unchanged.

  3. Content stream rewrite — pikepdf rewrites the PDF content streams directly, substituting scrambled bytes for original text bytes. Font encoding (Latin-1 and ToUnicode/CMap) is handled transparently, including subset-embedded fonts.

Configuration files

The library ships two system config files (bundled, not user-editable):

File Purpose
always_anonymise_system.toml Force specific strings to a known replacement value
never_anonymise_system.toml Protect specific phrases from being scrambled

You can supplement these with your own files:

always_anonymise.toml — force specific replacements: 

"40-37-28" = "00-00-00"
"12345678" = "00000000"
"Jason Farrar" = "John Doe"

never_anonymise.toml — protect additional phrases: 

exclude = [
    "My Bank",
    "My Employer Ltd",
]

User config files should not be committed to source control — they will typically contain real account numbers or names.

Public API

anonymise_pdf()

anonymise_pdf(
    input_path: str | Path,
    output_path: str | Path | None = None,
    always_anonymise_path: str | Path | None = None,
    never_anonymise_path: str | Path | None = None,
    debug: bool = False,
) -> Path

Anonymise a single bank statement PDF.

Delegates entirely to bank_statement_anonymiser.anonymise_pdf.

Parameters

input_path: Path to the source PDF.

output_path: Destination path for the anonymised PDF. If omitted, the output is written to the same directory as the input with the filename prefix anonymised_ prepended. It is strongly recommended to supply an explicit output path that does not contain any sensitive information (e.g. account numbers or names that may appear in the original filename).

always_anonymise_path: Optional path to a user always_anonymise.toml file. Entries here force specific strings to a known replacement value and take priority over the bundled system file.

never_anonymise_path: Optional path to a user never_anonymise.toml file. Phrases listed here are preserved exactly as-is during the scramble pass and are merged with the bundled system file.

debug: When True, print diagnostic information about config loading, fragment classification, and scramble pairs to stdout.

Returns

Path The path to the anonymised output file.

CLI Usage

The bsp anonymise command wraps the Python API:

# Anonymise a single PDF (output written alongside input)
bsp anonymise statement.pdf

# Specify a safe output filename
bsp anonymise statement.pdf --output ~/anonymised/output.pdf

# Supply user config files
bsp anonymise statement.pdf \
    --always-anonymise my_always_anonymise.toml \
    --never-anonymise my_never_anonymise.toml

# Enable diagnostic output
bsp anonymise statement.pdf --debug

See the CLI Reference for all available options.