borsapy.backtest

  1"""
  2Backtest Engine for trading strategy evaluation.
  3
  4This module provides a framework for backtesting trading strategies
  5on historical OHLCV data with comprehensive performance metrics.
  6
  7Features:
  8- Strategy function interface
  9- Technical indicator integration
 10- Performance metrics (Sharpe, Sortino, Profit Factor)
 11- Trade tracking and analysis
 12- Equity curve generation
 13- Buy & Hold comparison
 14
 15Examples:
 16    >>> import borsapy as bp
 17
 18    >>> def rsi_strategy(candle, position, indicators):
 19    ...     if indicators['rsi'] < 30 and position is None:
 20    ...         return 'BUY'
 21    ...     elif indicators['rsi'] > 70 and position == 'long':
 22    ...         return 'SELL'
 23    ...     return 'HOLD'
 24
 25    >>> result = bp.backtest("THYAO", rsi_strategy, period="1y")
 26    >>> print(result.summary())
 27    >>> print(f"Sharpe: {result.sharpe_ratio:.2f}")
 28"""
 29
 30from __future__ import annotations
 31
 32from collections.abc import Callable
 33from dataclasses import dataclass, field
 34from datetime import datetime
 35from typing import Any, Literal
 36
 37import numpy as np
 38import pandas as pd
 39
 40__all__ = ["Trade", "BacktestResult", "Backtest", "backtest"]
 41
 42
 43# Strategy signal types
 44Signal = Literal["BUY", "SELL", "HOLD"] | None
 45Position = Literal["long", "short"] | None
 46
 47# Strategy function signature
 48StrategyFunc = Callable[[dict, Position, dict], Signal]
 49
 50
 51@dataclass
 52class Trade:
 53    """
 54    Represents a single trade in a backtest.
 55
 56    Attributes:
 57        entry_time: When the trade was opened.
 58        entry_price: Price at entry.
 59        exit_time: When the trade was closed (None if open).
 60        exit_price: Price at exit (None if open).
 61        side: Trade direction ('long' or 'short').
 62        shares: Number of shares traded.
 63        commission: Total commission paid (entry + exit).
 64    """
 65
 66    entry_time: datetime
 67    entry_price: float
 68    exit_time: datetime | None = None
 69    exit_price: float | None = None
 70    side: Literal["long", "short"] = "long"
 71    shares: float = 0.0
 72    commission: float = 0.0
 73
 74    @property
 75    def is_closed(self) -> bool:
 76        """Check if trade is closed."""
 77        return self.exit_time is not None and self.exit_price is not None
 78
 79    @property
 80    def profit(self) -> float | None:
 81        """Calculate profit in currency units (None if open)."""
 82        if not self.is_closed:
 83            return None
 84        assert self.exit_price is not None
 85        if self.side == "long":
 86            gross = (self.exit_price - self.entry_price) * self.shares
 87        else:
 88            gross = (self.entry_price - self.exit_price) * self.shares
 89        return gross - self.commission
 90
 91    @property
 92    def profit_pct(self) -> float | None:
 93        """Calculate profit as percentage (None if open)."""
 94        if not self.is_closed or self.entry_price == 0:
 95            return None
 96        profit = self.profit
 97        if profit is None:
 98            return None
 99        entry_value = self.entry_price * self.shares
100        return (profit / entry_value) * 100
101
102    @property
103    def duration(self) -> float | None:
104        """Trade duration in days (None if open)."""
105        if not self.is_closed:
106            return None
107        assert self.exit_time is not None
108        delta = self.exit_time - self.entry_time
109        return delta.total_seconds() / 86400  # Convert to days
110
111    def to_dict(self) -> dict[str, Any]:
112        """Convert trade to dictionary."""
113        return {
114            "entry_time": self.entry_time,
115            "entry_price": self.entry_price,
116            "exit_time": self.exit_time,
117            "exit_price": self.exit_price,
118            "side": self.side,
119            "shares": self.shares,
120            "commission": self.commission,
121            "profit": self.profit,
122            "profit_pct": self.profit_pct,
123            "duration": self.duration,
124        }
125
126
127@dataclass
128class BacktestResult:
129    """
130    Comprehensive backtest results with performance metrics.
131
132    Follows TradingView/Mathieu2301 result format for familiarity.
133
134    Attributes:
135        symbol: Traded symbol.
136        period: Test period (e.g., "1y").
137        interval: Data interval (e.g., "1d").
138        strategy_name: Name of the strategy function.
139        initial_capital: Starting capital.
140        commission: Commission rate used.
141        trades: List of executed trades.
142        equity_curve: Daily equity values.
143        drawdown_curve: Daily drawdown values.
144        buy_hold_curve: Buy & hold comparison values.
145    """
146
147    # Identification
148    symbol: str
149    period: str
150    interval: str
151    strategy_name: str
152
153    # Configuration
154    initial_capital: float
155    commission: float
156
157    # Results
158    trades: list[Trade] = field(default_factory=list)
159    equity_curve: pd.Series = field(default_factory=lambda: pd.Series(dtype=float))
160    drawdown_curve: pd.Series = field(default_factory=lambda: pd.Series(dtype=float))
161    buy_hold_curve: pd.Series = field(default_factory=lambda: pd.Series(dtype=float))
162
163    # === Performance Properties ===
164
165    @property
166    def final_equity(self) -> float:
167        """Final portfolio value."""
168        if self.equity_curve.empty:
169            return self.initial_capital
170        return float(self.equity_curve.iloc[-1])
171
172    @property
173    def net_profit(self) -> float:
174        """Net profit in currency units."""
175        return self.final_equity - self.initial_capital
176
177    @property
178    def net_profit_pct(self) -> float:
179        """Net profit as percentage."""
180        if self.initial_capital == 0:
181            return 0.0
182        return (self.net_profit / self.initial_capital) * 100
183
184    @property
185    def total_trades(self) -> int:
186        """Total number of closed trades."""
187        return len([t for t in self.trades if t.is_closed])
188
189    @property
190    def winning_trades(self) -> int:
191        """Number of profitable trades."""
192        return len([t for t in self.trades if t.is_closed and (t.profit or 0) > 0])
193
194    @property
195    def losing_trades(self) -> int:
196        """Number of losing trades."""
197        return len([t for t in self.trades if t.is_closed and (t.profit or 0) <= 0])
198
199    @property
200    def win_rate(self) -> float:
201        """Percentage of winning trades."""
202        if self.total_trades == 0:
203            return 0.0
204        return (self.winning_trades / self.total_trades) * 100
205
206    @property
207    def profit_factor(self) -> float:
208        """Ratio of gross profits to gross losses."""
209        gross_profit = sum(t.profit or 0 for t in self.trades if t.is_closed and (t.profit or 0) > 0)
210        gross_loss = abs(sum(t.profit or 0 for t in self.trades if t.is_closed and (t.profit or 0) < 0))
211        if gross_loss == 0:
212            return float("inf") if gross_profit > 0 else 0.0
213        return gross_profit / gross_loss
214
215    @property
216    def avg_trade(self) -> float:
217        """Average profit per trade."""
218        closed = [t for t in self.trades if t.is_closed]
219        if not closed:
220            return 0.0
221        return sum(t.profit or 0 for t in closed) / len(closed)
222
223    @property
224    def avg_winning_trade(self) -> float:
225        """Average profit of winning trades."""
226        winners = [t for t in self.trades if t.is_closed and (t.profit or 0) > 0]
227        if not winners:
228            return 0.0
229        return sum(t.profit or 0 for t in winners) / len(winners)
230
231    @property
232    def avg_losing_trade(self) -> float:
233        """Average loss of losing trades."""
234        losers = [t for t in self.trades if t.is_closed and (t.profit or 0) < 0]
235        if not losers:
236            return 0.0
237        return sum(t.profit or 0 for t in losers) / len(losers)
238
239    @property
240    def max_consecutive_wins(self) -> int:
241        """Maximum consecutive winning trades."""
242        return self._max_consecutive(lambda t: (t.profit or 0) > 0)
243
244    @property
245    def max_consecutive_losses(self) -> int:
246        """Maximum consecutive losing trades."""
247        return self._max_consecutive(lambda t: (t.profit or 0) <= 0)
248
249    def _max_consecutive(self, condition: Callable[[Trade], bool]) -> int:
250        """Helper to find max consecutive trades matching condition."""
251        closed = [t for t in self.trades if t.is_closed]
252        if not closed:
253            return 0
254        max_count = 0
255        current_count = 0
256        for trade in closed:
257            if condition(trade):
258                current_count += 1
259                max_count = max(max_count, current_count)
260            else:
261                current_count = 0
262        return max_count
263
264    @property
265    def sharpe_ratio(self) -> float:
266        """
267        Sharpe ratio (risk-adjusted return).
268
269        Assumes 252 trading days and risk-free rate from current 10Y bond.
270        """
271        if self.equity_curve.empty or len(self.equity_curve) < 2:
272            return float("nan")
273
274        returns = self.equity_curve.pct_change().dropna()
275        if returns.std() == 0:
276            return float("nan")
277
278        # Get risk-free rate
279        try:
280            from borsapy.bond import risk_free_rate
281
282            rf_annual = risk_free_rate()
283        except Exception:
284            rf_annual = 0.30  # Fallback 30%
285
286        rf_daily = rf_annual / 252
287        excess_returns = returns - rf_daily
288        return float(np.sqrt(252) * excess_returns.mean() / excess_returns.std())
289
290    @property
291    def sortino_ratio(self) -> float:
292        """
293        Sortino ratio (downside risk-adjusted return).
294
295        Uses downside deviation instead of standard deviation.
296        """
297        if self.equity_curve.empty or len(self.equity_curve) < 2:
298            return float("nan")
299
300        returns = self.equity_curve.pct_change().dropna()
301
302        # Get risk-free rate
303        try:
304            from borsapy.bond import risk_free_rate
305
306            rf_annual = risk_free_rate()
307        except Exception:
308            rf_annual = 0.30
309
310        rf_daily = rf_annual / 252
311        excess_returns = returns - rf_daily
312        negative_returns = excess_returns[excess_returns < 0]
313
314        if len(negative_returns) == 0 or negative_returns.std() == 0:
315            return float("inf") if excess_returns.mean() > 0 else float("nan")
316
317        downside_std = negative_returns.std()
318        return float(np.sqrt(252) * excess_returns.mean() / downside_std)
319
320    @property
321    def max_drawdown(self) -> float:
322        """Maximum drawdown as percentage."""
323        if self.drawdown_curve.empty:
324            return 0.0
325        return float(self.drawdown_curve.min()) * 100
326
327    @property
328    def max_drawdown_duration(self) -> int:
329        """Maximum drawdown duration in days."""
330        if self.equity_curve.empty:
331            return 0
332
333        # Find periods where we're in drawdown
334        running_max = self.equity_curve.cummax()
335        in_drawdown = self.equity_curve < running_max
336
337        max_duration = 0
338        current_duration = 0
339
340        for is_dd in in_drawdown:
341            if is_dd:
342                current_duration += 1
343                max_duration = max(max_duration, current_duration)
344            else:
345                current_duration = 0
346
347        return max_duration
348
349    @property
350    def buy_hold_return(self) -> float:
351        """Buy & hold return as percentage."""
352        if self.buy_hold_curve.empty:
353            return 0.0
354        first = self.buy_hold_curve.iloc[0]
355        last = self.buy_hold_curve.iloc[-1]
356        if first == 0:
357            return 0.0
358        return ((last - first) / first) * 100
359
360    @property
361    def vs_buy_hold(self) -> float:
362        """Strategy outperformance vs buy & hold (percentage points)."""
363        return self.net_profit_pct - self.buy_hold_return
364
365    @property
366    def calmar_ratio(self) -> float:
367        """Calmar ratio (annualized return / max drawdown)."""
368        if self.max_drawdown == 0:
369            return float("inf") if self.net_profit_pct > 0 else 0.0
370        # Annualize return (assuming 252 trading days)
371        trading_days = len(self.equity_curve)
372        if trading_days == 0:
373            return 0.0
374        annual_return = self.net_profit_pct * (252 / trading_days)
375        return annual_return / abs(self.max_drawdown)
376
377    # === Export Methods ===
378
379    @property
380    def trades_df(self) -> pd.DataFrame:
381        """Get trades as DataFrame."""
382        if not self.trades:
383            return pd.DataFrame(
384                columns=[
385                    "entry_time",
386                    "entry_price",
387                    "exit_time",
388                    "exit_price",
389                    "side",
390                    "shares",
391                    "commission",
392                    "profit",
393                    "profit_pct",
394                    "duration",
395                ]
396            )
397        return pd.DataFrame([t.to_dict() for t in self.trades])
398
399    def to_dict(self) -> dict[str, Any]:
400        """
401        Export results to dictionary.
402
403        Compatible with TradingView/Mathieu2301 format.
404        """
405        return {
406            # Identification
407            "symbol": self.symbol,
408            "period": self.period,
409            "interval": self.interval,
410            "strategy_name": self.strategy_name,
411            # Configuration
412            "initial_capital": self.initial_capital,
413            "commission": self.commission,
414            # Summary
415            "net_profit": round(self.net_profit, 2),
416            "net_profit_pct": round(self.net_profit_pct, 2),
417            "final_equity": round(self.final_equity, 2),
418            # Trade Statistics
419            "total_trades": self.total_trades,
420            "winning_trades": self.winning_trades,
421            "losing_trades": self.losing_trades,
422            "win_rate": round(self.win_rate, 2),
423            "profit_factor": round(self.profit_factor, 2) if self.profit_factor != float("inf") else "inf",
424            "avg_trade": round(self.avg_trade, 2),
425            "avg_winning_trade": round(self.avg_winning_trade, 2),
426            "avg_losing_trade": round(self.avg_losing_trade, 2),
427            "max_consecutive_wins": self.max_consecutive_wins,
428            "max_consecutive_losses": self.max_consecutive_losses,
429            # Risk Metrics
430            "sharpe_ratio": round(self.sharpe_ratio, 2) if not np.isnan(self.sharpe_ratio) else None,
431            "sortino_ratio": round(self.sortino_ratio, 2) if not np.isnan(self.sortino_ratio) and self.sortino_ratio != float("inf") else None,
432            "calmar_ratio": round(self.calmar_ratio, 2) if self.calmar_ratio != float("inf") else None,
433            "max_drawdown": round(self.max_drawdown, 2),
434            "max_drawdown_duration": self.max_drawdown_duration,
435            # Comparison
436            "buy_hold_return": round(self.buy_hold_return, 2),
437            "vs_buy_hold": round(self.vs_buy_hold, 2),
438        }
439
440    def summary(self) -> str:
441        """
442        Generate human-readable performance summary.
443
444        Returns:
445            Formatted summary string.
446        """
447        d = self.to_dict()
448
449        lines = [
450            "=" * 60,
451            f"BACKTEST RESULTS: {d['symbol']} ({d['strategy_name']})",
452            "=" * 60,
453            f"Period: {d['period']} | Interval: {d['interval']}",
454            f"Initial Capital: {d['initial_capital']:,.2f} TL",
455            f"Commission: {d['commission']*100:.2f}%",
456            "",
457            "--- PERFORMANCE ---",
458            f"Net Profit: {d['net_profit']:,.2f} TL ({d['net_profit_pct']:+.2f}%)",
459            f"Final Equity: {d['final_equity']:,.2f} TL",
460            f"Buy & Hold: {d['buy_hold_return']:+.2f}%",
461            f"vs B&H: {d['vs_buy_hold']:+.2f}%",
462            "",
463            "--- TRADE STATISTICS ---",
464            f"Total Trades: {d['total_trades']}",
465            f"Winning: {d['winning_trades']} | Losing: {d['losing_trades']}",
466            f"Win Rate: {d['win_rate']:.1f}%",
467            f"Profit Factor: {d['profit_factor']}",
468            f"Avg Trade: {d['avg_trade']:,.2f} TL",
469            f"Avg Winner: {d['avg_winning_trade']:,.2f} TL | Avg Loser: {d['avg_losing_trade']:,.2f} TL",
470            f"Max Consecutive Wins: {d['max_consecutive_wins']} | Losses: {d['max_consecutive_losses']}",
471            "",
472            "--- RISK METRICS ---",
473            f"Sharpe Ratio: {d['sharpe_ratio'] if d['sharpe_ratio'] else 'N/A'}",
474            f"Sortino Ratio: {d['sortino_ratio'] if d['sortino_ratio'] else 'N/A'}",
475            f"Calmar Ratio: {d['calmar_ratio'] if d['calmar_ratio'] else 'N/A'}",
476            f"Max Drawdown: {d['max_drawdown']:.2f}%",
477            f"Max DD Duration: {d['max_drawdown_duration']} days",
478            "=" * 60,
479        ]
480
481        return "\n".join(lines)
482
483
484class Backtest:
485    """
486    Backtest engine for evaluating trading strategies.
487
488    Runs a strategy function over historical data and calculates
489    comprehensive performance metrics.
490
491    Attributes:
492        symbol: Stock symbol to backtest.
493        strategy: Strategy function to evaluate.
494        period: Historical data period.
495        interval: Data interval (e.g., "1d", "1h").
496        capital: Initial capital.
497        commission: Commission rate per trade (e.g., 0.001 = 0.1%).
498        indicators: List of indicators to calculate.
499
500    Examples:
501        >>> def my_strategy(candle, position, indicators):
502        ...     if indicators['rsi'] < 30:
503        ...         return 'BUY'
504        ...     elif indicators['rsi'] > 70:
505        ...         return 'SELL'
506        ...     return 'HOLD'
507
508        >>> bt = Backtest("THYAO", my_strategy, period="1y")
509        >>> result = bt.run()
510        >>> print(result.sharpe_ratio)
511    """
512
513    # Indicator period warmup
514    WARMUP_PERIOD = 50
515
516    def __init__(
517        self,
518        symbol: str,
519        strategy: StrategyFunc,
520        period: str = "1y",
521        interval: str = "1d",
522        capital: float = 100_000.0,
523        commission: float = 0.001,
524        indicators: list[str] | None = None,
525        slippage: float = 0.0,  # Future use
526    ):
527        """
528        Initialize Backtest.
529
530        Args:
531            symbol: Stock symbol (e.g., "THYAO").
532            strategy: Strategy function with signature:
533                      strategy(candle, position, indicators) -> 'BUY'|'SELL'|'HOLD'|None
534            period: Historical data period (1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y).
535            interval: Data interval (1m, 5m, 15m, 30m, 1h, 4h, 1d).
536            capital: Initial capital in TL.
537            commission: Commission rate per trade (0.001 = 0.1%).
538            indicators: List of indicators to calculate. Options:
539                       'rsi', 'rsi_7', 'sma_20', 'sma_50', 'sma_200',
540                       'ema_12', 'ema_26', 'ema_50', 'macd', 'bollinger',
541                       'atr', 'atr_20', 'stochastic', 'adx'
542            slippage: Slippage per trade (for future use).
543        """
544        self.symbol = symbol.upper()
545        self.strategy = strategy
546        self.period = period
547        self.interval = interval
548        self.capital = capital
549        self.commission = commission
550        self.indicators = indicators or ["rsi", "sma_20", "ema_12", "macd"]
551        self.slippage = slippage
552
553        # Strategy name for reporting
554        self._strategy_name = getattr(strategy, "__name__", "custom_strategy")
555
556        # Data storage
557        self._df: pd.DataFrame | None = None
558        self._df_with_indicators: pd.DataFrame | None = None
559
560    def _load_data(self) -> pd.DataFrame:
561        """Load historical data from Ticker."""
562        from borsapy.ticker import Ticker
563
564        ticker = Ticker(self.symbol)
565        df = ticker.history(period=self.period, interval=self.interval)
566
567        if df is None or df.empty:
568            raise ValueError(f"No historical data available for {self.symbol}")
569
570        return df
571
572    def _calculate_indicators(self, df: pd.DataFrame) -> pd.DataFrame:
573        """Add indicator columns to DataFrame."""
574        from borsapy.technical import (
575            calculate_adx,
576            calculate_atr,
577            calculate_bollinger_bands,
578            calculate_ema,
579            calculate_macd,
580            calculate_rsi,
581            calculate_sma,
582            calculate_stochastic,
583        )
584
585        result = df.copy()
586
587        for ind in self.indicators:
588            ind_lower = ind.lower()
589
590            # RSI variants
591            if ind_lower == "rsi":
592                result["rsi"] = calculate_rsi(df, period=14)
593            elif ind_lower.startswith("rsi_"):
594                try:
595                    period = int(ind_lower.split("_")[1])
596                    result[f"rsi_{period}"] = calculate_rsi(df, period=period)
597                except (IndexError, ValueError):
598                    pass
599
600            # SMA variants
601            elif ind_lower.startswith("sma_"):
602                try:
603                    period = int(ind_lower.split("_")[1])
604                    result[f"sma_{period}"] = calculate_sma(df, period=period)
605                except (IndexError, ValueError):
606                    pass
607
608            # EMA variants
609            elif ind_lower.startswith("ema_"):
610                try:
611                    period = int(ind_lower.split("_")[1])
612                    result[f"ema_{period}"] = calculate_ema(df, period=period)
613                except (IndexError, ValueError):
614                    pass
615
616            # MACD
617            elif ind_lower == "macd":
618                macd_df = calculate_macd(df)
619                result["macd"] = macd_df["MACD"]
620                result["macd_signal"] = macd_df["Signal"]
621                result["macd_histogram"] = macd_df["Histogram"]
622
623            # Bollinger Bands
624            elif ind_lower in ("bollinger", "bb"):
625                bb_df = calculate_bollinger_bands(df)
626                result["bb_upper"] = bb_df["BB_Upper"]
627                result["bb_middle"] = bb_df["BB_Middle"]
628                result["bb_lower"] = bb_df["BB_Lower"]
629
630            # ATR variants
631            elif ind_lower == "atr":
632                result["atr"] = calculate_atr(df, period=14)
633            elif ind_lower.startswith("atr_"):
634                try:
635                    period = int(ind_lower.split("_")[1])
636                    result[f"atr_{period}"] = calculate_atr(df, period=period)
637                except (IndexError, ValueError):
638                    pass
639
640            # Stochastic
641            elif ind_lower in ("stochastic", "stoch"):
642                stoch_df = calculate_stochastic(df)
643                result["stoch_k"] = stoch_df["Stoch_K"]
644                result["stoch_d"] = stoch_df["Stoch_D"]
645
646            # ADX
647            elif ind_lower == "adx":
648                result["adx"] = calculate_adx(df, period=14)
649
650        return result
651
652    def _get_indicators_at(self, idx: int) -> dict[str, float]:
653        """Get indicator values at specific index."""
654        if self._df_with_indicators is None:
655            return {}
656
657        row = self._df_with_indicators.iloc[idx]
658        indicators = {}
659
660        # Extract all non-OHLCV columns as indicators
661        exclude_cols = {"Open", "High", "Low", "Close", "Volume", "Adj Close"}
662
663        for col in self._df_with_indicators.columns:
664            if col not in exclude_cols:
665                val = row[col]
666                if pd.notna(val):
667                    indicators[col] = float(val)
668
669        return indicators
670
671    def _build_candle(self, idx: int) -> dict[str, Any]:
672        """Build candle dict from DataFrame row."""
673        if self._df is None:
674            return {}
675
676        row = self._df.iloc[idx]
677        timestamp = self._df.index[idx]
678
679        if isinstance(timestamp, pd.Timestamp):
680            timestamp = timestamp.to_pydatetime()
681
682        return {
683            "timestamp": timestamp,
684            "open": float(row["Open"]),
685            "high": float(row["High"]),
686            "low": float(row["Low"]),
687            "close": float(row["Close"]),
688            "volume": float(row.get("Volume", 0)) if "Volume" in row else 0,
689            "_index": idx,
690        }
691
692    def run(self) -> BacktestResult:
693        """
694        Run the backtest.
695
696        Returns:
697            BacktestResult with all performance metrics.
698
699        Raises:
700            ValueError: If no data available for symbol.
701        """
702        # Load data
703        self._df = self._load_data()
704        self._df_with_indicators = self._calculate_indicators(self._df)
705
706        # Initialize state
707        cash = self.capital
708        position: Position = None
709        shares = 0.0
710        trades: list[Trade] = []
711        current_trade: Trade | None = None
712
713        # Track equity curve
714        equity_values = []
715        dates = []
716
717        # Buy & hold tracking
718        initial_price = self._df["Close"].iloc[self.WARMUP_PERIOD]
719        bh_shares = self.capital / initial_price
720
721        # Run simulation
722        for idx in range(self.WARMUP_PERIOD, len(self._df)):
723            candle = self._build_candle(idx)
724            indicators = self._get_indicators_at(idx)
725            price = candle["close"]
726            timestamp = candle["timestamp"]
727
728            # Get strategy signal
729            try:
730                signal = self.strategy(candle, position, indicators)
731            except Exception:
732                signal = "HOLD"
733
734            # Execute trades
735            if signal == "BUY" and position is None:
736                # Calculate shares to buy (use all available cash)
737                entry_commission = cash * self.commission
738                available = cash - entry_commission
739                shares = available / price
740
741                current_trade = Trade(
742                    entry_time=timestamp,
743                    entry_price=price,
744                    side="long",
745                    shares=shares,
746                    commission=entry_commission,
747                )
748
749                cash = 0.0
750                position = "long"
751
752            elif signal == "SELL" and position == "long" and current_trade is not None:
753                # Close position
754                exit_value = shares * price
755                exit_commission = exit_value * self.commission
756
757                current_trade.exit_time = timestamp
758                current_trade.exit_price = price
759                current_trade.commission += exit_commission
760
761                trades.append(current_trade)
762
763                cash = exit_value - exit_commission
764                shares = 0.0
765                position = None
766                current_trade = None
767
768            # Track equity
769            if position == "long":
770                equity = shares * price
771            else:
772                equity = cash
773
774            equity_values.append(equity)
775            dates.append(timestamp)
776
777        # Close any open position at end
778        if position == "long" and current_trade is not None:
779            final_price = self._df["Close"].iloc[-1]
780            exit_value = shares * final_price
781            exit_commission = exit_value * self.commission
782
783            current_trade.exit_time = self._df.index[-1]
784            if isinstance(current_trade.exit_time, pd.Timestamp):
785                current_trade.exit_time = current_trade.exit_time.to_pydatetime()
786            current_trade.exit_price = final_price
787            current_trade.commission += exit_commission
788
789            trades.append(current_trade)
790
791        # Build curves
792        equity_curve = pd.Series(equity_values, index=pd.DatetimeIndex(dates))
793
794        # Calculate drawdown curve
795        running_max = equity_curve.cummax()
796        drawdown_curve = (equity_curve - running_max) / running_max
797
798        # Buy & hold curve
799        bh_values = self._df["Close"].iloc[self.WARMUP_PERIOD:] * bh_shares
800        buy_hold_curve = pd.Series(bh_values.values, index=pd.DatetimeIndex(dates))
801
802        return BacktestResult(
803            symbol=self.symbol,
804            period=self.period,
805            interval=self.interval,
806            strategy_name=self._strategy_name,
807            initial_capital=self.capital,
808            commission=self.commission,
809            trades=trades,
810            equity_curve=equity_curve,
811            drawdown_curve=drawdown_curve,
812            buy_hold_curve=buy_hold_curve,
813        )
814
815
816def backtest(
817    symbol: str,
818    strategy: StrategyFunc,
819    period: str = "1y",
820    interval: str = "1d",
821    capital: float = 100_000.0,
822    commission: float = 0.001,
823    indicators: list[str] | None = None,
824) -> BacktestResult:
825    """
826    Run a backtest with a single function call.
827
828    Convenience function that creates a Backtest instance and runs it.
829
830    Args:
831        symbol: Stock symbol (e.g., "THYAO").
832        strategy: Strategy function with signature:
833                  strategy(candle, position, indicators) -> 'BUY'|'SELL'|'HOLD'|None
834        period: Historical data period.
835        interval: Data interval.
836        capital: Initial capital.
837        commission: Commission rate.
838        indicators: List of indicators to calculate.
839
840    Returns:
841        BacktestResult with all performance metrics.
842
843    Examples:
844        >>> def rsi_strategy(candle, position, indicators):
845        ...     if indicators.get('rsi', 50) < 30 and position is None:
846        ...         return 'BUY'
847        ...     elif indicators.get('rsi', 50) > 70 and position == 'long':
848        ...         return 'SELL'
849        ...     return 'HOLD'
850
851        >>> result = bp.backtest("THYAO", rsi_strategy, period="1y")
852        >>> print(f"Net Profit: {result.net_profit_pct:.2f}%")
853        >>> print(f"Sharpe: {result.sharpe_ratio:.2f}")
854    """
855    bt = Backtest(
856        symbol=symbol,
857        strategy=strategy,
858        period=period,
859        interval=interval,
860        capital=capital,
861        commission=commission,
862        indicators=indicators,
863    )
864    return bt.run()