Primeros pasos

Requisitos

• Python 3.9 a 3.14
• Acceso a terminal (macOS, Linux o WSL)

Instalación

pip install bankstatementparser

Para soporte de DataFrames de Polars:

pip install bankstatementparser[polars]

Inicio rápido

Detectar automáticamente y analizar cualquier formato

from bankstatementparser import create_parser, detect_statement_format

fmt = detect_statement_format("transactions.ofx")
parser = create_parser("transactions.ofx", fmt)
df = parser.parse()  # pandas DataFrame
print(df.head())

Esto funciona con archivos .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 y .sta.

Analizar CAMT.053

from bankstatementparser import CamtParser

parser = CamtParser("statement.xml")
transactions = parser.parse()

Analizar PAIN.001

from bankstatementparser import Pain001Parser

parser = Pain001Parser("payment.xml")
payments = parser.parse()

Streaming de archivos grandes

Para archivos con miles de transacciones, use streaming para mantener la memoria acotada:

parser = CamtParser("large_statement.xml")
for transaction in parser.parse_streaming(redact_pii=True):
    process(transaction)  # La memoria permanece constante

Análisis en memoria

Analice desde bytes sin E/S de disco -- útil para flujos de trabajo SFTP o API:

xml_bytes = download_from_sftp()
parser = CamtParser.from_bytes(xml_bytes, source_name="daily.xml")
transactions = parser.parse()

Procesamiento de archivos en paralelo

Analice múltiples archivos simultáneamente:

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "filas")

Deduplicación

Detecte duplicados exactos y coincidencias sospechosas con puntuaciones de confianza:

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Únicos: {len(result.unique_transactions)}")
print(f"Duplicados exactos: {len(result.exact_duplicates)}")
print(f"Coincidencias sospechosas: {len(result.suspected_matches)}")

Procesamiento seguro de ZIP

Procese archivos XML comprimidos con comprobaciones de seguridad integradas (protección contra bombas, rechazo de entradas cifradas):

from bankstatementparser import iter_secure_xml_entries, CamtParser

for entry in iter_secure_xml_entries("statements.zip"):
    parser = CamtParser.from_bytes(entry.xml_bytes, source_name=entry.source_name)
    print(f"{entry.source_name}: {len(parser.parse())} transacciones")

Exportación

parser = CamtParser("statement.xml")
parser.export_csv("output.csv")
parser.export_json("output.json")

# Polars (requiere bankstatementparser[polars])
polars_df = parser.to_polars()

Uso de la CLI

# Analizar y mostrar
python -m bankstatementparser.cli --type camt --input statement.xml

# Exportar a CSV
python -m bankstatementparser.cli --type camt --input statement.xml --output transactions.csv

# Streaming con PII visible
python -m bankstatementparser.cli --type camt --input statement.xml --streaming --show-pii

Opciones de la CLI:

• --type {camt,pain001} -- tipo de analizador
• --input <path> -- archivo de entrada
• --output <csv_path> -- exportar a CSV
• --streaming -- streaming de archivos grandes
• --show-pii -- mostrar campos sensibles (ocultos por defecto)
• --max-size <MB> -- límite de tamaño de archivo

Configuración del entorno de desarrollo local

git clone https://github.com/sebastienrousseau/bankstatementparser.git
cd bankstatementparser
python3 -m venv .venv && source .venv/bin/activate
pip install poetry && poetry install --with dev

Ejecutar la suite de pruebas:

pytest

Referencia de la API

Clases de analizadores

Funciones de utilidad

Función	Propósito
detect_statement_format(path)	Detectar automáticamente el formato del archivo
create_parser(path, fmt)	Crear el analizador apropiado
parse_files_parallel(paths)	Analizar múltiples archivos simultáneamente
iter_secure_xml_entries(zip_path)	Iterar entradas ZIP de forma segura

Clases de datos

Clase	Propósito
Deduplicator	Detectar transacciones duplicadas
DeduplicationResult	Resultado con únicos, exactos y coincidencias sospechosas
InputValidator	Validar rutas de archivos y formatos
Transaction	Registro de transacción normalizado
FileResult	Resultado del análisis en paralelo
ZipXMLSource	Envoltorio de miembro ZIP

Excepciones

Excepción	Cuándo se lanza
ParserError	Fallos de análisis
ExportError	Fallos de exportación (CSV/JSON/Excel)
ValidationError	Fallos de validación de entrada
ZipSecurityError	Fallos de comprobación de seguridad ZIP