Metadata-Version: 2.4
Name: fincore
Version: 0.3.0
Summary: Quantitative performance and risk analytics for Python
Home-page: https://github.com/cloudQuant/fincore
Author-email: cloudQuant <yunjinqi@gmail.com>
Maintainer: cloudQuant
Maintainer-email: yunjinqi@gmail.com
License: Apache-2.0
Project-URL: Homepage, https://github.com/cloudQuant/fincore
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: scipy>=1.3.0
Requires-Dist: pytz>=2023.3
Requires-Dist: packaging>=21.0
Provides-Extra: viz
Requires-Dist: matplotlib>=3.3; extra == "viz"
Requires-Dist: seaborn>=0.11; extra == "viz"
Requires-Dist: ipython>=7.0; extra == "viz"
Requires-Dist: PyPDF2>=3.0; extra == "viz"
Requires-Dist: bokeh>=3.0; extra == "viz"
Requires-Dist: plotly>=5.0; extra == "viz"
Provides-Extra: bayesian
Requires-Dist: pymc>=5.0; extra == "bayesian"
Provides-Extra: datareader
Requires-Dist: pandas-datareader>=0.8.0; extra == "datareader"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-xdist>=2.0; extra == "dev"
Requires-Dist: pytest-cov>=2.10; extra == "dev"
Requires-Dist: pytest-benchmark>=3.2; extra == "dev"
Requires-Dist: pytest-sugar>=0.9; extra == "dev"
Requires-Dist: parameterized>=0.7; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: types-requests>=2.25; extra == "dev"
Requires-Dist: yfinance>=0.2; extra == "dev"
Requires-Dist: requests>=2.25; extra == "dev"
Requires-Dist: matplotlib>=3.3; extra == "dev"
Requires-Dist: seaborn>=0.11; extra == "dev"
Requires-Dist: PyPDF2>=3.0; extra == "dev"
Requires-Dist: bokeh>=3.0; extra == "dev"
Requires-Dist: plotly>=5.0; extra == "dev"
Requires-Dist: playwright>=1.40; extra == "dev"
Requires-Dist: openpyxl>=3.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7; extra == "dev"
Provides-Extra: all
Requires-Dist: fincore[bayesian,datareader,viz]; extra == "all"
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-python

# fincore | Quantitative Performance & Risk Analytics

<p align="center">
    <img src="https://img.shields.io/badge/version-0.3.0-blueviolet.svg" alt="Version 0.3.0"/>
    <img src="https://img.shields.io/badge/tests-2345%20passed-brightgreen.svg" alt="Tests Passing"/>
    <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="Coverage"/>
    <img src="https://img.shields.io/badge/platform-mac%7Clinux%7Cwin-yellow.svg" alt="Platforms"/>
    <img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-brightgreen.svg" alt="Python Versions"/>
    <img src="https://img.shields.io/badge/license-Apache%202.0-orange" alt="License: Apache 2.0"/>
</p>

<p align="center">
    <a href="#english">English</a> · <a href="#中文">中文</a> · <a href="https://fincore.readthedocs.io/en/latest/">Documentation</a> · <a href="CONTRIBUTING.md">Contributing</a> · <a href="CHANGELOG.md">Changelog</a> · <a href="docs/MIGRATION.md">Migration Guide</a>
</p>

---

<a name="english"></a>

## Overview

**fincore** is a Python library for quantitative finance analytics — 150+ financial metrics, portfolio optimization, Monte Carlo simulation, and performance attribution. It continues the **empyrical** stack under active maintenance by [cloudQuant](https://github.com/cloudQuant).

### Highlights

| Feature | Description |
|---------|-------------|
| **150+ Metrics** | Returns, risk, drawdown, alpha/beta, capture ratios, timing, streaks |
| **AnalysisContext** | `fincore.analyze()` — lazy, cached computation with JSON/HTML export |
| **RollingEngine** | Batch rolling metrics (sharpe, volatility, max_drawdown, beta) in one call |
| **Pluggable Viz** | Matplotlib, HTML, Plotly, Bokeh backends via `VizBackend` protocol |
| **Portfolio Optimization** | Efficient frontier, risk parity, constrained optimization |
| **Monte Carlo** | Bootstrap, scenario testing, path simulation |
| **Performance Attribution** | Brinson, Fama-French, style analysis |
| **Lazy Imports** | `import fincore` in ~0.04s — heavy deps load on first access |
| **PEP 561** | `py.typed` marker for type checker support |

### Installation

```bash
pip install fincore                  # Core
pip install "fincore[viz]"           # + matplotlib, seaborn
pip install "fincore[all]"           # Everything
pip install "fincore[dev]"           # Development tools
```

**From source:**
```bash
git clone https://github.com/cloudQuant/fincore   # International
git clone https://gitee.com/yunjinqi/fincore       # China mirror
cd fincore && pip install -e ".[dev,viz]"
```

### Quick Start

```python
import fincore

# One-liner analysis — lazy, cached
ctx = fincore.analyze(returns, factor_returns=benchmark)

print(f"Sharpe:  {ctx.sharpe_ratio:.4f}")
print(f"Max DD:  {ctx.max_drawdown:.4f}")
print(f"Alpha:   {ctx.alpha:.6f}")

ctx.to_html(path="report.html")       # Self-contained HTML report
ctx.to_json()                          # JSON export
```

**Classic API** (drop-in empyrical replacement):
```python
from fincore import empyrical

sharpe = empyrical.sharpe_ratio(returns, risk_free=0.02/252)
alpha, beta = empyrical.alpha_beta(returns, benchmark)
mdd = empyrical.max_drawdown(returns)
```

**RollingEngine** (batch rolling metrics):
```python
from fincore.core.engine import RollingEngine

engine = RollingEngine(returns, factor_returns=benchmark, window=60)
results = engine.compute(['sharpe', 'volatility', 'max_drawdown', 'beta'])
```

**Portfolio Optimization:**
```python
from fincore.optimization import efficient_frontier, risk_parity, optimize

ef = efficient_frontier(returns_df, n_points=50)
rp = risk_parity(returns_df)
w = optimize(returns_df, objective="max_sharpe")
```

### Architecture

```
fincore/
├── __init__.py          # Lazy exports (Empyrical, Pyfolio, analyze)
├── empyrical.py         # Empyrical facade (150+ methods)
├── core/
│   ├── context.py       # AnalysisContext — lazy cached metrics
│   └── engine.py        # RollingEngine — batch rolling metrics
├── metrics/             # 17 metric modules (returns, risk, ratios, ...)
├── viz/                 # VizBackend protocol + backends
├── optimization/        # Efficient frontier, risk parity
├── simulation/          # Monte Carlo, bootstrap
├── attribution/         # Brinson, Fama-French, style analysis
├── risk/                # EVT, GARCH
├── report/              # HTML/PDF report generation
├── tearsheets/          # Pyfolio-style plotting
└── utils/               # Shared helpers
```

### Testing

```bash
pytest tests/ -n 4                   # Parallel (2345 tests)
pytest tests/ --cov=fincore          # With coverage
pytest tests/test_core/              # AnalysisContext, RollingEngine, Viz
```

### License

Apache License 2.0 — see [LICENSE](LICENSE). Originally by Quantopian Inc., maintained by the open-source community.

---

<a name="中文"></a>

## 概述

**fincore** 是面向量化金融的 Python 分析库 — 150+ 金融指标、组合优化、蒙特卡洛模拟和绩效归因。它延续 **empyrical** 分析栈，由 [cloudQuant](https://github.com/cloudQuant) 持续维护。

### 核心特性

| 特性 | 说明 |
|------|------|
| **150+ 指标** | 收益、风险、回撤、Alpha/Beta、捕获比率、择时、连续统计 |
| **AnalysisContext** | `fincore.analyze()` — 惰性计算、自动缓存，支持 JSON/HTML 导出 |
| **RollingEngine** | 批量滚动指标（sharpe、volatility、max_drawdown、beta）一次调用 |
| **可插拔可视化** | Matplotlib、HTML、Plotly、Bokeh 后端，基于 `VizBackend` 协议 |
| **组合优化** | 有效前沿、风险平价、约束优化 |
| **蒙特卡洛** | Bootstrap、情景测试、路径模拟 |
| **绩效归因** | Brinson、Fama-French、风格分析 |
| **惰性导入** | `import fincore` 仅需 ~0.04 秒 |
| **PEP 561** | `py.typed` 标记，支持类型检查器 |

### 安装

```bash
pip install fincore                  # 核心
pip install "fincore[viz]"           # + matplotlib, seaborn
pip install "fincore[all]"           # 全部依赖
pip install "fincore[dev]"           # 开发工具
```

**从源码安装：**
```bash
git clone https://gitee.com/yunjinqi/fincore       # 中国用户
git clone https://github.com/cloudQuant/fincore     # 国际用户
cd fincore && pip install -e ".[dev,viz]"
```

### 快速开始

```python
import fincore

# 一行代码完成分析 — 惰性计算、自动缓存
ctx = fincore.analyze(returns, factor_returns=benchmark)

print(f"夏普比率: {ctx.sharpe_ratio:.4f}")
print(f"最大回撤: {ctx.max_drawdown:.4f}")
print(f"Alpha:    {ctx.alpha:.6f}")

ctx.to_html(path="report.html")       # 独立 HTML 报告
ctx.to_json()                          # JSON 导出
```

**经典 API**（可直接替换 empyrical）：
```python
from fincore import empyrical

sharpe = empyrical.sharpe_ratio(returns, risk_free=0.02/252)
alpha, beta = empyrical.alpha_beta(returns, benchmark)
mdd = empyrical.max_drawdown(returns)
```

**RollingEngine**（批量滚动指标）：
```python
from fincore.core.engine import RollingEngine

engine = RollingEngine(returns, factor_returns=benchmark, window=60)
results = engine.compute(['sharpe', 'volatility', 'max_drawdown', 'beta'])
```

**组合优化：**
```python
from fincore.optimization import efficient_frontier, risk_parity, optimize

ef = efficient_frontier(returns_df, n_points=50)
rp = risk_parity(returns_df)
w = optimize(returns_df, objective="max_sharpe")
```

### 指标概览

| 类别 | 主要指标 |
|------|---------|
| **收益** | `simple_returns`, `cum_returns`, `annual_return`, `cagr`, `aggregate_returns` |
| **风险** | `max_drawdown`, `annual_volatility`, `downside_risk`, `value_at_risk`, `conditional_value_at_risk` |
| **风险调整** | `sharpe_ratio`, `sortino_ratio`, `calmar_ratio`, `omega_ratio`, `information_ratio` |
| **市场关系** | `alpha`, `beta`, `up_capture`, `down_capture`, `treynor_ratio` |
| **滚动** | `roll_sharpe_ratio`, `roll_max_drawdown`, `roll_beta`, `roll_alpha` 等 |
| **择时** | `treynor_mazuy_timing`, `henriksson_merton_timing`, `market_timing_return` |
| **连续统计** | `max_consecutive_up_days`, `max_consecutive_down_days`, `max_single_day_gain` |

> 完整指标列表见 [API 文档](docs/api文档/README.md)

### 测试

```bash
pytest tests/ -n 4                   # 并行运行（2345 个测试）
pytest tests/ --cov=fincore          # 含覆盖率
pytest tests/test_core/              # AnalysisContext、RollingEngine、可视化
```

### 贡献

欢迎贡献！详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

### 许可证

Apache License 2.0 — 详见 [LICENSE](LICENSE)。最初由 Quantopian Inc. 开发，目前由开源社区维护。
