filings-b3

Biblioteca Python simples e eficiente para acessar os conjuntos de dados públicos da B3 (a bolsa brasileira). Cada reader transforma um pregão em um pandas.DataFrame tipado, validado por contrato e com proveniência — valores monetários como Decimal exato, nunca um float com perda.

✨ Principais recursos

📊 Readers do Boletim Diário (BDI)

• BdiStocksSummaryReader — o resumo por pregão do mercado à vista de ações (DailyAverageStocks).
• BdiBtbLendingOpenPositionsReader — o retrato das posições em aberto de empréstimo de ativos (BTB) (BTBLendingOpenPosition).

🗂️ Readers da Pesquisa por Pregão

O arquivo de instrumentos do pregão (IN{aammdd}.zip, BVBG.028.02) é um download lido de dezoito formas: cada registro aninha os seus campos sob exatamente um de 20 blocos InstrmInf. O download é um zip dentro de um zip, com um XML por snapshot intradiário do pregão — todo reader lê o de maior CreDtAndTm, o definitivo, porque os snapshots são cumulativos.

• InstrumentsFileReader — todos os tipos sob o layout de 52 colunas publicado pela B3.
• Por tipo, cada um com a lista completa de campos do seu bloco: InstrumentsFileEqtyReader (ações), InstrumentsFileOptnOnEqtsReader (opções sobre ações), InstrumentsFileOptnOnSpotAndFuturesReader (opções sobre disponível e futuros), InstrumentsFileExrcEqtsReader (exercício de opções), InstrumentsFileEqtyFwdReader (termo de ações), InstrumentsFileFxdIncmReader (renda fixa), InstrumentsFileAdrReader (ADRs), InstrumentsFileBtcReader (BTC), InstrumentsFileFutrCtrctsReader (contratos futuros), InstrumentsFileDrvsOptnExrcReader (exercício de opções sobre derivativos), InstrumentsFileStrtgyReader (estratégias, com as duas pernas), InstrumentsFileNtlBdReader (títulos públicos nacionais), InstrumentsFileIntlBdReader (títulos internacionais), InstrumentsFileFxdIncmNonTrdblReader (renda fixa não negociável), InstrumentsFileOtcReader (balcão), InstrumentsFileCshReader (disponível) e InstrumentsFileFicReader (fundos de investimento).
• InstrumentsLayoutMetaReader — snapshot tipado do layout autoritativo da B3, para o datalake e para o job semanal de deriva de contrato.

🔒 Fidelidade por construção

• Tipagem explícita — toda coluna tipada na carga, nunca a inferência do pandas.
• Decimais exatos — dinheiro e qualquer valor cuja parte fracionária importa é decimal.Decimal, nunca um float binário.
• Contratos — uma fonte que remove uma coluna obrigatória falha de forma barulhenta com ContractError, verificado contra os layouts publicados pela própria B3.

🧾 Proveniência & camada bronze

• Seis colunas de proveniência em todo frame (url, updated_at, source_key, package_version, ingestion_run_id, content_hash).
• Passe path_raw= para reter cada página bruta da fonte para a camada bronze de um datalake.

🚀 Primeiros passos

Pré-requisitos

• Python 3.10+
• Poetry (recomendado)
• Opcional: Makefile

Instalação

Opção 1: Pip (recomendado)

pip install filings-b3

Opção 2: Build a partir do código-fonte

git clone https://github.com/guilhermegor/filings-b3.git
cd filings-b3
pyenv install 3.12.2
pyenv local 3.12.2
poetry install --no-root
poetry shell

Uso básico

from datetime import date
from filings_b3.daily_bulletin import BdiBtbLendingOpenPositionsReader

df = BdiBtbLendingOpenPositionsReader(date(2025, 1, 2)).read()
print(df[["TCKR_SYMB", "STOCK_BALANCE", "BALANCE"]].head())

Cada reader é importado pela sua macro-seção (filings_b3.daily_bulletin, filings_b3.search_trading_session, …) — a única forma pública. A raiz do pacote não exporta readers.

⚠️ Mudança na 0.3.0 — duas colunas do arquivo de instrumentos foram renomeadas, porque um mesmo campo vinha publicado com dois nomes diferentes entre readers do mesmo arquivo, quebrando um UNION ALL sobre a família (#165). Só o nome da coluna mudou — caminho de origem e valores são os mesmos.

Reader	Antes	Agora
InstrumentsFileFxdIncmReader	TP	UNDRLYG_INSTRM_ID_TP
InstrumentsFileExrcEqtsReader	TP	OPTN_EXRC_INSTRM_ID_TP

O TP de InstrumentsFileIntlBdReader não muda: ali é o tag Tp de verdade do bloco.

⚠️ Mudança na 0.2.0 — até a 0.1.x cada reader também era reexportado de forma plana na raiz (from filings_b3 import BdiBtbLendingOpenPositionsReader). Isso foi removido: com seis macro-seções e ~105 datasets previstos, a raiz viraria uma lista de mais de cem nomes. Troque o import pela seção correspondente.

date_ref é obrigatório — o endpoint do BDI é endereçado por data, então não existe um padrão "mais recente". Veja a documentação para cada reader e mais receitas.

Rodando os testes

poetry run pytest tests/unit/ -v
poetry run pytest tests/integration/ -v

📂 Estrutura do projeto

filings-b3/
├── .github/
│   ├── workflows/
│   ├── CODEOWNERS
│   └── PULL_REQUEST_TEMPLATE.md
├── assets/
│   └── b3-logo.png
├── bin/
├── docs/
├── src/filings_b3/
│   ├── daily_bulletin/          # readers do Boletim Diário do Pregão (BDI)
│   ├── search_trading_session/  # readers da Pesquisa por Pregão
│   └── _internal/               # privado: contracts, utils, ports
├── tests/
│   ├── unit/
│   ├── integration/
│   └── performance/
├── LICENSE
├── Makefile
├── poetry.lock
├── pyproject.toml
├── README.md
└── requirements.txt

👨‍💻 Autores

• guilhermegor — GitHub | LinkedIn

📜 Licença

Este projeto é licenciado sob a Licença MIT — veja LICENSE.

🔗 Links úteis

• Documentação
• Repositório no GitHub
• Rastreador de issues