Metadata-Version: 2.4
Name: etl-ativa-investimentos
Version: 0.1.0
Summary: 
Author: Gustavo Rizzo S M de Albuquerque
Author-email: grizzo.albu@gmail.com
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: pandas (>=3.0.1,<4.0.0)
Requires-Dist: python-calamine (>=0.6.2,<0.7.0)
Description-Content-Type: text/markdown

# etl-ativa-investimentos

Biblioteca Python para leitura dos arquivos Excel exportados pela corretora **Ativa Investimentos**, convertendo-os em `pandas.DataFrame` prontos para análise, pipelines de dados e integrações ETL.

---

## Instalação

```bash
pip install etl-ativa-investimentos
```

**Requisitos:** Python >= 3.11

---

## Motivação

A Ativa Investimentos exporta relatórios em Excel com múltiplas abas e nomes de colunas em português. Esta biblioteca abstrai a leitura desses arquivos, entregando DataFrames limpos e prontos para uso — sem precisar se preocupar com nomes de abas, encoding ou engine de leitura.

---

## Módulos

A lib é organizada por tipo de relatório. Cada módulo expõe:

- Funções individuais por aba: `read_<nome_da_aba>(path)`
- Uma função `read_all(path)` que retorna todas as abas como `dict[str, DataFrame]`

---

### `posicao_consolidada`

Lê o relatório de **Posição Consolidada** (`.xls`), disponível no portal da corretora.

```python
from etl_ativa_investimentos import posicao_consolidada

path = "posicao_consolidada/2025_12_30.xls"

# Aba individual
df_acoes = posicao_consolidada.read_acoes(path)
df_rf    = posicao_consolidada.read_renda_fixa_privada(path)

# Todas as abas de uma vez
data = posicao_consolidada.read_all(path)
```

| Função | Aba do Excel | Colunas principais |
|--------|--------------|--------------------|
| `read_acoes(path)` | Ações | Código, Nome, Carteira, Quantidade, Preço, Total |
| `read_clubes_e_fundos(path)` | Clubes e Fundos | Nome do fundo, Data, Valor Aplicação, Cota, Valor |
| `read_financeiro(path)` | Financeiro | Conta, Tipo, Disponível, Projeção, Total |
| `read_renda_fixa_privada(path)` | Renda Fixa Privada | Ticker, Emissor, Remuneração, PU Atual, Quantidade, Total |
| `read_renda_fixa_publica(path)` | Renda Fixa Pública | Título, Emissor, Indexador, Data Vencimento, PU Atual, Total |
| `read_all(path)` | Todas | Retorna `dict[str, DataFrame]` |

**Chaves retornadas por `read_all`:**

```python
{
    "acoes": ...,
    "clubes_e_fundos": ...,
    "financeiro": ...,
    "renda_fixa_privada": ...,
    "renda_fixa_publica": ...,
}
```

---

### `carteira_cotizada`

Lê o relatório de **Carteira Cotizada / Painel** (`.xlsx`), exportado pelo sistema SIM da corretora.

```python
from etl_ativa_investimentos import carteira_cotizada

path = "SIM.PAINEL.2026.01.30.10.01.36.xlsx"

# Aba individual
df = carteira_cotizada.read_carteira_analitica(path)

# Todas as abas de uma vez
data = carteira_cotizada.read_all(path)
```

| Função | Conteúdo |
|--------|----------|
| `read_variacao_patrimonial(path)` | Patrimônio bruto, líquido e variação percentual |
| `read_composicao_patrimonio(path)` | Composição por classe de ativo com provisões de IR e IOF |
| `read_carteira_analitica(path)` | Posição consolidada com preços, financeiros e L/P |
| `read_rentabilidade_carteira(path)` | Performance: dia, mês, 30 dias, ano, 12 meses, início |
| `read_rentabilidade_no_ano(path)` | Rentabilidade mensal no ano corrente por ativo |
| `read_rentabilidade_ultimos_meses(path)` | Histórico mensal comparado ao CDI e IBOVESPA |
| `read_rentabilidade_ativos(path)` | Performance individual por ativo em múltiplos períodos |
| `read_provisoes(path)` | Provisões de IR e IOF com datas e valores |
| `read_renda_fixa_detalhada(path)` | CDBs e títulos com PU de aquisição, atual, IR e IOF |
| `read_clubes_e_fundos_detalhados(path)` | Fundos com cotas, L/P, IR, IOF e valor líquido |
| `read_all(path)` | Todas as abas — retorna `dict[str, DataFrame]` |

**Chaves retornadas por `read_all`:**

```python
{
    "variacao_patrimonial": ...,
    "composicao_patrimonio": ...,
    "carteira_analitica": ...,
    "rentabilidade_carteira": ...,
    "rentabilidade_no_ano": ...,
    "rentabilidade_ultimos_meses": ...,
    "rentabilidade_ativos": ...,
    "provisoes": ...,
    "renda_fixa_detalhada": ...,
    "clubes_e_fundos_detalhados": ...,
}
```

---

### `movimentacao_b3`

Lê o relatório de **Movimentação B3** (`.xlsx`), exportado diretamente pelo portal da B3 ou pela corretora.

```python
from etl_ativa_investimentos import movimentacao_b3

path = "movimentacao-2023-01-01-ate-31-12-2023.xlsx"

# Aba individual
df = movimentacao_b3.read_movimentacao(path)

# Todas as abas de uma vez
data = movimentacao_b3.read_all(path)
```

| Função | Aba do Excel | Colunas principais |
|--------|--------------|--------------------|
| `read_movimentacao(path)` | Movimentação | Entrada/Saída, Data, Movimentação, Produto, Instituição, Quantidade, Preço unitário, Valor da Operação |
| `read_all(path)` | Todas | Retorna `dict[str, DataFrame]` |

**Chaves retornadas por `read_all`:**

```python
{
    "movimentacao": ...,
}
```

---

## Exemplo completo

```python
from etl_ativa_investimentos import (
    posicao_consolidada,
    carteira_cotizada,
    movimentacao_b3,
)

# Posição consolidada
posicao = posicao_consolidada.read_all("posicao_consolidada/2025_12_30.xls")
print(posicao["acoes"])

# Carteira cotizada
painel = carteira_cotizada.read_all("SIM.PAINEL.2026.01.30.10.01.36.xlsx")
print(painel["carteira_analitica"])

# Movimentação B3
mov = movimentacao_b3.read_all("movimentacao-2023-01-01-ate-31-12-2023.xlsx")
print(mov["movimentacao"])
```

---

## Detalhes técnicos

- Todos os arquivos são lidos com `pandas.read_excel` usando o engine [`calamine`](https://github.com/tafia/calamine) — uma implementação em Rust, mais rápida e sem dependência do Java (ao contrário do `xlrd`/`openpyxl` para `.xls` antigos).
- Suporta tanto `.xls` (formato legado) quanto `.xlsx`.
- Cada função retorna um `pandas.DataFrame` sem transformações — os dados são entregues exatamente como estão no Excel, para que você decida como processar.

---

## Desenvolvimento

```bash
# Clonar e instalar dependências
git clone https://github.com/seu-usuario/etl-ativa-investimentos.git
cd etl-ativa-investimentos
poetry install

# Rodar testes
poetry run pytest -v
```

---

## Licença

MIT

