Metadata-Version: 2.4
Name: biblioteca-br
Version: 0.1.3
Summary: Biblioteca Python para dados econômicos e financeiros brasileiros
Author-email: Isaque Sena <isaquesenadasilva1@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/senaanalytics/biblioteca-br
Project-URL: Repository, https://github.com/senaanalytics/biblioteca-br
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Requires-Dist: pandas>=1.3
Requires-Dist: matplotlib>=3.4
Requires-Dist: openpyxl>=3.0
Requires-Dist: reportlab>=3.6
Requires-Dist: yfinance>=0.2
Dynamic: license-file

# biblioteca-br

![Versão](https://img.shields.io/badge/versão-0.1.1-blue)
![Python](https://img.shields.io/badge/python-3.8%2B-brightgreen)
![Licença](https://img.shields.io/badge/licença-MIT-green)
![Status](https://img.shields.io/badge/status-Alpha-orange)

**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`](https://pypi.org/project/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

```bash
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:

```python
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:

```python
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:

```python
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

```python
# 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

```python
# 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

```python
# 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

```python
# 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:

```python
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:

```python
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](https://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](LICENSE) para mais detalhes.

---

## Autor

Desenvolvido por **Isaque Sena**

- GitHub: [@senaanalytics](https://github.com/senaanalytics)
- LinkedIn: [Isaque Sena](https://www.linkedin.com/in/isaque-sena-794b89233/)

---

*quem cede a vez não quer vitória*
