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 nove formas: cada registro aninha os seus campos sob exatamente um de 20 blocos InstrmInf.

• 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) e InstrumentsFileBtcReader (BTC).
• 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.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