etl-ativa-investimentos 0.1.5

No project description provided

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

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.

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:

{
    "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.

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:

{
    "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.

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:

{
    "movimentacao": ...,
}

---

Interface orientada a objetos (readers)

Além das funções funcionais, a lib oferece classes que encapsulam leitura, cache e validação:

from etl_ativa_investimentos.readers.carteira_cotizada import CarteiraCotzada
from etl_ativa_investimentos.readers.posicao_consolidada import PosicaoConsolidada
from etl_ativa_investimentos.readers.movimentacao_b3 import MovimentacaoB3

Cada classe segue o mesmo contrato:

Método	Descrição
.<aba>()	Retorna o DataFrame da aba (lazy load + cache)
.infer_excel_date()	Tenta inferir a data do Excel pelo nome do arquivo; retorna date ou None
.load()	Carrega todas as abas em memória de uma vez
.validate_all()	Valida todas as abas; retorna ValidationResult
.load_and_print_errors()	Carrega, valida e exibe erros formatados

Exemplo

from etl_ativa_investimentos.readers.carteira_cotizada import CarteiraCotzada

carteira = CarteiraCotzada("SIM.PAINEL.2026.01.30.10.01.36.xlsx")

# Inferência da data a partir do nome do arquivo (YYYY.MM.DD)
excel_date = carteira.infer_excel_date()
print(excel_date)  # 2026-01-30

# Lazy load — lê só quando chamado, resultado fica em cache
df = carteira.carteira_analitica()

# Validação estruturada
result = carteira.validate_all()
if not result.ok:
    print(result.errors)  # {"nome_aba": ["mensagem de erro", ...]}

# Ou de forma conveniente
carteira.load_and_print_errors()

---

Exemplo completo (API funcional)

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 — 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

# 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

---

Referência das colunas por módulo

Documentação detalhada com todas as abas, nomes de colunas e tipos esperados para cada Excel:

• docs/carteira_cotizada.md — 10 abas do relatório SIM Painel (.xlsx)
• docs/posicao_consolidada.md — 5 abas da Posição Consolidada (.xls)
• docs/movimentacao_b3.md — 1 aba da Movimentação B3 (.xlsx)

---

Licença

MIT