Filings B3

Python Version PyPI Version PyPI Downloads Formatting: isort Test Coverage License Open Issues Contributions Welcome

Simple and efficient Python library to interact with B3 (Brazil's exchange) public datasets. Each reader turns one trading session into a typed, contract-validated pandas.DataFrame carrying provenance — money as exact Decimal, never a lossy float.

✨ Key Features

📊 Daily Bulletin (BDI) readers

BdiStocksSummaryReader — the per-session cash-equities summary (DailyAverageStocks).
BdiBtbLendingOpenPositionsReader — the securities-lending (BTB) open-position snapshot (BTBLendingOpenPosition).

🔒 Fidelity by construction

Explicit typing — every column typed on load, never pandas' inference.
Exact decimals — money and any value whose fractional part matters is decimal.Decimal, never a binary float.
Contracts — a source that drops a required column fails loudly with ContractError, verified against B3's own published layouts.

🧾 Provenance & bronze layer

Six provenance columns on every frame (url, updated_at, source_key, package_version, ingestion_run_id, content_hash).
Pass path_raw= to retain each untouched source page for a datalake's bronze layer.

🚀 Getting Started

Prerequisites

Python 3.10+
Poetry (recommended)
Optional: Makefile

Installation

Option 1: Pip (recommended)

pip install filings-b3

Option 2: Build from source

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

Basic usage

from datetime import date
from filings_b3 import BdiBtbLendingOpenPositionsReader

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

date_ref is required — the BDI endpoint is date-addressed, so there is no "latest" default. See the documentation for every reader and more recipes.

Running Tests

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

📂 Project Structure

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

👨‍💻 Authors

guilhermegor — GitHub | LinkedIn

📜 License

This project is licensed under the MIT License — see LICENSE.

🔗 Useful Links

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

filings_b3-0.1.2.tar.gz (54.7 kB view details)

Uploaded Jul 25, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

filings_b3-0.1.2-py3-none-any.whl (75.5 kB view details)

Uploaded Jul 25, 2026 Python 3

File details

Details for the file filings_b3-0.1.2.tar.gz.

File metadata

Download URL: filings_b3-0.1.2.tar.gz
Upload date: Jul 25, 2026
Size: 54.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for filings_b3-0.1.2.tar.gz
Algorithm	Hash digest
SHA256	`5ee3b055bd75fbec95d0b2535e55dc9cf1000ee68ec150b75c5af6ede3da6112`
MD5	`c5aeb63b2c5657d400072a43ce5125b0`
BLAKE2b-256	`dbd89e079f3702d5dcdc323310b17ed4bced7980dbd602efe15bd52e4bf32c90`

See more details on using hashes here.

Provenance

The following attestation bundles were made for filings_b3-0.1.2.tar.gz:

Publisher: release-pypi.yaml on guilhermegor/filings-b3

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: filings_b3-0.1.2.tar.gz
- Subject digest: 5ee3b055bd75fbec95d0b2535e55dc9cf1000ee68ec150b75c5af6ede3da6112
- Sigstore transparency entry: 2241833400
- Sigstore integration time: Jul 25, 2026
Source repository:
- Permalink: guilhermegor/filings-b3@bf8d7e54e70df81b697c832853871210946114fc
- Branch / Tag: refs/heads/main
- Owner: https://github.com/guilhermegor
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yaml@bf8d7e54e70df81b697c832853871210946114fc
- Trigger Event: workflow_dispatch