bbstrader 0.2.97__tar.gz → 0.2.99__tar.gz

{bbstrader-0.2.97/bbstrader.egg-info → bbstrader-0.2.99}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bbstrader
-Version: 0.2.97
+Version: 0.2.99
 Summary: Simplified Investment & Trading Toolkit
 Home-page: https://github.com/bbalouki/bbstrader
 Download-URL: https://pypi.org/project/bbstrader/
@@ -24,21 +24,24 @@ Classifier: Operating System :: MacOS
 Classifier: License :: OSI Approved :: MIT License
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pandas
+Requires-Dist: numpy<2.0.0,>=1.26.0
+Requires-Dist: scikit-learn
+Requires-Dist: statsmodels
+Requires-Dist: seaborn
+Requires-Dist: lightgbm
+Requires-Dist: dash
+Requires-Dist: nltk
+Requires-Dist: spacy
+Requires-Dist: pmdarima
+Requires-Dist: pyportfolioopt
+Requires-Dist: alphalens-reloaded
 Requires-Dist: pandas_ta
-Requires-Dist: numpy<2.0.0
 Requires-Dist: yfinance
-Requires-Dist: scipy
 Requires-Dist: hmmlearn
-Requires-Dist: pmdarima
 Requires-Dist: arch
 Requires-Dist: hurst
-Requires-Dist: seaborn
-Requires-Dist: statsmodels
-Requires-Dist: matplotlib
 Requires-Dist: filterpy
 Requires-Dist: pykalman
-Requires-Dist: pytest
 Requires-Dist: CurrencyConverter
 Requires-Dist: tabulate
 Requires-Dist: python-dotenv
@@ -46,24 +49,17 @@ Requires-Dist: ipython
 Requires-Dist: QuantStats
 Requires-Dist: exchange-calendars
 Requires-Dist: tqdm
-Requires-Dist: scikit-learn
 Requires-Dist: notify-py
 Requires-Dist: python-telegram-bot
-Requires-Dist: pyportfolioopt
 Requires-Dist: eodhd
 Requires-Dist: financetoolkit
 Requires-Dist: PyYAML
 Requires-Dist: tables
-Requires-Dist: lightgbm
-Requires-Dist: alphalens-reloaded
 Requires-Dist: pyfiglet
 Requires-Dist: colorama
 Requires-Dist: praw
 Requires-Dist: tweepy
 Requires-Dist: beautifulsoup4
-Requires-Dist: dash
-Requires-Dist: nltk
-Requires-Dist: spacy
 Requires-Dist: textblob
 Requires-Dist: vaderSentiment
 Provides-Extra: mt5

{bbstrader-0.2.97 → bbstrader-0.2.99}/bbstrader/__main__.py

@@ -16,7 +16,7 @@ USAGE_TEXT = """
     Modules:
         copier: Copy trades from one MetaTrader account to another or multiple accounts
         backtest: Backtest a strategy, see bbstrader.btengine.backtest.run_backtest
-        execution: Execute a strategy, see bbstrader.trading.execution.MT5ExecutionEngine
+        execution: Execute a strategy, see bbstrader.trading.execution.Mt5ExecutionEngine
     
     python -m bbstrader --run <module> --help for more information on the module
 """

{bbstrader-0.2.97 → bbstrader-0.2.99}/bbstrader/btengine/backtest.py

@@ -4,7 +4,7 @@ from datetime import datetime
 from typing import List, Literal, Optional
 
 from tabulate import tabulate
-
+from bbstrader.btengine.event import Events
 from bbstrader.btengine.data import DataHandler
 from bbstrader.btengine.execution import ExecutionHandler, SimExecutionHandler
 from bbstrader.btengine.portfolio import Portfolio
@@ -165,19 +165,19 @@ class BacktestEngine(Backtest):
                     break
                 else:
                     if event is not None:
-                        if event.type == "MARKET":
+                        if event.type == Events.MARKET:
                             self.strategy.calculate_signals(event)
                             self.portfolio.update_timeindex(event)
 
-                        elif event.type == "SIGNAL":
+                        elif event.type == Events.SIGNAL:
                             self.signals += 1
                             self.portfolio.update_signal(event)
 
-                        elif event.type == "ORDER":
+                        elif event.type == Events.ORDER:
                             self.orders += 1
                             self.execution_handler.execute_order(event)
 
-                        elif event.type == "FILL":
+                        elif event.type == Events.FILL:
                             self.fills += 1
                             self.portfolio.update_fill(event)
                             self.strategy.update_trades_from_fill(event)
@@ -354,7 +354,7 @@ def run_backtest_with(engine: Literal["bbstrader", "cerebro", "zipline"], **kwar
         )
     elif engine == "cerebro":
         # TODO:
-        pass
+        raise NotImplementedError("cerebro engine is not supported yet")
     elif engine == "zipline":
         # TODO:
-        pass
+        raise NotImplementedError("zipline engine is not supported yet")

{bbstrader-0.2.97 → bbstrader-0.2.99}/bbstrader/btengine/event.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from enum import Enum
 from typing import Literal
 
 __all__ = ["Event", "MarketEvent", "SignalEvent", "OrderEvent", "FillEvent"]
@@ -18,6 +19,13 @@ class Event(object):
     ...
 
 
+class Events(Enum):
+    MARKET = "MARKET"
+    SIGNAL = "SIGNAL"
+    ORDER = "ORDER"
+    FILL = "FILL"
+
+
 class MarketEvent(Event):
     """
     Market Events are triggered when the outer while loop of the backtesting
@@ -32,7 +40,7 @@ class MarketEvent(Event):
         """
         Initialises the MarketEvent.
         """
-        self.type = "MARKET"
+        self.type = Events.MARKET
 
 
 class SignalEvent(Event):
@@ -72,7 +80,7 @@ class SignalEvent(Event):
             price (int | float): An optional price to be used when the signal is generated.
             stoplimit (int | float): An optional stop-limit price for the signal
         """
-        self.type = "SIGNAL"
+        self.type = Events.SIGNAL
         self.strategy_id = strategy_id
         self.symbol = symbol
         self.datetime = datetime
@@ -118,7 +126,7 @@ class OrderEvent(Event):
             price (int | float): The price at which to order.
             signal (str): The signal that generated the order.
         """
-        self.type = "ORDER"
+        self.type = Events.ORDER
         self.symbol = symbol
         self.order_type = order_type
         self.quantity = quantity
@@ -191,7 +199,7 @@ class FillEvent(Event):
             commission (float | None): An optional commission sent from IB.
             order (str): The order that this fill is related
         """
-        self.type = "FILL"
+        self.type = Events.FILL
         self.timeindex = timeindex
         self.symbol = symbol
         self.exchange = exchange

{bbstrader-0.2.97 → bbstrader-0.2.99}/bbstrader/btengine/execution.py

@@ -4,7 +4,7 @@ from queue import Queue
 from loguru import logger
 
 from bbstrader.btengine.data import DataHandler
-from bbstrader.btengine.event import FillEvent, OrderEvent
+from bbstrader.btengine.event import Events, FillEvent, OrderEvent
 from bbstrader.config import BBSTRADER_DIR
 from bbstrader.metatrader.account import Account
 
@@ -80,7 +80,7 @@ class SimExecutionHandler(ExecutionHandler):
         Args:
             event (OrderEvent): Contains an Event object with order information.
         """
-        if event.type == "ORDER":
+        if event.type == Events.ORDER:
             dtime = self.bardata.get_latest_bar_datetime(event.symbol)
             fill_event = FillEvent(
                 timeindex=dtime,
@@ -233,7 +233,7 @@ class MT5ExecutionHandler(ExecutionHandler):
         Args:
             event (OrderEvent): Contains an Event object with order information.
         """
-        if event.type == "ORDER":
+        if event.type == Events.ORDER:
             symbol = event.symbol
             direction = event.direction
             quantity = event.quantity

{bbstrader-0.2.97 → bbstrader-0.2.99}/bbstrader/btengine/portfolio.py

@@ -6,7 +6,7 @@ import pandas as pd
 import quantstats as qs
 
 from bbstrader.btengine.data import DataHandler
-from bbstrader.btengine.event import FillEvent, MarketEvent, OrderEvent, SignalEvent
+from bbstrader.btengine.event import Events, FillEvent, MarketEvent, OrderEvent, SignalEvent
 from bbstrader.btengine.performance import (
     create_drawdowns,
     create_sharpe_ratio,
@@ -282,7 +282,7 @@ class Portfolio(object):
         Updates the portfolio current positions and holdings
         from a FillEvent.
         """
-        if event.type == "FILL":
+        if event.type == Events.FILL:
             self.update_positions_from_fill(event)
             self.update_holdings_from_fill(event)
 
@@ -337,7 +337,7 @@ class Portfolio(object):
         Acts on a SignalEvent to generate new orders
         based on the portfolio logic.
         """
-        if event.type == "SIGNAL":
+        if event.type == Events.SIGNAL:
             order_event = self.generate_order(event)
             self.events.put(order_event)
 

{bbstrader-0.2.97 → bbstrader-0.2.99}/bbstrader/btengine/strategy.py

@@ -10,15 +10,15 @@ import pytz
 from loguru import logger
 
 from bbstrader.btengine.data import DataHandler
-from bbstrader.btengine.event import FillEvent, SignalEvent
+from bbstrader.btengine.event import Events, FillEvent, SignalEvent
 from bbstrader.config import BBSTRADER_DIR
-from bbstrader.metatrader.trade import TradeSignal
 from bbstrader.metatrader.account import (
     Account,
     AdmiralMarktsGroup,
     PepperstoneGroupLimited,
 )
 from bbstrader.metatrader.rates import Rates
+from bbstrader.metatrader.trade import TradeSignal
 from bbstrader.models.optimization import optimized_weights
 
 __all__ = ["Strategy", "MT5Strategy"]
@@ -67,7 +67,7 @@ class MT5Strategy(Strategy):
     """
     A `MT5Strategy()` object is a subclass of `Strategy` that is used to
     calculate signals for the MetaTrader 5 trading platform. The signals
-    are generated by the `MT5Strategy` object and sent to the the `MT5ExecutionEngine`
+    are generated by the `MT5Strategy` object and sent to the the `Mt5ExecutionEngine`
     for live trading and `MT5BacktestEngine` objects for backtesting.
     """
 
@@ -146,9 +146,9 @@ class MT5Strategy(Strategy):
     def _initialize_portfolio(self):
         positions = ["LONG", "SHORT"]
         orders = ["BLMT", "BSTP", "BSTPLMT", "SLMT", "SSTP", "SSTPLMT"]
+        self._orders: Dict[str, Dict[str, List[SignalEvent]]] = {}
         self._positions: Dict[str, Dict[str, int | float]] = {}
         self._trades: Dict[str, Dict[str, int]] = {}
-        self._orders: Dict[str, Dict[str, List[SignalEvent]]] = {}
         for symbol in self.symbols:
             self._positions[symbol] = {}
             self._orders[symbol] = {}
@@ -188,7 +188,7 @@ class MT5Strategy(Strategy):
         This method updates the trades for the strategy based on the fill event.
         It is used to keep track of the number of trades executed for each order.
         """
-        if event.type == "FILL":
+        if event.type == Events.FILL:
             if event.order != "EXIT":
                 self._trades[event.symbol][event.order] += 1
             elif event.order == "EXIT" and event.direction == "BUY":
@@ -206,6 +206,7 @@ class MT5Strategy(Strategy):
         - ``price``: The price at which to execute the action, used for pending orders.
         - ``stoplimit``: The stop-limit price for STOP-LIMIT orders, used for pending stop limit orders.
         - ``id``: The unique identifier for the strategy or order.
+        - ``comment``: An optional comment or description related to the trade signal.
         """
         pass
 
@@ -677,6 +678,12 @@ class MT5Strategy(Strategy):
         if period_count == 0 or period_count is None:
             return True
         return period_count % signal_inverval == 0
+    
+    @staticmethod
+    def stop_time(time_zone: str, stop_time: str) -> bool:
+        now = datetime.now(pytz.timezone(time_zone)).time()
+        stop_time = datetime.strptime(stop_time, "%H:%M").time()
+        return now >= stop_time
 
     def ispositions(
         self, symbol, strategy_id, position, max_trades, one_true=False, account=None

{bbstrader-0.2.97 → bbstrader-0.2.99}/bbstrader/metatrader/account.py

@@ -9,6 +9,7 @@ from currency_converter import SINGLE_DAY_ECB_URL, CurrencyConverter
 
 from bbstrader.metatrader.utils import (
     AccountInfo,
+    BookInfo,
     InvalidBroker,
     OrderCheckResult,
     OrderSentResult,
@@ -188,10 +189,12 @@ def check_mt5_connection(**kwargs):
     except Exception:
         raise_mt5_error(INIT_MSG)
 
+
 def shutdown_mt5():
     """Close the connection to the MetaTrader 5 terminal."""
     mt5.shutdown()
-    
+
+
 class Broker(object):
     def __init__(self, name: str = None, **kwargs):
         if name is None:
@@ -323,7 +326,7 @@ class Account(object):
                 f"For {supported['FTMO'].name}, See [{ftmo_url}]\n"
             )
             raise InvalidBroker(message=msg)
-    
+
     def shutdown(self):
         """Close the connection to the MetaTrader 5 terminal."""
         shutdown_mt5()
@@ -1037,6 +1040,29 @@ class Account(object):
         """
         self._show_info(self.get_tick_info, "tick", symbol=symbol)
 
+    def get_market_book(self, symbol: str) -> Union[Tuple[BookInfo], None]:
+        """
+        Get the Market Depth content for a specific symbol.
+        Args:
+            symbol (str): Financial instrument name. Required unnamed parameter.
+                The symbol name should be specified in the same format as in the Market Watch window.
+
+        Returns:
+            The Market Depth content as a tuple from BookInfo entries featuring order type, price and volume in lots.
+            Return None in case of an error.
+            
+        Raises:
+            MT5TerminalError: A specific exception based on the error code.
+        """
+        try:
+            book = mt5.market_book_get(symbol)
+            if book is None:
+                return None
+            else:
+                return tuple([BookInfo(**entry._asdict()) for entry in book])
+        except Exception as e:
+            raise_mt5_error(e)
+
     def calculate_margin(
         self, action: Literal["buy", "sell"], symbol: str, lot: float, price: float
     ) -> float:
@@ -1299,8 +1325,7 @@ class Account(object):
         df.drop(["time_msc", "external_id"], axis=1, inplace=True)
         df.set_index("time", inplace=True)
         if save:
-            file = "trade_history.csv"
-            df.to_csv(file)
+            df.to_csv("trades_history.csv")
         if to_df:
             return df
         else:
@@ -1507,8 +1532,7 @@ class Account(object):
         df["time_done"] = pd.to_datetime(df["time_done"], unit="s")
 
         if save:
-            file = "trade_history.csv"
-            df.to_csv(file)
+            df.to_csv("orders_history.csv")
         if to_df:
             return df
         else:

bbstrader-0.2.99/bbstrader/metatrader/analysis.py

@@ -0,0 +1,98 @@
+import matplotlib.pyplot as plt
+import MetaTrader5 as mt5
+import numpy as np
+import pandas as pd
+import seaborn as sns
+
+from bbstrader.metatrader.account import check_mt5_connection
+from bbstrader.metatrader.utils import TIMEFRAMES
+
+sns.set_theme()
+
+
+def _get_data(path, symbol, timeframe, bars):
+    check_mt5_connection(path=path)
+    rates = mt5.copy_rates_from_pos(symbol, timeframe, 0, bars)
+    df = pd.DataFrame(rates)
+    df["time"] = pd.to_datetime(df["time"], unit="s")
+    return df
+
+
+def volume_profile(df, bins):
+    prices = (df["high"] + df["low"]) / 2
+    volumes = df["tick_volume"]
+    hist, bin_edges = np.histogram(prices, bins=bins, weights=volumes)
+    bin_centers = 0.5 * (bin_edges[:-1] + bin_edges[1:])
+    return hist, bin_edges, bin_centers
+
+
+def value_area(hist, bin_centers, percentage):
+    total_volume = np.sum(hist)
+    poc_index = np.argmax(hist)
+    poc = bin_centers[poc_index]
+
+    sorted_indices = np.argsort(hist)[::-1]
+    volume_accum = 0
+    value_area_indices = []
+
+    for idx in sorted_indices:
+        volume_accum += hist[idx]
+        value_area_indices.append(idx)
+        if volume_accum >= percentage * total_volume:
+            break
+
+    vah = max(bin_centers[i] for i in value_area_indices)
+    val = min(bin_centers[i] for i in value_area_indices)
+    return poc, vah, val
+
+
+def display_volume_profile(
+    symbol,
+    path,
+    timeframe: str = "1m",
+    bars: int = 1440,
+    bins: int = 100,
+    va_percentage: float = 0.7,
+):
+    """
+    Display a volume profile chart for a given market symbol using historical data.
+
+    This function retrieves historical price and volume data for a given symbol and
+    plots a vertical volume profile chart showing the volume distribution across 
+    price levels. It highlights key levels such as:
+        - Point of Control (POC): Price level with the highest traded volume.
+        - Value Area High (VAH): Upper bound of the value area.
+        - Value Area Low (VAL): Lower bound of the value area.
+        - Current Price: Latest bid price from MetaTrader 5.
+
+    Args:
+        symbol (str): Market symbol (e.g., "AAPL", "EURUSD").
+        path (str): Path to the historical data see ``bbstrader.metatrader.account.check_mt5_connection()``.
+        timeframe (str, optional): Timeframe for each candle (default is "1m").
+        bars (int, optional): Number of historical bars to fetch (default is 1440).
+        bins (int, optional): Number of price bins for volume profile calculation (default is 100).
+        va_percentage (float, optional): Percentage of total volume to define the value area (default is 0.7).
+
+    Returns:
+        None: Displays a matplotlib chart of the volume profile.
+    """
+    df = _get_data(path, symbol, TIMEFRAMES[timeframe], bars)
+    hist, bin_edges, bin_centers = volume_profile(df, bins)
+    poc, vah, val = value_area(hist, bin_centers, va_percentage)
+    current_price = mt5.symbol_info_tick(symbol).bid
+
+    plt.figure(figsize=(6, 10))
+    plt.barh(bin_centers, hist, height=bin_centers[1] - bin_centers[0], color="skyblue")
+    plt.axhline(poc, color="red", linestyle="--", label=f"POC: {poc:.5f}")
+    plt.axhline(vah, color="green", linestyle="--", label=f"VAH: {vah:.5f}")
+    plt.axhline(val, color="orange", linestyle="--", label=f"VAL: {val:.5f}")
+    plt.axhline(
+        current_price, color="black", linestyle=":", label=f"Price: {current_price:.5f}"
+    )
+    plt.legend()
+    plt.title("Volume Profile")
+    plt.xlabel("Volume")
+    plt.ylabel("Price")
+    plt.grid(True)
+    plt.tight_layout()
+    plt.show()