Primeiros passos

Requisitos

• Python 3.9 ate 3.14
• Acesso ao terminal (macOS, Linux ou WSL)

Instalacao

pip install bankstatementparser

Para suporte a DataFrame Polars:

pip install bankstatementparser[polars]

Inicio rapido

Deteccao automatica e analise de qualquer 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())

Funciona com arquivos .xml (CAMT/PAIN.001), .csv, .ofx, .qfx, .mt940 e .sta.

Analise CAMT.053

from bankstatementparser import CamtParser

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

Analise PAIN.001

from bankstatementparser import Pain001Parser

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

Streaming para arquivos grandes

Para arquivos com milhares de transacoes, use streaming para manter a memoria limitada:

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

Analise em memoria

Analise a partir de bytes sem operacoes de I/O em disco -- util para fluxos SFTP ou API:

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

Processamento paralelo de arquivos

Analise multiplos arquivos simultaneamente:

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), "rows")

Deduplicacao

Detecte duplicatas exatas e correspondencias suspeitas com scores de confianca:

from bankstatementparser import CamtParser, Deduplicator

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

print(f"Unicas: {len(result.unique_transactions)}")
print(f"Duplicatas exatas: {len(result.exact_duplicates)}")
print(f"Correspondencias suspeitas: {len(result.suspected_matches)}")

Processamento seguro de ZIP

Processe arquivos XML compactados com verificacoes de seguranca integradas (protecao contra bombas, rejeicao de entradas criptografadas):

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())} transacoes")

Exportacao

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

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

Uso CLI

# Analisar e exibir
python -m bankstatementparser.cli --type camt --input statement.xml

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

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

Opcoes CLI:

• --type {camt,pain001} -- tipo do parser
• --input <caminho> -- arquivo de entrada
• --output <caminho_csv> -- exportar para CSV
• --streaming -- streaming para arquivos grandes
• --show-pii -- mostrar campos sensiveis (mascarados por padrao)
• --max-size <MB> -- limite de tamanho do arquivo

Configuracao de desenvolvimento 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

Execute a suite de testes:

pytest

Referencia da API

Classes parser

Funcoes utilitarias

Funcao	Proposito
detect_statement_format(path)	Deteccao automatica do formato do arquivo
create_parser(path, fmt)	Criar o parser apropriado
parse_files_parallel(paths)	Analisar multiplos arquivos simultaneamente
iter_secure_xml_entries(zip_path)	Iterar entradas ZIP com seguranca

Classes de dados

Classe	Proposito
Deduplicator	Detectar transacoes duplicadas
DeduplicationResult	Resultado com unicas, exatas e correspondencias suspeitas
InputValidator	Validar caminhos e formatos de arquivo
Transaction	Registro de transacao normalizado
FileResult	Resultado da analise paralela
ZipXMLSource	Wrapper de membro ZIP

Excecoes

Excecao	Quando e lancada
ParserError	Falhas de analise
ExportError	Falhas de exportacao (CSV/JSON/Excel)
ValidationError	Falhas de validacao de entrada
ZipSecurityError	Falhas de verificacao de seguranca ZIP