Metadata-Version: 2.4
Name: singular-finance
Version: 1.0.0
Summary: Uma biblioteca Python para análise financeira corporativa, valuation e indicadores
Home-page: https://github.com/singular-finance/singular-finance
Author: Singular Finance Team
Author-email: contact@singularfinance.com
Project-URL: Bug Reports, https://github.com/singular-finance/singular-finance/issues
Project-URL: Source, https://github.com/singular-finance/singular-finance
Project-URL: Documentation, https://singular-finance.readthedocs.io/
Keywords: finance,valuation,financial-analysis,corporate-finance,indicators
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: yfinance>=0.1.70
Requires-Dist: requests>=2.25.0
Requires-Dist: beautifulsoup4>=4.9.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: xlsxwriter>=3.0.0
Requires-Dist: jupyter>=1.0.0
Requires-Dist: ipywidgets>=7.6.0
Requires-Dist: tqdm>=4.62.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=0.5; extra == "docs"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
pip install singular-finance
```

## 🔧 Instalação para Desenvolvimento

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

---

## 🎯 Exemplo Rápido de Uso

```python
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:**
```python
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:**
```python
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:
```python
from singular_finance import visualization
fig = visualization.plot_financial_metrics(indicadores)
```

---

## 🧪 Testes automatizados

```bash
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:

```bash
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:

```bash
# 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](CONTRIBUTING.md).
