biblioteca-br 0.1.3

Biblioteca Python para dados econômicos e financeiros brasileiros

biblioteca-br

Interface unificada em Python para dados econômicos e financeiros do Brasil.

Chega de navegar entre dezenas de APIs, documentações incompletas e formatos inconsistentes. A biblioteca-br integra o Banco Central (BACEN), a Bolsa de Valores (B3) e o IBGE em uma única API coerente todos os retornos são DataFrames do pandas, limpos e prontos para análise.

Sobre o Projeto

Sou estudante de Ciência da Computação e desenvolvi a biblioteca-br como um projeto de aprendizado. A ideia surgiu da frustração de tentar consumir dados econômicos brasileiros durante os estudos (APIs espalhadas), formatos inconsistentes e pouca documentação.

Grande parte da inspiração veio da python-bcb, biblioteca criada pelo Wilson Freitas, que mostrou como é possível tornar dados do Banco Central acessíveis de forma elegante. Se você ainda não conhece o trabalho dele, recomendo muito.

Este projeto é o resultado dessa jornada: imperfeito, em evolução, mas feito com dedicação. Se você também está aprendendo e quiser contribuir, trocar um papo minhas redes estão ali.

---

Instalação

pip install biblioteca-br

Requisitos: Python 3.8 ou superior. As dependências (requests, pandas, matplotlib, openpyxl, reportlab, yfinance) são instaladas automaticamente.

---

Início Rápido

1. Banco Central — Séries Temporais (SGS)

Busque os principais indicadores macroeconômicos com uma única linha:

from biblioteca_br import selic, ipca, igpm, cambio

# Taxa Selic (meta) desde 2022
df_selic = selic(inicio="01/01/2022")
print(df_selic.head())
#          data  valor
# 0  2022-01-03  9.15
# 1  2022-02-01  9.75
# ...

# IPCA mensal
df_ipca = ipca(inicio="01/01/2023", fim="31/12/2023")

# Cotação do Dólar (também disponível: EUR, GBP)
df_usd = cambio(moeda="USD", inicio="01/01/2024")

# Expectativas do Boletim Focus
from biblioteca_br import expectativas
df_focus = expectativas(indicador="IPCA", top=50)

2. Bolsa de Valores — B3

Obtenha histórico de preços de ações e índices diretamente da B3 via Yahoo Finance:

from biblioteca_br import acao, acoes, ibovespa

# Histórico de uma ação (o sufixo .SA é adicionado automaticamente)
df_petr4 = acao("PETR4", inicio="2024-01-01")
print(df_petr4[["Open", "High", "Low", "Close", "Volume"]].head())

# Múltiplas ações de uma vez
df_carteira = acoes(["PETR4", "VALE3", "ITUB4"], inicio="2024-01-01")

# Ibovespa
df_ibov = ibovespa(inicio="2023-01-01")

3. Visualização e Exportação

Gere gráficos e exporte dados com formatação profissional:

from biblioteca_br import selic, linha, excel, pdf, comparativo

df = selic(inicio="01/01/2022")

# Gráfico de linha
linha(df, titulo="Taxa Selic — Evolução Histórica", ylabel="% a.a.")

# Painel com os 4 principais indicadores (Selic, IPCA, Dólar, IGP-M)
comparativo(titulo="Panorama Econômico Brasileiro")

# Exportar para Excel com formatação condicional
excel(df, "selic_2022_2024.xlsx", nome_planilha="Selic")

# Gerar relatório em PDF
pdf(df, "relatorio_selic.pdf", titulo="Taxa Selic — Relatório Anual")

---

Referência de Módulos

Módulo	Importação	Funções Principais	Descrição
bacen	from biblioteca_br import selic, ipca, ...	selic(), ipca(), igpm(), cambio(), expectativas(), juros_bancos(), calendario()	Séries temporais do SGS, câmbio (USD/EUR/GBP), Boletim Focus e calendário econômico
b3	from biblioteca_br import acao, acoes, ibovespa	acao(), acoes(), ibovespa()	Histórico de preços de ações, FIIs e o índice Ibovespa via Yahoo Finance
plot	from biblioteca_br import linha, barras, area, ...	linha(), barras(), area(), dispersao(), comparativo(), plotar()	Gráficos prontos para séries temporais, comparativos e painéis de indicadores
exportar	from biblioteca_br import excel, pdf, csv, json	excel(), pdf(), csv(), json()	Exportação de DataFrames para .xlsx (formatado), .pdf (com tabela e gráfico), .csv e .json

Detalhes das funções — BACEN

# Todas as funções de séries temporais aceitam os mesmos parâmetros:
# inicio: str no formato "dd/mm/aaaa" (padrão: "01/01/2020")
# fim: str no mesmo formato (opcional — traz até a data mais recente)

selic(inicio="01/01/2022", fim="31/12/2023")
ipca(inicio="01/01/2020")
igpm(inicio="01/06/2023")
cambio(moeda="USD", inicio="01/01/2024")  # moeda: "USD", "EUR" ou "GBP"

# Focus — expectativas de mercado
expectativas(indicador="IPCA", top=100)   # indicador: "IPCA", "Selic", "IGP-M", etc.

# Taxas de juros por banco e modalidade
juros_bancos(top=1000)

# Calendário estimado de divulgações (IPCA, Selic/COPOM, PIB)
calendario(meses=3)

Detalhes das funções — B3

# O código da ação deve ser informado sem o sufixo ".SA" — a função adiciona automaticamente
acao("PETR4", inicio="2024-01-01", fim="2024-12-31")
acao("BOVA11")  # FIIs e ETFs também são suportados

# Múltiplas ações retornam um DataFrame com MultiIndex
acoes(["PETR4", "VALE3", "ITUB4"], inicio="2024-01-01")

ibovespa(inicio="2020-01-01")  # Índice ^BVSP

Detalhes das funções — Plot

# Gráfico de linha (ideal para séries temporais)
linha(df, colunas="valor", coluna_data="data", titulo="Selic", ylabel="% a.a.")

# Gráfico de barras (vertical ou horizontal)
barras(df, horizontal=False, empilhado=False, rotacao_x=45)

# Gráfico de área (ideal para composição)
area(df, empilhado=True, alpha=0.7)

# Dispersão com regressão linear automática
dispersao(x=df["selic"], y=df["ipca"], mostrar_correlacao=True)

# Painel 2x2 com Selic, IPCA, Dólar e IGP-M (busca os dados automaticamente)
comparativo(titulo="Panorama Econômico")

# Função genérica
plotar(df, tipo="linha")   # tipo: "linha", "barra", "area", "dispersao"

Detalhes das funções — Exportar

# Excel com cabeçalho formatado, colunas ajustadas e painéis congelados
excel(df, "saida.xlsx", nome_planilha="IPCA", adicionar_formatacao=True)

# CSV no padrão brasileiro (ponto-e-vírgula como separador)
csv(df, "saida.csv", separador=";", decimais=",")

# PDF com tabela (até 50 linhas) e gráfico opcional embutido
pdf(df, "relatorio.pdf", titulo="Relatório Selic", incluir_grafico=True)

# JSON com indentação
json(df, "dados.json", orient="records", indent=2)

---

FAQ

Qual é a vantagem de usar a biblioteca-br em vez de chamar as APIs diretamente?

As APIs do BACEN, B3 e IBGE têm formatos, endpoints e padrões de erro completamente diferentes entre si. Com a biblioteca-br, você usa a mesma sintaxe para todas as fontes e sempre recebe um DataFrame do pandas padronizados sem precisar lidar com JSON aninhado, tratamento de datas em múltiplos formatos ou gerenciamento manual de erros HTTP.

---

Os dados são em tempo real?

Não. Os dados seguem a defasagem natural de cada fonte:

• BACEN (SGS): séries atualizadas em D+1 ou conforme o calendário de divulgação de cada indicador (ex.: IPCA é divulgado mensalmente pelo IBGE e refletido no SGS com alguns dias de defasagem).
• B3 (via Yahoo Finance): cotações históricas de fechamento; dados do dia corrente podem ter atraso de 15 a 20 minutos dependendo do horário.
• Boletim Focus: atualizado semanalmente pelo BACEN, toda segunda-feira.

Para operações que exigem dados em tempo real, recomenda-se consultar diretamente as APIs oficiais das respectivas instituições.

---

Como tratar erros de conexão ou dados não encontrados?

A biblioteca propaga as exceções originais para que você possa tratá-las de forma explícita:

import requests
from biblioteca_br import selic

try:
    df = selic(inicio="01/01/2024")
except requests.exceptions.Timeout:
    print("A requisição ao BACEN expirou. Tente novamente.")
except requests.exceptions.RequestException as e:
    print(f"Erro de conexão: {e}")
except ValueError as e:
    print(f"Nenhum dado encontrado para o período informado: {e}")

Para diagnóstico detalhado, ative o logging:

import logging
logging.basicConfig(level=logging.INFO)

---

Quais moedas estão disponíveis para câmbio?

A versão atual suporta USD (Dólar comercial), EUR (Euro) e GBP (Libra esterlina), todas via séries do SGS/BACEN. Novas moedas serão adicionadas nas próximas versões.

---

---

Contribuindo

Contribuições são muito bem-vindas! Se encontrar um bug, tiver sugestões ou quiser adicionar uma nova fonte de dados:

1. Faça um fork do repositório: github.com/senaanalytics/biblioteca-br
2. Crie uma branch para sua feature: git checkout -b feature/nova-funcionalidade
3. Faça commit das alterações e abra um Pull Request

---

Licença

Este projeto está licenciado sob a MIT License — veja o arquivo LICENSE para mais detalhes.

---

Autor

Desenvolvido por Isaque Sena

• GitHub: @senaanalytics
• LinkedIn: Isaque Sena

---

quem cede a vez não quer vitória