Metadata-Version: 2.4
Name: ifdata-bcb
Version: 0.2.1
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: ipywidgets>=8.1.8
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: requests>=2.28.0
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.search('Itau')
bcb.search('Bradesco')
#    CNPJ_8                       INSTITUICAO  SITUACAO  FONTES  SCORE
# 0  60872504  ITAU UNIBANCO HOLDING S.A.           A    ...    100
# Quando possivel, prioriza resultados com dados disponiveis em FONTES.

# 3. Ler dados usando CNPJ de 8 digitos
# COSIF/IFDATA: instituicao e start sao OBRIGATORIOS
# start sozinho = data unica; start + end = range

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

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

# Enriquecer com dados cadastrais inline
df = bcb.ifdata.read(
    instituicao='60872504',
    start='2024-01',
    end='2024-12',
    escopo='prudencial',
    cadastro=['TCB', 'SEGMENTO']
)

# Cadastro
info = bcb.cadastro.info('60872504', start='2024-12')

# Cadastro tambem pode ser filtrado sem instituicao
df = bcb.cadastro.read(start='2024-12', segmento='Banco Multiplo')

# 4. Listar contas e instituicoes disponiveis
bcb.cosif.list_accounts(escopo='prudencial')
bcb.cosif.list_institutions(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)** - BaseExplorer, EntityLookup, Constants
- **[domain.md](docs/internals/domain.md)** - Exceptions, Models, 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

# Funcoes
bcb.search(termo, limit=10)  # Busca instituicoes por nome

# Exceptions
bcb.BacenAnalysisError       # Classe base para todos os erros
bcb.DataUnavailableError     # Dados nao disponiveis
```

### Metodos dos Explorers

Todos os explorers possuem:

| Metodo | Descricao |
|--------|-----------|
| `collect(start, end, ...)` | Coleta dados do BCB |
| `read(instituicao, start, ...)` | Le dados com filtros |
| `list_periods()` | Periodos disponiveis |
| `has_data()` | Verifica se tem dados |

Metodos especificos:

| Explorer | Metodos Adicionais |
|----------|-------------------|
| `cosif` | `list_accounts()`, `list_institutions()` |
| `ifdata` | `list_accounts()`, `list_institutions()`, `list_reporters()`, `list_reports()` |
| `cadastro` | `info()`, `list_segmentos()`, `list_ufs()`, `get_conglomerate_members()` |

## 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_periods()` para verificar disponibilidade.
- **Primeira coleta lenta**: a coleta inicial de dados pode demorar dependendo do range de datas solicitado, pois faz requisicoes HTTP sequenciais ao BCB.
- **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.
