Metadata-Version: 2.3
Name: quantframe-lib
Version: 0.1.2
Summary: A lightweight pandas-based backtesting framework extracted from deribit-arb.
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2.0
Requires-Dist: pandas<=2.3.3
Requires-Dist: pyarrow>=24.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: tqdm
Requires-Dist: yfinance>=1.3.0 ; extra == 'yfinance'
Requires-Python: >=3.10
Provides-Extra: yfinance
Description-Content-Type: text/markdown

# quantframe

`quantframe` is a lightweight Python backtesting framework extracted from the
`deribit-arb` backtest engine.

It provides:

- `backtest(weights, prices, config)` for DataFrame-based target weights.
- `run_strategy(strategy, prices, config)` for event-style strategies, with optional metadata for explicit symbol lifetimes.
- TWAP and VWAP execution models.
- gross PnL, fee PnL, optional funding PnL, and common performance metrics.
- `BacktestResult.plot()` for quick result inspection.

## Install

```bash
uv sync
```

Yahoo Finance downloads are optional:

```bash
pip install quantframe-lib[yfinance]
```

## Run Tests

```bash
uv run pytest
```

## Minimal Usage

```python
import pandas as pd

from quantframe.backtest import BacktestConfig, backtest

prices = pd.DataFrame(
    {
        "timestamp": pd.date_range("2024-01-01", periods=3, freq="1min", tz="UTC"),
        "symbol": ["ETH-PERPETUAL"] * 3,
        "close": [100.0, 101.0, 102.0],
    }
)
weights = pd.DataFrame(
    {
        "timestamp": [pd.Timestamp("2024-01-01", tz="UTC")],
        "symbol": ["ETH-PERPETUAL"],
        "weight": [1.0],
    }
)

result = backtest(weights, prices, BacktestConfig(exec_horizon=1))
print(result.metrics)
```

## Loading Bar Data

```python
from quantframe.data.yfinance import YahooFinanceProvider

bars = YahooFinanceProvider().load_bars(
    ["BTC-USD", "GC=F"],
    start="2016-01-01",
    end="2026-04-30",
    interval="1d",
)
```

Custom providers can subclass `DataProvider` and implement `fetch_bars()`.
Returned bars are validated and normalized before use.
