Metadata-Version: 2.5
Name: ifdata-bcb
Version: 1.0.0
Summary: Analise de dados financeiros do Banco Central do Brasil (BCB)
Project-URL: Homepage, https://github.com/enzoomoreira/ifdata-bcb
Project-URL: Repository, https://github.com/enzoomoreira/ifdata-bcb
Project-URL: Documentation, https://github.com/enzoomoreira/ifdata-bcb/tree/master/docs
Project-URL: Bug Tracker, https://github.com/enzoomoreira/ifdata-bcb/issues
Project-URL: Changelog, https://github.com/enzoomoreira/ifdata-bcb/blob/master/CHANGELOG.md
License: MIT License
        
        Copyright (c) 2026 Enzo Moreira
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: duckdb>=1.5.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: pandas>=2.0.0
Requires-Dist: platformdirs>=3.0.0
Requires-Dist: pyarrow>=10.0.0
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=14.3.1
Requires-Dist: tenacity>=9.1.2
Requires-Dist: thefuzz[speedup]>=0.22.0
Description-Content-Type: text/markdown

# ifdata-bcb

[![PyPI version](https://img.shields.io/pypi/v/ifdata-bcb)](https://pypi.org/project/ifdata-bcb/)
[![Python](https://img.shields.io/pypi/pyversions/ifdata-bcb)](https://pypi.org/project/ifdata-bcb/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/enzoomoreira/ifdata-bcb/actions/workflows/ci.yml/badge.svg)](https://github.com/enzoomoreira/ifdata-bcb/actions/workflows/ci.yml)

Coleta e analise de dados contabeis e financeiros de instituicoes financeiras brasileiras. Dados publicos do Banco Central do Brasil.

| Fonte | Modulo | Dados | Periodicidade |
|-------|--------|-------|---------------|
| COSIF | `bcb.cosif` | Plano contabil (individual e prudencial) | Mensal |
| IFDATA | `bcb.ifdata` | Informacoes financeiras | Trimestral |
| Cadastro | `bcb.cadastro` | Metadados de instituicoes (segmento, conglomerado) | Trimestral |

## Instalacao

```bash
uv add ifdata-bcb
```

Requer Python 3.12+.

## Uso Rapido

```python
import ifdata_bcb as bcb

# 1. Coletar dados (primeira vez ou atualizar)
bcb.cadastro.collect("2024-01", "2024-12")
bcb.cosif.collect("2024-01", "2024-12")
bcb.ifdata.collect("2024-01", "2024-12")

# 2. Buscar instituicao por nome (fuzzy matching)
bcb.cadastro.search("Itau")
bcb.cadastro.search("Bradesco")
#    cnpj_8                 instituicao  situacao        fontes  score
# 0  60872504  ITAU UNIBANCO HOLDING S.A.        A  cosif,ifdata    100

# 3. Ler dados usando CNPJ de 8 digitos
# start e OBRIGATORIO (posicional); instituicao e keyword-only e opcional
# start sozinho = data unica; start + end = range
# read() devolve a data como DatetimeIndex 'date': df.loc["2024"] e resample() funcionam direto

# COSIF (escopo=None busca em todos os escopos)
df = bcb.cosif.read(
    "2024-12", instituicao="60872504", conta="TOTAL GERAL DO ATIVO", escopo="prudencial"
)

# IFDATA
df = bcb.ifdata.read(
    "2024-01", "2024-12", instituicao="60872504", conta="Lucro Liquido"
)

# Bulk read: todas as instituicoes (sem instituicao)
df = bcb.cosif.read("2024-12", escopo="prudencial")

# Enriquecer com dados cadastrais inline
df = bcb.ifdata.read(
    "2024-01",
    "2024-12",
    instituicao="60872504",
    escopo="prudencial",
    cadastro=["tcb", "segmento"],
)

# Cadastro
df = bcb.cadastro.read("2024-12", segmento="Banco Multiplo")

# Espiar dados direto do BCB sem tocar o cache local
df = bcb.cosif.fetch("2024-12", instituicao="60872504", escopo="prudencial")

# 4. Listar valores distintos e contas
bcb.ifdata.list_values(["relatorio"])
bcb.cosif.list_values(["data", "escopo"])
bcb.cadastro.list_values(["segmento"], uf="SP")
bcb.cosif.list_contas("ativo", escopo="prudencial")

# 5. SQL direto com DuckDB (para analises avancadas)
from ifdata_bcb.infra import QueryEngine

qe = QueryEngine()
df = qe.sql("""
    SELECT CNPJ_8, NOME_INSTITUICAO, SALDO
    FROM '{cache}/cosif/prudencial/*.parquet'
    WHERE DATA_BASE = 202412 AND NOME_CONTA = 'TOTAL GERAL DO ATIVO'
    ORDER BY SALDO DESC
    LIMIT 10
""")
```

## Documentacao

### Guias de Uso

- **[getting-started.md](docs/getting-started.md)** - Instalacao e primeiro uso

### Fontes de Dados

- **[cosif.md](docs/providers/cosif.md)** - Plano contabil (individual/prudencial)
- **[ifdata.md](docs/providers/ifdata.md)** - Informacoes financeiras trimestrais
- **[cadastro.md](docs/providers/cadastro.md)** - Metadados de instituicoes

### Uso Avancado

- **[sql-queries.md](docs/advanced/sql-queries.md)** - Queries SQL com DuckDB
- **[extending.md](docs/advanced/extending.md)** - Como criar novos providers

### Arquitetura Interna

- **[architecture.md](docs/internals/architecture.md)** - Visao geral da arquitetura
- **[core.md](docs/internals/core.md)** - EntityLookup, Constants, Eras, BaseExplorer
- **[domain.md](docs/internals/domain.md)** - Exceptions, Types, Validation
- **[infra.md](docs/internals/infra.md)** - Settings, QueryEngine, DataManager
- **[providers.md](docs/internals/providers.md)** - BaseCollector, Explorers

## Estrutura de Dados

```
{cache}/
  cosif/
    individual/       # cosif_ind_YYYYMM.parquet
    prudencial/       # cosif_prud_YYYYMM.parquet
  ifdata/
    valores/          # ifdata_val_YYYYMM.parquet
    cadastro/         # ifdata_cad_YYYYMM.parquet
```

O diretorio de cache varia por sistema:

| Sistema | Caminho |
|---------|---------|
| Windows | `%LOCALAPPDATA%\py-bacen\Cache\` |
| Linux | `~/.cache/py-bacen/` |
| macOS | `~/Library/Caches/py-bacen/` |

Customizavel via variavel de ambiente `BACEN_DATA_DIR`.

## API Publica

### Modulo Principal

```python
import ifdata_bcb as bcb

# Explorers (lazy loading)
bcb.cosif  # COSIFExplorer
bcb.ifdata  # IFDATAExplorer
bcb.cadastro  # CadastroExplorer

# Excecoes e warnings (todos importaveis do top-level)
bcb.BacenAnalysisError  # Classe base de todos os erros
bcb.BacenWarning  # Classe base de todos os warnings
```

### Metodos dos Explorers

Todos os explorers possuem:

| Metodo | Descricao |
|--------|-----------|
| `collect(start, end=None, ...)` | Coleta dados do BCB. `end=None` coleta so o periodo de `start` |
| `read(start, end, *, instituicao, ...)` | Le dados com filtros (`start` posicional, demais keyword-only). Devolve DatetimeIndex `date` |
| `fetch(start, end, *, instituicao, ...)` | Baixa do BCB e devolve DataFrame no formato de `read()` sem tocar o cache local |
| `list_values(columns, *, ...)` | Lista valores distintos para colunas (SELECT DISTINCT) |
| `list_periodos(escopo=None)` | Periodos disponiveis (opcionalmente por escopo) |
| `describe(escopo=None)` | Escopos, filtros e colunas aceitas, mais os periodos coletados |
| `has_data(escopo=None)` | Verifica se tem dados |

Metodos especificos:

| Explorer | Metodos Adicionais |
|----------|-------------------|
| `cosif` | `list_contas()` |
| `ifdata` | `list_contas()`, `mapeamento()` |
| `cadastro` | `search()` |

## Limitacoes Conhecidas

- **Dependencia de APIs do BCB**: a coleta depende da disponibilidade dos endpoints publicos do Banco Central. Se a API estiver fora do ar ou mudar seu schema, a coleta pode falhar.
- **Dados historicos**: nem todos os periodos estao disponiveis para todas as fontes. Use `list_periodos()` para verificar disponibilidade.
- **Primeira coleta lenta**: a coleta inicial de dados pode demorar dependendo do range de datas solicitado, pois faz multiplas requisicoes HTTP ao BCB (paralelas com 4 workers).
- **Cache sem invalidacao automatica**: dados coletados ficam em cache local indefinidamente. Para atualizar, colete novamente o periodo desejado.
- **Sem suporte offline**: a coleta requer conexao com a internet. A leitura funciona offline se os dados ja estiverem em cache.

## Contribuindo

Contribuicoes sao bem-vindas! Consulte o [guia de contribuicao](CONTRIBUTING.md) para detalhes sobre como participar.

## Licenca

Distribuido sob a licenca MIT. Veja [LICENSE](LICENSE) para mais informacoes.
