singular-finance 1.0.0

Uma biblioteca Python para análise financeira corporativa, valuation e indicadores

Singular Finance - Biblioteca de Análise Financeira Corporativa

Singular Finance é uma biblioteca Python completa para análise financeira corporativa, oferecendo ferramentas avançadas para valuation, indicadores financeiros, análise fundamentalista, análise técnica de ações, fluxo de caixa, visualização e modelos matemáticos.

🚀 Principais recursos

• Indicadores Financeiros: ROE, ROA, margens, liquidez, endividamento, eficiência
• Valuation: Fluxo de caixa descontado (DCF), múltiplos comparáveis, valuation de ativos
• Análise Fundamentalista:
  • Margem bruta, margem operacional, payout, dividend yield
  • Crescimento de receita e lucro, qualidade dos lucros
  • Dívida líquida/EBITDA, ROIC, EBITDA/Receita, eficiência e mais
• Análise Técnica:
  • RSI (índice de força relativa), MACD, médias móveis (SMA/EMA)
  • Detecção de padrões de candles (martelo, estrela cadente...)
  • Suporte total para estratégias quantitativas
• Fluxo de Caixa: Métricas completas, qualidade do fluxo e análise executiva
• Visualização: Gráficos, dashboards, heatmaps e mais
• Modelos Matemáticos: Black-Scholes, Monte Carlo, VaR, GARCH, machine learning
• Coleta de Dados: Yahoo Finance, automatização de downloads
• Utilitários Financeiros: Formatação, cálculos auxiliares, validação

---

📦 Instalação

pip install singular-finance

🔧 Instalação para Desenvolvimento

git clone https://github.com/singular-finance/singular-finance.git
cd singular-finance
pip install -e .[dev]

---

🎯 Exemplo Rápido de Uso

import pandas as pd
from singular_finance import indicators, models

# Dados de exemplo
df = pd.DataFrame({
    "receita_liquida": [100000, 120000],
    "lucro_bruto": [40000, 50000],
    "lucro_liquido": [20000, 25000],
    "ebit": [30000, 35000],
    "ebitda": [31000, 36000],
    "patrimonio_liquido": [100000, 110000],
    "dividendos": [5000, 6000],
    "acoes_circulantes": [10000, 10000]
})

# 📊 Indicadores fundamentalistas
fi = indicators.FinancialIndicators(df)
print("ROE:", fi.calculate_roe())
print("Margem Bruta:", fi.calculate_margem_bruta())
print("Payout:", fi.calculate_payout())
print("Dividend Yield:", fi.calculate_dividend_yield(preco_acao=20.00))

# 📈 Análise técnica
import numpy as np
precos = pd.Series(np.random.uniform(10, 30, 100))
print("RSI:", models.calculate_rsi(precos).tail())
print("MACD:", models.calculate_macd(precos).tail())

---

📚 Documentação de Indicadores Avançados

A Classe FinancialIndicators permite calcular KPIs profissionais:

• Margem Bruta: calculate_margem_bruta()
• Margem Operacional (EBIT): calculate_margem_operacional()
• Payout: calculate_payout()
• Dividend Yield: calculate_dividend_yield(preco_acao)
• Crescimento Receita/Lucro: calculate_crescimento_receita()
• Qualidade dos Lucros: calculate_qualidade_lucros()
• Dívida Líquida / EBITDA: calculate_divida_liquida_ebitda()
• e muito mais!

Exemplo:

fi = indicators.FinancialIndicators(df)
print("Margem Operacional:", fi.calculate_margem_operacional())
print("Crescimento Receita:", fi.calculate_crescimento_receita())

---

📉 Recursos de Análise Técnica

Funções diretas no módulo models para indicadores clássicos:

• RSI: models.calculate_rsi(prices, window=14)
• MACD: models.calculate_macd(prices)
• Médias móveis: models.calculate_sma(prices, window) e models.calculate_ema(prices, window)
• Candles: models.is_hammer(open, high, low, close)

Exemplo:

import pandas as pd
from singular_finance import models
precos = pd.Series([...])
rsi = models.calculate_rsi(precos)
macd = models.calculate_macd(precos)

---

📈 Visualizações

Monte gráficos automáticos com o módulo visualization. Exemplo:

from singular_finance import visualization
fig = visualization.plot_financial_metrics(indicadores)

---

🧪 Testes automatizados

pytest tests/ -v

---

📦 Como construir e publicar (resumo)

Este repositório inclui os testes automatizados e metadados básicos. Para publicar no TestPyPI/PyPI siga o fluxo abaixo (detalhado em PUBLISHING.md):

1. Atualize a versão em singular_finance/__init__.py e o CHANGELOG.md.
2. Execute os testes localmente: pytest -q (todos os testes devem passar).
3. Gere as distribuições:

python -m pip install --upgrade build twine
python -m build

4. Verifique os pacotes com twine check dist/*.
5. Publique primeiro em TestPyPI para validação e depois no PyPI:

# TestPyPI
twine upload --repository testpypi dist/*

# PyPI (quando pronto)
twine upload dist/*

No ambiente de CI, use secrets (PYPI_API_TOKEN) e o GitHub Actions para publicar automaticamente quando criar uma nova tag.

Veja PUBLISHING.md para um guia passo-a-passo e o workflow de exemplo em .github/workflows/ci-publish.yml.

---

🤝 Contribuição

Veja o arquivo CONTRIBUTING.md.