stratpy-lib 0.1.0__tar.gz

stratpy_lib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 quantbirrd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stratpy_lib-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: stratpy-lib
+Version: 0.1.0
+Summary: A modular python library for building algorithmic trading strategies.
+Author-email: Albert Akinola <albert.akinola@outlook.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: yfinance
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# stratpy
+A modular Python library for building and testing algorithmic trading strategies quickly, without writing tons of code from scratch

stratpy_lib-0.1.0/README.md

@@ -0,0 +1,2 @@
+# stratpy
+A modular Python library for building and testing algorithmic trading strategies quickly, without writing tons of code from scratch

stratpy_lib-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "stratpy-lib"
+version = "0.1.0"
+authors = [
+  { name="Albert Akinola", email="albert.akinola@outlook.com" },
+]
+description = "A modular python library for building algorithmic trading strategies."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas",
+    "numpy",
+    "yfinance",
+    "matplotlib"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "build",
+    "twine"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

stratpy_lib-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stratpy_lib-0.1.0/src/stratpy/__init__.py

@@ -0,0 +1,37 @@
+"""
+Stratpy: A modular Python library for building and testing algorithmic trading strategies.
+"""
+
+__version__ = "0.1.0"
+
+# Import data functions
+from .data import data, clean
+
+# Import indicators
+from .indicators import sma, ema, macd, rsi, bb, atr, vwap
+
+# Import strategies (classes and legacy wrappers)
+from .strategies import BaseStrategy, MACrossover, RSIReversion, BollingerBreakout, mac_strategy, rsi_reversion
+
+# Import backtesting engine
+from .backtest import runstrat
+
+__all__ = [
+    "data",
+    "clean",
+    "sma",
+    "ema",
+    "macd",
+    "rsi",
+    "bb",
+    "atr",
+    "vwap",
+    "BaseStrategy",
+    "MACrossover",
+    "RSIReversion",
+    "BollingerBreakout",
+    "mac_strategy",
+    "rsi_reversion",
+    "runstrat",
+    "__version__",
+]

stratpy_lib-0.1.0/src/stratpy/backtest.py

@@ -0,0 +1,129 @@
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+from typing import Optional
+from .utils import validate_dataframe
+
+def runstrat(df: pd.DataFrame, column: str = 'Close', plot_path: Optional[str] = None) -> pd.DataFrame:
+    """
+    Simulates the strategy execution, prints performance metrics (including Sharpe Ratio
+    and Maximum Drawdown), and outputs a polished Matplotlib comparison graph.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame with historical price data and generated 'Signal' column.
+    column (str): The column containing asset prices. Defaults to 'Close'.
+    plot_path (Optional[str]): If provided, saves the performance plot to this file path.
+    
+    Returns:
+    pd.DataFrame: A copy of the input DataFrame containing returns and cumulative metrics.
+    
+    Raises:
+    ValueError: If 'Signal' or the specified price column is missing.
+    """
+    # Validate that both the price and Signal columns are present
+    validate_dataframe(df, [column, 'Signal'], "runstrat")
+    
+    df = df.copy()
+    
+    # 1. Calculate daily percentage changes of the underlying market
+    df['Market_Returns'] = df[column].pct_change()
+    
+    # 2. Calculate strategy returns (shift Signal by 1 to prevent look-ahead bias)
+    df['Strategy_Returns'] = df['Signal'].shift(1) * df['Market_Returns']
+    
+    # 3. Calculate cumulative returns starting at 1.0 (0% gain)
+    df['Cumulative_Market'] = (1 + df['Market_Returns'].fillna(0)).cumprod()
+    df['Cumulative_Strategy'] = (1 + df['Strategy_Returns'].fillna(0)).cumprod()
+    
+    # 4. Extract total returns (in percent)
+    total_market_return = (df['Cumulative_Market'].iloc[-1] - 1) * 100
+    total_strategy_return = (df['Cumulative_Strategy'].iloc[-1] - 1) * 100
+    
+    # 5. Calculate Annualized Sharpe Ratio (assuming risk-free rate of 0)
+    # Using 252 standard trading days to annualize the daily standard deviation
+    mkt_daily_ret = df['Market_Returns'].dropna()
+    strat_daily_ret = df['Strategy_Returns'].dropna()
+    
+    mkt_std = mkt_daily_ret.std()
+    strat_std = strat_daily_ret.std()
+    
+    with np.errstate(divide='ignore', invalid='ignore'):
+        market_sharpe = 0.0 if mkt_std == 0 or np.isnan(mkt_std) else (mkt_daily_ret.mean() / mkt_std) * np.sqrt(252)
+        strat_sharpe = 0.0 if strat_std == 0 or np.isnan(strat_std) else (strat_daily_ret.mean() / strat_std) * np.sqrt(252)
+    
+    # 6. Calculate Maximum Drawdown
+    cum_market = df['Cumulative_Market']
+    running_max_mkt = cum_market.cummax()
+    with np.errstate(divide='ignore', invalid='ignore'):
+        drawdown_mkt = np.where(running_max_mkt <= 0, 0.0, (cum_market / running_max_mkt) - 1.0)
+    max_dd_mkt = drawdown_mkt.min()
+    
+    cum_strat = df['Cumulative_Strategy']
+    running_max_strat = cum_strat.cummax()
+    with np.errstate(divide='ignore', invalid='ignore'):
+        drawdown_strat = np.where(running_max_strat <= 0, 0.0, (cum_strat / running_max_strat) - 1.0)
+    max_dd_strat = drawdown_strat.min()
+    
+    # --- Format & Print ASCII Output Table ---
+    mkt_ret_str = f"{total_market_return:+.2f}%"
+    strat_ret_str = f"{total_strategy_return:+.2f}%"
+    mkt_sharpe_str = f"{market_sharpe:.2f}"
+    strat_sharpe_str = f"{strat_sharpe:.2f}"
+    mkt_dd_str = f"{max_dd_mkt * 100:+.2f}%"
+    strat_dd_str = f"{max_dd_strat * 100:+.2f}%"
+    
+    print("\n" + "="*50)
+    print("            STRATPY BACKTEST RESULTS")
+    print("="*50)
+    print(f"{'Metric':<20}{'Market Buy & Hold':<18}{'Strategy':<12}")
+    print("-"*50)
+    print(f"{'Total Return':<20}{mkt_ret_str:<18}{strat_ret_str:<12}")
+    print(f"{'Sharpe Ratio':<20}{mkt_sharpe_str:<18}{strat_sharpe_str:<12}")
+    print(f"{'Max Drawdown':<20}{mkt_dd_str:<18}{strat_dd_str:<12}")
+    print("="*50 + "\n")
+    
+    # --- Plot the Results ---
+    fig, ax = plt.subplots(figsize=(12, 6), dpi=100)
+    
+    # Set a clean face color
+    ax.set_facecolor('#f8fafc')
+    
+    # Plot Market (semi-transparent gray/slate)
+    ax.plot(df.index, df['Cumulative_Market'], label='Market Buy & Hold', color='#94a3b8', alpha=0.8, linewidth=1.5)
+    
+    # Plot Strategy (bold, premium steel blue)
+    ax.plot(df.index, df['Cumulative_Strategy'], label='Stratpy Strategy', color='#0f766e', linewidth=2.5)
+    
+    # Set labels and title
+    ax.set_title('Stratpy: Cumulative Performance vs. Market Buy & Hold', fontsize=13, fontweight='bold', pad=15, color='#1e293b')
+    ax.set_xlabel('Date', fontsize=10, labelpad=10, color='#334155')
+    ax.set_ylabel('Growth of $1.00 (Cumulative Return)', fontsize=10, labelpad=10, color='#334155')
+    
+    # Format dates beautifully if DataFrame index is DatetimeIndex
+    if isinstance(df.index, pd.DatetimeIndex):
+        ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m-%d'))
+        fig.autofmt_xdate(rotation=30)
+    
+    # Add subtle dashed grids
+    ax.grid(True, linestyle='--', alpha=0.5, color='#cbd5e1')
+    
+    # Remove top and right borders for a cleaner modern aesthetic
+    for spine in ['top', 'right']:
+        ax.spines[spine].set_visible(False)
+    ax.spines['left'].set_color('#cbd5e1')
+    ax.spines['bottom'].set_color('#cbd5e1')
+    
+    # Configure premium looking legend
+    ax.legend(loc='upper left', frameon=True, facecolor='white', edgecolor='#e2e8f0', fontsize=9)
+    
+    plt.tight_layout()
+    
+    # Save image if path is provided
+    if plot_path:
+        plt.savefig(plot_path, dpi=150)
+        print(f"Stratpy: Performance plot saved successfully to: {plot_path}")
+        
+    plt.show()
+    
+    return df

stratpy_lib-0.1.0/src/stratpy/data.py

@@ -0,0 +1,76 @@
+import pandas as pd
+import yfinance as yf
+import os
+from typing import Union
+
+def data(ticker: str, period: str = '1y', interval: str = '1d') -> pd.DataFrame:
+    """
+    Pulls historical market data from Yahoo Finance.
+    
+    Parameters:
+    ticker (str): The stock or crypto ticker symbol (e.g., 'AAPL', 'BTC-USD').
+    period (str): The time period to pull (e.g., '1mo', '1y', 'max').
+    interval (str): The timeframe of the candles (e.g., '1d', '1h', '15m').
+    
+    Returns:
+    pd.DataFrame: A formatted pandas DataFrame containing Open, High, Low, Close, Volume.
+    
+    Raises:
+    ValueError: If ticker is empty or if no data was found for the ticker symbol.
+    """
+    if not ticker or not isinstance(ticker, str):
+        raise ValueError("Stratpy Error: Ticker symbol must be a non-empty string.")
+        
+    print(f"Stratpy: Fetching {period} of {interval} data for {ticker}...")
+    
+    stock = yf.Ticker(ticker)
+    df = stock.history(period=period, interval=interval)
+    
+    # Catch errors if the user types an invalid ticker symbol
+    if df.empty:
+        raise ValueError(
+            f"No data found for ticker '{ticker}'. Please check the symbol, period, "
+            f"and interval, and try again."
+        )
+        
+    return df
+
+
+def clean(file_path: Union[str, os.PathLike]) -> pd.DataFrame:
+    """
+    Loads a local CSV file, handles missing data, and sets the Date index.
+    
+    Parameters:
+    file_path (str or PathLike): The relative or absolute path to the CSV file.
+    
+    Returns:
+    pd.DataFrame: A cleaned pandas DataFrame ready for Stratpy indicators.
+    
+    Raises:
+    FileNotFoundError: If the file path does not point to a valid file.
+    ValueError: If the file path is empty or invalid.
+    """
+    if not file_path:
+        raise ValueError("Stratpy Error: File path must not be empty.")
+        
+    # Check if the file actually exists to prevent traceback errors
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"Stratpy Error: The file '{file_path}' was not found.")
+        
+    print(f"Stratpy: Cleaning {file_path}...")
+    df = pd.read_csv(file_path)
+    
+    # Forward fill missing values (carry the last known price forward), then drop any remaining NaNs
+    df = df.copy()
+    df = df.ffill().dropna()
+    
+    # Automatically find the date column, format it, and set it as the index
+    date_columns = ['Date', 'date', 'Datetime', 'datetime', 'Timestamp', 'timestamp']
+    for col in date_columns:
+        if col in df.columns:
+            df[col] = pd.to_datetime(df[col])
+            df.set_index(col, inplace=True)
+            break  # Stop searching once we find the date column
+            
+    return df
+

stratpy_lib-0.1.0/src/stratpy/indicators.py

@@ -0,0 +1,179 @@
+import pandas as pd
+import numpy as np
+from .utils import validate_dataframe
+
+def sma(df: pd.DataFrame, window: int = 20, column: str = 'Close') -> pd.DataFrame:
+    """
+    Calculates the Simple Moving Average (SMA) of a specified column.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing historical market data.
+    window (int): The number of periods to look back for the average.
+    column (str): The column to calculate the SMA on. Defaults to 'Close'.
+    
+    Returns:
+    pd.DataFrame: A new DataFrame copy with the added SMA column.
+    """
+    validate_dataframe(df, [column], "sma")
+    df = df.copy()
+    df[f'SMA_{window}'] = df[column].rolling(window=window).mean()
+    return df
+
+
+def ema(df: pd.DataFrame, window: int = 20, column: str = 'Close') -> pd.DataFrame:
+    """
+    Calculates the Exponential Moving Average (EMA) of a specified column.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing historical market data.
+    window (int): The decay/span period for the exponential average.
+    column (str): The column to calculate the EMA on. Defaults to 'Close'.
+    
+    Returns:
+    pd.DataFrame: A new DataFrame copy with the added EMA column.
+    """
+    validate_dataframe(df, [column], "ema")
+    df = df.copy()
+    df[f'EMA_{window}'] = df[column].ewm(span=window, adjust=False).mean()
+    return df
+
+
+def macd(df: pd.DataFrame, fast: int = 12, slow: int = 26, signal: int = 9, column: str = 'Close') -> pd.DataFrame:
+    """
+    Calculates the Moving Average Convergence Divergence (MACD) indicators.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing historical market data.
+    fast (int): The span for the fast EMA. Defaults to 12.
+    slow (int): The span for the slow EMA. Defaults to 26.
+    signal (int): The span for the signal line EMA. Defaults to 9.
+    column (str): The column to run MACD on. Defaults to 'Close'.
+    
+    Returns:
+    pd.DataFrame: A new DataFrame copy containing 'MACD', 'MACD_Signal', and 'MACD_Hist'.
+    """
+    validate_dataframe(df, [column], "macd")
+    df = df.copy()
+    
+    ema_fast = df[column].ewm(span=fast, adjust=False).mean()
+    ema_slow = df[column].ewm(span=slow, adjust=False).mean()
+    
+    df['MACD'] = ema_fast - ema_slow
+    df['MACD_Signal'] = df['MACD'].ewm(span=signal, adjust=False).mean()
+    df['MACD_Hist'] = df['MACD'] - df['MACD_Signal']
+    return df
+
+
+def rsi(df: pd.DataFrame, window: int = 14, column: str = 'Close') -> pd.DataFrame:
+    """
+    Calculates the Relative Strength Index (RSI) using standard pandas/numpy vectorization.
+    Safely handles division by zero if all values in the window are identical.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing historical market data.
+    window (int): The number of periods to look back for gain/loss averages.
+    column (str): The column to run RSI on. Defaults to 'Close'.
+    
+    Returns:
+    pd.DataFrame: A new DataFrame copy with the added RSI column.
+    """
+    validate_dataframe(df, [column], "rsi")
+    df = df.copy()
+    delta = df[column].diff()
+    
+    # Capture positive gains and negative losses separately
+    gain = (delta.where(delta > 0, 0.0)).rolling(window=window).mean()
+    loss = (-delta.where(delta < 0, 0.0)).rolling(window=window).mean()
+    
+    # Calculate RSI using total change to avoid division by zero (when loss is 0)
+    # Formula: RSI = 100 * gain / (gain + loss)
+    # If total change is 0 (price stayed flat), RSI is defined as 50.0.
+    with np.errstate(divide='ignore', invalid='ignore'):
+        total_change = gain + loss
+        df[f'RSI_{window}'] = np.where(
+            total_change == 0,
+            50.0,
+            100.0 * gain / total_change
+        )
+        
+    return df
+
+
+def bb(df: pd.DataFrame, window: int = 20, num_std: int = 2, column: str = 'Close') -> pd.DataFrame:
+    """
+    Calculates Bollinger Bands (Middle, Upper, and Lower).
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing historical market data.
+    window (int): The number of periods for the middle moving average.
+    num_std (int): The number of standard deviations to apply to upper and lower bands.
+    column (str): The column to run Bollinger Bands on. Defaults to 'Close'.
+    
+    Returns:
+    pd.DataFrame: A new DataFrame copy with 'BB_Mid', 'BB_Upper', and 'BB_Lower'.
+    """
+    validate_dataframe(df, [column], "bb")
+    df = df.copy()
+    
+    rolling_mean = df[column].rolling(window=window).mean()
+    rolling_std = df[column].rolling(window=window).std()
+    
+    df['BB_Mid'] = rolling_mean
+    df['BB_Upper'] = rolling_mean + (rolling_std * num_std)
+    df['BB_Lower'] = rolling_mean - (rolling_std * num_std)
+    return df
+
+
+def atr(df: pd.DataFrame, window: int = 14) -> pd.DataFrame:
+    """
+    Calculates the Average True Range (ATR), a measure of volatility.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing historical market data.
+    window (int): The period to smooth the True Range over.
+    
+    Returns:
+    pd.DataFrame: A new DataFrame copy with the added ATR column.
+    """
+    validate_dataframe(df, ['High', 'Low', 'Close'], "atr")
+    df = df.copy()
+    
+    high_low = df['High'] - df['Low']
+    high_close = np.abs(df['High'] - df['Close'].shift())
+    low_close = np.abs(df['Low'] - df['Close'].shift())
+    
+    # Calculate True Range as the maximum of three metrics
+    ranges = pd.concat([high_low, high_close, low_close], axis=1)
+    true_range = np.max(ranges, axis=1)
+    
+    df[f'ATR_{window}'] = true_range.rolling(window=window).mean()
+    return df
+
+
+def vwap(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Calculates the Volume Weighted Average Price (VWAP).
+    Safely handles division by zero if total volume is zero.
+    
+    Parameters:
+    df (pd.DataFrame): DataFrame containing historical market data.
+    
+    Returns:
+    pd.DataFrame: A new DataFrame copy with the added 'VWAP' column.
+    """
+    validate_dataframe(df, ['High', 'Low', 'Close', 'Volume'], "vwap")
+    df = df.copy()
+    
+    typical_price = (df['High'] + df['Low'] + df['Close']) / 3
+    cum_volume = df['Volume'].cumsum()
+    
+    # Safely divide typical price sum by cumulative volume
+    with np.errstate(divide='ignore', invalid='ignore'):
+        df['VWAP'] = np.where(
+            cum_volume == 0,
+            np.nan,
+            (typical_price * df['Volume']).cumsum() / cum_volume
+        )
+        
+    return df
+

stratpy_lib-0.1.0/src/stratpy/strategies.py

@@ -0,0 +1,161 @@
+import pandas as pd
+import numpy as np
+from abc import ABC, abstractmethod
+from .utils import validate_dataframe
+from .indicators import bb, rsi
+
+class BaseStrategy(ABC):
+    """
+    Abstract Base Class for all trading strategies.
+    
+    All strategy implementations must define the `generate_signals` method.
+    """
+    
+    @abstractmethod
+    def generate_signals(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Calculates indicators and generates buy (1), sell/short (-1), or hold (0) signals.
+        
+        Parameters:
+        df (pd.DataFrame): DataFrame containing historical market data.
+        
+        Returns:
+        pd.DataFrame: A copy of the DataFrame with the 'Signal' column.
+        """
+        pass
+
+    def __call__(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Allows the strategy instance to be invoked directly on a DataFrame.
+        For example:
+            strategy = MACrossover()
+            df = strategy(df)
+        """
+        return self.generate_signals(df)
+
+
+class MACrossover(BaseStrategy):
+    """
+    Moving Average Crossover Strategy.
+    
+    Buys (Signal = 1) when the short moving average crosses ABOVE the long moving average.
+    Sells/Shorts (Signal = -1) when the short moving average crosses BELOW the long moving average.
+    """
+    def __init__(self, short_window: int = 20, long_window: int = 50, column: str = 'Close'):
+        self.short_window = short_window
+        self.long_window = long_window
+        self.column = column
+
+    def generate_signals(self, df: pd.DataFrame) -> pd.DataFrame:
+        validate_dataframe(df, [self.column], self.__class__.__name__)
+        df = df.copy()
+        
+        # Calculate moving averages
+        sma_short = df[self.column].rolling(window=self.short_window).mean()
+        sma_long = df[self.column].rolling(window=self.long_window).mean()
+        
+        # Generate raw crossover signals
+        df['Signal'] = np.where(sma_short > sma_long, 1, -1)
+        
+        # Set signal to 0 during the initial warm-up period (where averages are NaN)
+        df.loc[sma_long.isna() | sma_short.isna(), 'Signal'] = 0
+        
+        return df
+
+
+class RSIReversion(BaseStrategy):
+    """
+    RSI Mean Reversion Strategy.
+    
+    Buys (Signal = 1) when RSI falls below the lower bound (oversold).
+    Sells/Shorts (Signal = -1) when RSI rises above the upper bound (overbought).
+    """
+    def __init__(self, lower_bound: int = 30, upper_bound: int = 70, column: str = 'Close', window: int = 14):
+        self.lower_bound = lower_bound
+        self.upper_bound = upper_bound
+        self.column = column
+        self.window = window
+
+    def generate_signals(self, df: pd.DataFrame) -> pd.DataFrame:
+        validate_dataframe(df, [self.column], self.__class__.__name__)
+        df = df.copy()
+        
+        # Check if the RSI column is present, if not compute it
+        rsi_col = f'RSI_{self.window}'
+        if rsi_col not in df.columns:
+            df = rsi(df, window=self.window, column=self.column)
+            
+        df['Signal'] = 0
+        df.loc[df[rsi_col] < self.lower_bound, 'Signal'] = 1
+        df.loc[df[rsi_col] > self.upper_bound, 'Signal'] = -1
+        
+        # Forward fill the signals so we carry the active position forward
+        df['Signal'] = df['Signal'].replace(0, np.nan).ffill().fillna(0).astype(int)
+        
+        # Set signal to 0 during the initial warm-up period (where RSI is NaN)
+        df.loc[df[rsi_col].isna(), 'Signal'] = 0
+        
+        return df
+
+
+class BollingerBreakout(BaseStrategy):
+    """
+    Bollinger Bands Breakout Strategy.
+    
+    Buys (Signal = 1) when the price closes ABOVE the upper Bollinger Band.
+    Sells/Shorts (Signal = -1) when the price closes BELOW the lower Bollinger Band.
+    """
+    def __init__(self, window: int = 20, num_std: int = 2, column: str = 'Close'):
+        self.window = window
+        self.num_std = num_std
+        self.column = column
+
+    def generate_signals(self, df: pd.DataFrame) -> pd.DataFrame:
+        validate_dataframe(df, [self.column], self.__class__.__name__)
+        df = df.copy()
+        
+        # Check if Bollinger Bands are present, if not compute them
+        if 'BB_Upper' not in df.columns or 'BB_Lower' not in df.columns:
+            df = bb(df, window=self.window, num_std=self.num_std, column=self.column)
+            
+        df['Signal'] = 0
+        df.loc[df[self.column] > df['BB_Upper'], 'Signal'] = 1
+        df.loc[df[self.column] < df['BB_Lower'], 'Signal'] = -1
+        
+        # Forward fill the signals
+        df['Signal'] = df['Signal'].replace(0, np.nan).ffill().fillna(0).astype(int)
+        
+        # Set signal to 0 during the initial warm-up period (where bands are NaN)
+        df.loc[df['BB_Upper'].isna() | df['BB_Lower'].isna(), 'Signal'] = 0
+        
+        return df
+
+
+# --- Legacy Functional Wrappers (Backward Compatibility) ---
+
+def mac_strategy(df: pd.DataFrame, short_window: int = 20, long_window: int = 50, column: str = 'Close') -> pd.DataFrame:
+    """
+    Legacy wrapper for Moving Average Crossover Strategy.
+    """
+    return MACrossover(short_window=short_window, long_window=long_window, column=column).generate_signals(df)
+
+
+def rsi_reversion(df: pd.DataFrame, rsi_col: str, lower_bound: int = 30, upper_bound: int = 70) -> pd.DataFrame:
+    """
+    Legacy wrapper for RSI Mean Reversion Strategy.
+    Assumes that the RSI values have already been pre-calculated in `rsi_col`.
+    """
+    validate_dataframe(df, [rsi_col], "rsi_reversion")
+    df = df.copy()
+    
+    df['Signal'] = 0
+    df.loc[df[rsi_col] < lower_bound, 'Signal'] = 1
+    df.loc[df[rsi_col] > upper_bound, 'Signal'] = -1
+    
+    # Forward fill signals
+    df['Signal'] = df['Signal'].replace(0, np.nan).ffill().fillna(0).astype(int)
+    
+    # Ensure warm-up values are clean
+    df.loc[df[rsi_col].isna(), 'Signal'] = 0
+    
+    return df

stratpy_lib-0.1.0/src/stratpy/utils.py

@@ -0,0 +1,32 @@
+import pandas as pd
+from typing import List
+
+class MissingColumnsError(ValueError):
+    """
+    Custom exception raised when a DataFrame is missing one or more required columns
+    necessary for running an indicator or strategy.
+    """
+    pass
+
+def validate_dataframe(df: pd.DataFrame, required_columns: List[str], caller_name: str) -> None:
+    """
+    Validates that the input is a pandas DataFrame and contains all required columns.
+    
+    Parameters:
+    df (pd.DataFrame): The DataFrame to validate.
+    required_columns (List[str]): List of column names that must be present.
+    caller_name (str): The name of the function or class performing the validation (for error messages).
+    
+    Raises:
+    TypeError: If the input is not a pandas DataFrame.
+    MissingColumnsError: If any of the required columns are missing from the DataFrame.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(f"Stratpy Error: Input to '{caller_name}' must be a pandas DataFrame, got {type(df).__name__}.")
+        
+    missing_cols = [col for col in required_columns if col not in df.columns]
+    if missing_cols:
+        raise MissingColumnsError(
+            f"Stratpy Error: '{caller_name}' requires the following column(s): {missing_cols}. "
+            f"Please verify your DataFrame contains these columns. Available columns: {list(df.columns)}"
+        )

stratpy_lib-0.1.0/src/stratpy_lib.egg-info/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: stratpy-lib
+Version: 0.1.0
+Summary: A modular python library for building algorithmic trading strategies.
+Author-email: Albert Akinola <albert.akinola@outlook.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: yfinance
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# stratpy
+A modular Python library for building and testing algorithmic trading strategies quickly, without writing tons of code from scratch

stratpy_lib-0.1.0/src/stratpy_lib.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/stratpy/__init__.py
+src/stratpy/backtest.py
+src/stratpy/data.py
+src/stratpy/indicators.py
+src/stratpy/strategies.py
+src/stratpy/utils.py
+src/stratpy_lib.egg-info/PKG-INFO
+src/stratpy_lib.egg-info/SOURCES.txt
+src/stratpy_lib.egg-info/dependency_links.txt
+src/stratpy_lib.egg-info/requires.txt
+src/stratpy_lib.egg-info/top_level.txt
+tests/test_indicators.py

stratpy_lib-0.1.0/src/stratpy_lib.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stratpy_lib-0.1.0/src/stratpy_lib.egg-info/requires.txt

@@ -0,0 +1,9 @@
+pandas
+numpy
+yfinance
+matplotlib
+
+[dev]
+pytest
+build
+twine

stratpy_lib-0.1.0/src/stratpy_lib.egg-info/top_level.txt

@@ -0,0 +1 @@
+stratpy

stratpy_lib-0.1.0/tests/test_indicators.py

@@ -0,0 +1,77 @@
+import os
+import sys
+import unittest
+import pandas as pd
+import numpy as np
+
+# Ensure the local 'src' directory is prioritized in the Python path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../src')))
+
+import stratpy as sp
+from stratpy.utils import MissingColumnsError
+
+class TestIndicators(unittest.TestCase):
+    
+    def setUp(self):
+        # Create a basic sample DataFrame for testing
+        dates = pd.date_range(start="2026-01-01", periods=10, freq="D")
+        self.df = pd.DataFrame({
+            "Open": [100.0, 101.0, 102.0, 103.0, 104.0, 105.0, 106.0, 107.0, 108.0, 109.0],
+            "High": [102.0, 103.0, 104.0, 105.0, 106.0, 107.0, 108.0, 109.0, 110.0, 111.0],
+            "Low": [98.0, 99.0, 100.0, 101.0, 102.0, 103.0, 104.0, 105.0, 106.0, 107.0],
+            "Close": [101.0, 102.0, 103.0, 104.0, 105.0, 106.0, 107.0, 108.0, 109.0, 110.0],
+            "Volume": [1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900]
+        }, index=dates)
+
+    def test_sma_calculation(self):
+        # Test SMA with window 3
+        result = sp.sma(self.df, window=3, column='Close')
+        self.assertIn("SMA_3", result.columns)
+        # The first two should be NaN
+        self.assertTrue(np.isnan(result["SMA_3"].iloc[0]))
+        self.assertTrue(np.isnan(result["SMA_3"].iloc[1]))
+        # The third value should be average of 101, 102, 103 = 102
+        self.assertAlmostEqual(result["SMA_3"].iloc[2], 102.0)
+
+    def test_missing_column_validation(self):
+        # Create a DataFrame missing 'Close'
+        incomplete_df = self.df.drop(columns=["Close"])
+        
+        # Calling an indicator requiring 'Close' should raise MissingColumnsError
+        with self.assertRaises(MissingColumnsError) as context:
+            sp.sma(incomplete_df, window=3, column='Close')
+        self.assertIn("requires the following column(s): ['Close']", str(context.exception))
+
+        # ATR requires High, Low, Close. Drop 'High'
+        incomplete_df_atr = self.df.drop(columns=["High"])
+        with self.assertRaises(MissingColumnsError) as context:
+            sp.atr(incomplete_df_atr, window=3)
+        self.assertIn("requires the following column(s): ['High']", str(context.exception))
+
+    def test_rsi_division_by_zero_flat_price(self):
+        # Create a DataFrame where price does not change at all (RSI gain/loss will be 0)
+        flat_dates = pd.date_range(start="2026-01-01", periods=10, freq="D")
+        flat_df = pd.DataFrame({
+            "Close": [100.0] * 10
+        }, index=flat_dates)
+        
+        # RSI should run and return 50.0 (safely handling division by zero) rather than crashing
+        result = sp.rsi(flat_df, window=3, column='Close')
+        self.assertIn("RSI_3", result.columns)
+        # The values after the rolling warm-up should be 50.0
+        # Wait, since gain and loss are 0, total_change is 0, so result is 50.0
+        self.assertAlmostEqual(result["RSI_3"].iloc[2], 50.0)
+
+    def test_vwap_division_by_zero_zero_volume(self):
+        # Create a DataFrame where volume is zero
+        zero_vol_df = self.df.copy()
+        zero_vol_df["Volume"] = 0
+        
+        # VWAP should run and return NaN (or handles zero volume safely) rather than crashing or throwing ZeroDivisionError
+        result = sp.vwap(zero_vol_df)
+        self.assertIn("VWAP", result.columns)
+        self.assertTrue(np.isnan(result["VWAP"].iloc[0]))
+        self.assertTrue(np.isnan(result["VWAP"].iloc[-1]))
+
+if __name__ == '__main__':
+    unittest.main()