ivolatility-backtesting 1.0.0__tar.gz → 1.1.0__tar.gz

{ivolatility_backtesting-1.0.0 → ivolatility_backtesting-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ivolatility_backtesting
-Version: 1.0.0
+Version: 1.1.0
 Summary: A universal backtesting framework for financial strategies using the IVolatility API.
 Author-email: IVolatility <support@ivolatility.com>
 Project-URL: Homepage, https://ivolatility.com

{ivolatility_backtesting-1.0.0 → ivolatility_backtesting-1.1.0}/ivolatility_backtesting/ivolatility_backtesting.py

@@ -1,6 +1,12 @@
 """
-ivolatility_backtesting.py
-Universal Backtest Framework with One-Command Runner
+ivolatility_backtesting.py - UPDATED VERSION
+Universal Backtest Framework with API Response Normalization
+
+NEW FEATURES:
+- APIHelper class for automatic response normalization
+- Handles both dict and DataFrame responses from IVolatility API
+- Safe data extraction with proper error handling
+- Unified interface for all API calls
 
 Usage:
     from ivolatility_backtesting import *
@@ -8,8 +14,10 @@ Usage:
     # Initialize API once
     init_api(os.getenv("API_KEY"))
     
-    CONFIG = {...}
-    analyzer = run_backtest(my_strategy, CONFIG)
+    # Use API helper for normalized responses
+    data = api_call('/equities/eod/stock-prices', symbol='AAPL', from_='2024-01-01')
+    if data:  # Always returns dict or None
+        df = pd.DataFrame(data)
 """
 
 import pandas as pd
@@ -26,21 +34,96 @@ plt.rcParams['figure.figsize'] = (15, 8)
 
 
 # ============================================================
-# GLOBAL API MANAGER
+# API HELPER - NEW!
 # ============================================================
-class APIManager:
+class APIHelper:
     """
-    Centralized API key management for IVolatility API
+    Helper class for normalized API responses
+    Automatically handles both dict and DataFrame responses
+    """
+    
+    @staticmethod
+    def normalize_response(response, debug=False):
+        """
+        Convert API response to consistent dict format
+        
+        Args:
+            response: API response (dict, DataFrame, or other)
+            debug: Print debug information
+        
+        Returns:
+            dict with 'data' key containing list of records, or None if invalid
+        """
+        if response is None:
+            if debug:
+                print("[APIHelper] Response is None")
+            return None
+        
+        # Case 1: Already a dict with 'data' key
+        if isinstance(response, dict):
+            if 'data' in response:
+                if debug:
+                    print(f"[APIHelper] Dict response with {len(response['data'])} records")
+                return response
+            else:
+                if debug:
+                    print("[APIHelper] Dict response without 'data' key")
+                return None
+        
+        # Case 2: DataFrame - convert to dict
+        if isinstance(response, pd.DataFrame):
+            if response.empty:
+                if debug:
+                    print("[APIHelper] Empty DataFrame")
+                return None
+            
+            records = response.to_dict('records')
+            if debug:
+                print(f"[APIHelper] Converted DataFrame to dict with {len(records)} records")
+            return {'data': records, 'status': 'success'}
+        
+        # Case 3: Unknown type
+        if debug:
+            print(f"[APIHelper] Unexpected response type: {type(response)}")
+        return None
     
-    Usage:
-        from ivolatility_backtesting import init_api, get_api_method
+    @staticmethod
+    def safe_dataframe(response, debug=False):
+        """
+        Safely convert API response to DataFrame
         
-        # Initialize once at the start
-        init_api(os.getenv("API_KEY"))
+        Args:
+            response: API response (any type)
+            debug: Print debug information
         
-        # Use anywhere in your code
-        getOptionsData = get_api_method('/equities/eod/stock-opts-by-param')
-        data = getOptionsData(symbol='SPY', tradeDate='2024-01-01', ...)
+        Returns:
+            pandas DataFrame or empty DataFrame if invalid
+        """
+        normalized = APIHelper.normalize_response(response, debug=debug)
+        
+        if normalized is None or 'data' not in normalized:
+            if debug:
+                print("[APIHelper] Cannot create DataFrame - no valid data")
+            return pd.DataFrame()
+        
+        try:
+            df = pd.DataFrame(normalized['data'])
+            if debug:
+                print(f"[APIHelper] Created DataFrame with shape {df.shape}")
+            return df
+        except Exception as e:
+            if debug:
+                print(f"[APIHelper] DataFrame creation failed: {e}")
+            return pd.DataFrame()
+
+
+# ============================================================
+# GLOBAL API MANAGER (Updated)
+# ============================================================
+class APIManager:
+    """
+    Centralized API key management for IVolatility API
+    Now includes response normalization
     """
     _api_key = None
     _methods = {}
@@ -56,17 +139,8 @@ class APIManager:
     
     @classmethod
     def get_method(cls, endpoint):
-        """
-        Get API method with automatic key injection
-        
-        Args:
-            endpoint: API endpoint path (e.g. '/equities/eod/stock-opts-by-param')
-        
-        Returns:
-            Callable API method
-        """
+        """Get API method with automatic key injection"""
         if cls._api_key is None:
-            # Auto-initialize from environment if not set
             api_key = os.getenv("API_KEY")
             if not api_key:
                 raise ValueError(
@@ -74,9 +148,7 @@ class APIManager:
                 )
             cls.initialize(api_key)
         
-        # Cache methods to avoid recreation
         if endpoint not in cls._methods:
-            # Re-set login params before creating method
             ivol.setLoginParams(apiKey=cls._api_key)
             cls._methods[endpoint] = ivol.setMethod(endpoint)
         
@@ -88,56 +160,80 @@ class APIManager:
         return cls._api_key is not None
 
 
-# Public API functions
+# Public API functions (Updated)
 def init_api(api_key=None):
-    """
-    Initialize IVolatility API with key
-    
-    Args:
-        api_key: API key string. If None, tries to load from API_KEY env variable
-    
-    Example:
-        init_api("your-api-key")
-        # or
-        init_api()  # Auto-loads from environment
-    """
+    """Initialize IVolatility API with key"""
     if api_key is None:
         api_key = os.getenv("API_KEY")
     APIManager.initialize(api_key)
 
 
 def get_api_method(endpoint):
+    """Get API method for specified endpoint"""
+    return APIManager.get_method(endpoint)
+
+
+def api_call(endpoint, debug=False, **kwargs):
     """
-    Get API method for specified endpoint
+    Make API call with automatic response normalization
     
     Args:
         endpoint: API endpoint path
+        debug: Enable debug output
+        **kwargs: API parameters
     
     Returns:
-        Callable API method with key already configured
+        dict with 'data' key (normalized format) or None if error
     
     Example:
-        getOptionsData = get_api_method('/equities/eod/stock-opts-by-param')
-        data = getOptionsData(symbol='SPY', tradeDate='2024-01-01', cp='C')
+        # Old way (manual handling):
+        method = get_api_method('/equities/eod/stock-prices')
+        response = method(symbol='AAPL', from_='2024-01-01')
+        if isinstance(response, pd.DataFrame):
+            df = response
+        elif isinstance(response, dict):
+            df = pd.DataFrame(response['data'])
+        
+        # New way (automatic):
+        data = api_call('/equities/eod/stock-prices', symbol='AAPL', from_='2024-01-01')
+        if data:
+            df = pd.DataFrame(data['data'])
     """
-    return APIManager.get_method(endpoint)
+    try:
+        method = get_api_method(endpoint)
+        response = method(**kwargs)
+        
+        normalized = APIHelper.normalize_response(response, debug=debug)
+        
+        if normalized is None and debug:
+            print(f"[api_call] Failed to get valid data from {endpoint}")
+            print(f"[api_call] Parameters: {kwargs}")
+        
+        return normalized
+    
+    except Exception as e:
+        if debug:
+            print(f"[api_call] Exception: {e}")
+            print(f"[api_call] Endpoint: {endpoint}")
+            print(f"[api_call] Parameters: {kwargs}")
+        return None
 
 
+# ============================================================
+# BACKTEST RESULTS (Unchanged)
+# ============================================================
 class BacktestResults:
-    """
-    Universal container for backtest results
-    ANY strategy must return this format
-    """
+    """Universal container for backtest results"""
     def __init__(self, 
-                 equity_curve,           # List of equity values
-                 equity_dates,           # List of dates (matching equity_curve)
-                 trades,                 # List of dicts with trade info
-                 initial_capital,        # Starting capital
-                 config,                 # Strategy config dict
-                 benchmark_prices=None,  # Optional: dict {date: price}
-                 benchmark_symbol='SPY', # Optional: benchmark ticker
-                 daily_returns=None,     # Optional: if not provided, calculated
-                 debug_info=None):       # Optional: debug information
+                 equity_curve,
+                 equity_dates,
+                 trades,
+                 initial_capital,
+                 config,
+                 benchmark_prices=None,
+                 benchmark_symbol='SPY',
+                 daily_returns=None,
+                 debug_info=None):
         
         self.equity_curve = equity_curve
         self.equity_dates = equity_dates
@@ -149,7 +245,6 @@ class BacktestResults:
         self.benchmark_symbol = benchmark_symbol
         self.debug_info = debug_info if debug_info else []
         
-        # Calculate daily returns if not provided
         if daily_returns is None and len(equity_curve) > 1:
             self.daily_returns = [
                 (equity_curve[i] - equity_curve[i-1]) / equity_curve[i-1]
@@ -158,7 +253,6 @@ class BacktestResults:
         else:
             self.daily_returns = daily_returns if daily_returns else []
         
-        # Calculate max drawdown
         self.max_drawdown = self._calculate_max_drawdown()
     
     def _calculate_max_drawdown(self):
@@ -169,11 +263,11 @@ class BacktestResults:
         return abs(np.min(drawdowns))
 
 
+# ============================================================
+# BACKTEST ANALYZER (Unchanged - same as before)
+# ============================================================
 class BacktestAnalyzer:
-    """
-    Universal metrics calculator
-    Works with any BacktestResults object
-    """
+    """Universal metrics calculator"""
     def __init__(self, results):
         self.results = results
         self.metrics = {}
@@ -186,13 +280,12 @@ class BacktestAnalyzer:
         self.metrics['total_pnl'] = r.final_capital - r.initial_capital
         self.metrics['total_return'] = (self.metrics['total_pnl'] / r.initial_capital) * 100
         
-        # CAGR - WITH PROTECTION AGAINST DIVISION BY ZERO
+        # CAGR with protection
         if len(r.equity_dates) > 0:
             start_date = min(r.equity_dates)
             end_date = max(r.equity_dates)
             days_diff = (end_date - start_date).days
             
-            # PROTECTION: если даты одинаковые или разница < 1 день
             if days_diff <= 0:
                 self.metrics['cagr'] = 0
                 self.metrics['show_cagr'] = False
@@ -438,6 +531,10 @@ class BacktestAnalyzer:
         return min(exposure_pct, 100.0)
 
 
+# ============================================================
+# RESULTS REPORTER, CHART GENERATOR, RESULTS EXPORTER
+# (All unchanged - same as before)
+# ============================================================
 class ResultsReporter:
     """Universal results printer"""
     
@@ -451,17 +548,15 @@ class ResultsReporter:
         print("="*80)
         print()
         
-        # PRINT DEBUG INFO IF AVAILABLE
         if hasattr(r, 'debug_info') and len(r.debug_info) > 0:
             print("DEBUG INFORMATION")
             print("-"*80)
-            for debug_msg in r.debug_info[:10]:  # First 10 messages
+            for debug_msg in r.debug_info[:10]:
                 print(debug_msg)
             if len(r.debug_info) > 10:
                 print(f"... and {len(r.debug_info) - 10} more debug messages")
             print()
         
-        # Profitability
         print("PROFITABILITY METRICS")
         print("-"*80)
         print(f"Initial Capital:        ${r.initial_capital:>15,.2f}")
@@ -475,7 +570,6 @@ class ResultsReporter:
                 print(f"Annualized Return:       {m['cagr']:>15.2f}%  (extrapolated to 1 year)")
         print()
         
-        # Risk
         print("RISK METRICS")
         print("-"*80)
         print(f"Sharpe Ratio:            {m['sharpe']:>15.2f}  (>1 good, >2 excellent)")
@@ -506,7 +600,6 @@ class ResultsReporter:
             print(f"Beta (vs {r.benchmark_symbol}):      {m['beta']:>15.2f}  (<1 defensive, >1 aggressive)")
             print(f"R^2 (vs {r.benchmark_symbol}):        {m['r_squared']:>15.2f}  (market correlation 0-1)")
         
-        # Warning for unrealistic results
         if abs(m['total_return']) > 200 or m['volatility'] > 150:
             print()
             print("UNREALISTIC RESULTS DETECTED:")
@@ -518,7 +611,6 @@ class ResultsReporter:
         
         print()
         
-        # Efficiency
         print("EFFICIENCY METRICS")
         print("-"*80)
         if m['recovery_factor'] != 0:
@@ -527,7 +619,6 @@ class ResultsReporter:
             print(f"Exposure Time:           {m['exposure_time']:>15.1f}%  (time in market)")
         print()
         
-        # Trading stats
         print("TRADING STATISTICS")
         print("-"*80)
         print(f"Total Trades:            {m['total_trades']:>15}")
@@ -671,14 +762,12 @@ class ResultsExporter:
             print("No trades to export")
             return
         
-        # Export trades
         trades_df = pd.DataFrame(r.trades)
         trades_df['entry_date'] = pd.to_datetime(trades_df['entry_date']).dt.strftime('%Y-%m-%d')
         trades_df['exit_date'] = pd.to_datetime(trades_df['exit_date']).dt.strftime('%Y-%m-%d')
         trades_df.to_csv(f'{prefix}_trades.csv', index=False)
         print(f"Trades exported: {prefix}_trades.csv")
         
-        # Export equity curve
         equity_df = pd.DataFrame({
             'date': pd.to_datetime(r.equity_dates).strftime('%Y-%m-%d'),
             'equity': r.equity_curve
@@ -686,7 +775,6 @@ class ResultsExporter:
         equity_df.to_csv(f'{prefix}_equity.csv', index=False)
         print(f"Equity exported: {prefix}_equity.csv")
         
-        # Export summary
         with open(f'{prefix}_summary.txt', 'w') as f:
             f.write("BACKTEST SUMMARY\n")
             f.write("="*70 + "\n\n")
@@ -707,7 +795,7 @@ class ResultsExporter:
 
 
 # ============================================================
-# ONE-COMMAND RUNNER
+# ONE-COMMAND RUNNER (Unchanged)
 # ============================================================
 def run_backtest(strategy_function, config, 
                  print_report=True,
@@ -715,36 +803,7 @@ def run_backtest(strategy_function, config,
                  export_results=True,
                  chart_filename='backtest_results.png',
                  export_prefix='backtest'):
-    """
-    Run complete backtest with one command
-    
-    Args:
-        strategy_function: Your strategy function that returns BacktestResults
-        config: Configuration dictionary for the strategy
-        print_report: Print full metrics report (default: True)
-        create_charts: Generate 6 charts (default: True)
-        export_results: Export to CSV files (default: True)
-        chart_filename: Name for chart file (default: 'backtest_results.png')
-        export_prefix: Prefix for exported files (default: 'backtest')
-    
-    Returns:
-        BacktestAnalyzer object with all metrics
-    
-    Example:
-        from ivolatility_backtesting import run_backtest
-        
-        def my_strategy(config):
-            # ... your strategy logic
-            return BacktestResults(...)
-        
-        CONFIG = {'initial_capital': 100000, ...}
-        
-        # Run everything with one command!
-        analyzer = run_backtest(my_strategy, CONFIG)
-        
-        # Access metrics
-        print(f"Sharpe: {analyzer.metrics['sharpe']:.2f}")
-    """
+    """Run complete backtest with one command"""
     
     print("="*80)
     print(" "*25 + "STARTING BACKTEST")
@@ -754,20 +813,16 @@ def run_backtest(strategy_function, config,
     print(f"Capital: ${config.get('initial_capital', 0):,.0f}")
     print("="*80 + "\n")
     
-    # Run strategy
     results = strategy_function(config)
     
-    # Calculate metrics
     print("\n[*] Calculating metrics...")
     analyzer = BacktestAnalyzer(results)
     analyzer.calculate_all_metrics()
     
-    # Print report
     if print_report:
         print("\n" + "="*80)
         ResultsReporter.print_full_report(analyzer)
     
-    # Create charts
     if create_charts and len(results.trades) > 0:
         print(f"\n[*] Creating charts: {chart_filename}")
         try:
@@ -778,7 +833,6 @@ def run_backtest(strategy_function, config,
     elif create_charts and len(results.trades) == 0:
         print("\n[!] No trades - skipping charts")
     
-    # Export results
     if export_results and len(results.trades) > 0:
         print(f"\n[*] Exporting results: {export_prefix}_*.csv")
         try:
@@ -792,22 +846,12 @@ def run_backtest(strategy_function, config,
     elif export_results and len(results.trades) == 0:
         print("\n[!] No trades - skipping export")
     
-    # Final summary
-    #print("\n" + "="*80)
-    #print(" "*30 + "SUMMARY")
-    #print("="*80)
-    #print(f"Total Return:    {analyzer.metrics['total_return']:>10.2f}%")
-    #print(f"Sharpe Ratio:    {analyzer.metrics['sharpe']:>10.2f}")
-    #print(f"Max Drawdown:    {analyzer.metrics['max_drawdown']:>10.2f}%")
-    #print(f"Win Rate:        {analyzer.metrics['win_rate']:>10.1f}%")
-    #print(f"Total Trades:    {analyzer.metrics['total_trades']:>10}")
-    #print(f"Profit Factor:   {analyzer.metrics['profit_factor']:>10.2f}")
-    #print("="*80)
-    
     return analyzer
 
 
-# Export all classes and functions
+# ============================================================
+# EXPORTS
+# ============================================================
 __all__ = [
     'BacktestResults',
     'BacktestAnalyzer', 
@@ -817,5 +861,7 @@ __all__ = [
     'run_backtest',
     'init_api',
     'get_api_method',
+    'api_call',           # NEW!
+    'APIHelper',          # NEW!
     'APIManager'
-]
+]

{ivolatility_backtesting-1.0.0 → ivolatility_backtesting-1.1.0}/ivolatility_backtesting.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ivolatility_backtesting
-Version: 1.0.0
+Version: 1.1.0
 Summary: A universal backtesting framework for financial strategies using the IVolatility API.
 Author-email: IVolatility <support@ivolatility.com>
 Project-URL: Homepage, https://ivolatility.com

{ivolatility_backtesting-1.0.0 → ivolatility_backtesting-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ivolatility_backtesting"
-version = "1.0.0"
+version = "1.1.0"
 description = "A universal backtesting framework for financial strategies using the IVolatility API."
 readme = "README.md"
 authors = [