bbstrader 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

bbstrader/metatrader/account.py

@@ -1,21 +1,28 @@
 import os
 import re
 import urllib.request
-from datetime import datetime, timedelta
+from datetime import datetime
 from typing import Any, Dict, List, Literal, Optional, Tuple, Union
 
+import numpy as np
 import pandas as pd
 from currency_converter import SINGLE_DAY_ECB_URL, CurrencyConverter
+from numpy.typing import NDArray
 
 from bbstrader.metatrader.utils import (
+    TIMEFRAMES,
     AccountInfo,
     BookInfo,
     InvalidBroker,
     OrderCheckResult,
     OrderSentResult,
+    RateDtype,
+    RateInfo,
     SymbolInfo,
     SymbolType,
     TerminalInfo,
+    TickDtype,
+    TickFlag,
     TickInfo,
     TradeDeal,
     TradeOrder,
@@ -33,6 +40,7 @@ except ImportError:
 __all__ = [
     "Account",
     "Broker",
+    "MetaQuotes",
     "AdmiralMarktsGroup",
     "JustGlobalMarkets",
     "PepperstoneGroupLimited",
@@ -41,6 +49,7 @@ __all__ = [
 ]
 
 __BROKERS__ = {
+    "MQL": "MetaQuotes Ltd.",
     "AMG": "Admirals Group AS",
     "JGM": "Just Global Markets Ltd.",
     "FTMO": "FTMO S.R.O.",
@@ -67,14 +76,13 @@ _ADMIRAL_MARKETS_PRODUCTS_ = [
 ]
 _JUST_MARKETS_PRODUCTS_ = ["Stocks", "Crypto", "indices", "Commodities", "Forex"]
 
-SUPPORTED_BROKERS = [__BROKERS__[b] for b in {"AMG", "JGM", "FTMO"}]
+SUPPORTED_BROKERS = [__BROKERS__[b] for b in {"MQL", "AMG", "JGM", "FTMO"}]
 INIT_MSG = (
-    f"\n* Ensure you have a good and stable internet connexion\n"
-    f"* Ensure you have an activete MT5 terminal install on your machine\n"
-    f"* Ensure you have an active MT5 Account with {' or '.join(SUPPORTED_BROKERS)}\n"
-    f"* If you want to trade {', '.join(_ADMIRAL_MARKETS_PRODUCTS_)}, See [{_ADMIRAL_MARKETS_URL_}]\n"
-    f"* If you want to trade {', '.join(_JUST_MARKETS_PRODUCTS_)}, See [{_JUST_MARKETS_URL_}]\n"
-    f"* If you are looking for a prop firm, See [{_FTMO_URL_}]\n"
+    f"\n* Check your internet connection\n"
+    f"* Make sure MT5 is installed and active\n"
+    f"* Looking for a boker? See [{_ADMIRAL_MARKETS_URL_}] "
+    f"or [{_JUST_MARKETS_URL_}]\n"
+    f"* Looking for a prop firm? See [{_FTMO_URL_}]\n"
 )
 
 amg_url = _ADMIRAL_MARKETS_URL_
@@ -136,7 +144,16 @@ AMG_EXCHANGES = {
 }
 
 
-def check_mt5_connection(**kwargs) -> bool:
+def check_mt5_connection(
+    *,
+    path=None,
+    login=None,
+    password=None,
+    server=None,
+    timeout=60_000,
+    portable=False,
+    **kwargs,
+) -> bool:
     """
     Initialize the connection to the MetaTrader 5 terminal.
 
@@ -156,12 +173,11 @@ def check_mt5_connection(**kwargs) -> bool:
         - Follow these instructions to lunch each terminal in portable mode first:
             https://www.metatrader5.com/en/terminal/help/start_advanced/start#configuration_file
     """
-    path = kwargs.get("path", None)
-    login = kwargs.get("login", None)
-    password = kwargs.get("password", None)
-    server = kwargs.get("server", None)
-    timeout = kwargs.get("timeout", 60_000)
-    portable = kwargs.get("portable", False)
+    if login is not None and server is not None:
+        account_info = mt5.account_info()
+        if account_info is not None:
+            if account_info.login == login and account_info.server == server:
+                return True
 
     init = False
     if path is None and (login or password or server):
@@ -221,6 +237,11 @@ class Broker(object):
         return f"{self.__class__.__name__}({self.name})"
 
 
+class MetaQuotes(Broker):
+    def __init__(self, **kwargs):
+        super().__init__(__BROKERS__["MQL"], **kwargs)
+
+
 class AdmiralMarktsGroup(Broker):
     def __init__(self, **kwargs):
         super().__init__(__BROKERS__["AMG"], **kwargs)
@@ -262,6 +283,7 @@ class AMP(Broker): ...
 
 BROKERS: Dict[str, Broker] = {
     "FTMO": FTMO(),
+    "MQL": MetaQuotes(),
     "AMG": AdmiralMarktsGroup(),
     "JGM": JustGlobalMarkets(),
     "PGL": PepperstoneGroupLimited(),
@@ -503,7 +525,7 @@ class Account(object):
         """Helper function to  print account info"""
         self._show_info(self.get_account_info, "account")
 
-    def get_terminal_info(self, show=False) -> Union[TerminalInfo, None]:
+    def get_terminal_info(self, show=False) -> TerminalInfo | None:
         """
         Get the connected MetaTrader 5 client terminal status and settings.
 
@@ -951,7 +973,7 @@ class Account(object):
                         futures_types["bonds"].append(info.name)
             return futures_types[category]
 
-    def get_symbol_info(self, symbol: str) -> Union[SymbolInfo, None]:
+    def get_symbol_info(self, symbol: str) -> SymbolInfo | None:
         """Get symbol properties
 
         Args:
@@ -984,6 +1006,14 @@ class Account(object):
             msg = self._symbol_info_msg(symbol)
             raise_mt5_error(message=f"{str(e)} {msg}")
 
+    def _symbol_info_msg(self, symbol):
+        return (
+            f"No history found for {symbol} in Market Watch.\n"
+            f"* Ensure {symbol} is selected and displayed in the Market Watch window.\n"
+            f"* See https://www.metatrader5.com/en/terminal/help/trading/market_watch\n"
+            f"* Ensure the symbol name is correct.\n"
+        )
+
     def show_symbol_info(self, symbol: str):
         """
         Print symbol properties
@@ -993,15 +1023,7 @@ class Account(object):
         """
         self._show_info(self.get_symbol_info, "symbol", symbol=symbol)
 
-    def _symbol_info_msg(self, symbol):
-        return (
-            f"No history found for {symbol} in Market Watch.\n"
-            f"* Ensure {symbol} is selected and displayed in the Market Watch window.\n"
-            f"* See https://www.metatrader5.com/en/terminal/help/trading/market_watch\n"
-            f"* Ensure the symbol name is correct.\n"
-        )
-
-    def get_tick_info(self, symbol: str) -> Union[TickInfo, None]:
+    def get_tick_info(self, symbol: str) -> TickInfo | None:
         """Get symbol tick properties
 
         Args:
@@ -1043,7 +1065,148 @@ class Account(object):
         """
         self._show_info(self.get_tick_info, "tick", symbol=symbol)
 
-    def get_market_book(self, symbol: str) -> Union[Tuple[BookInfo], None]:
+    def get_rate_info(self, symbol: str, timeframe: str = "1m") -> RateInfo | None:
+        """Get the most recent bar for a specified symbol and timeframe.
+
+        Args:
+            symbol (str): The symbol for which to get the rate information.
+            timeframe (str): The timeframe for the rate information. Default is '1m'.
+                            See ``bbstrader.metatrader.utils.TIMEFRAMES`` for supported timeframes.
+        Returns:
+            RateInfo: The most recent bar as a RateInfo named tuple.
+            None: If no rates are found or an error occurs.
+        Raises:
+            MT5TerminalError: A specific exception based on the error code.
+        """
+        rates = mt5.copy_rates_from_pos(symbol, TIMEFRAMES[timeframe], 0, 1)
+        if rates is None or len(rates) == 0:
+            return None
+        rate = rates[0]
+        return RateInfo(*rate)
+
+    def get_rates_from_pos(
+        self, symbol: str, timeframe: str, start_pos: int = 0, bars: int = 1
+    ) -> NDArray[np.void]:
+        """
+        Get bars from the MetaTrader 5 terminal starting from the specified index.
+
+        Args:
+            symbol: Financial instrument name, for example, "EURUSD"
+            timeframe: Timeframe the bars are requested for.
+            start_pos: Initial index of the bar the data are requested from.
+            bars: Number of bars to receive.
+
+        Returns:
+            bars as the numpy array with the named time, open, high, low, close, tick_volume, spread and real_volume columns.
+            Returns an empty array in case of an error.
+        """
+        rates = mt5.copy_rates_from_pos(symbol, TIMEFRAMES[timeframe], start_pos, bars)
+        if rates is None or len(rates) == 0:
+            return np.array([], dtype=RateDtype)
+        return rates
+
+    def get_rates_from_date(
+        self,
+        symbol: str,
+        timeframe: str,
+        date_from: datetime | pd.Timestamp,
+        bars: int = 1,
+    ) -> NDArray[np.void]:
+        """
+        Get bars from the MetaTrader 5 terminal starting from the specified date.
+
+        Args:
+            symbol: Financial instrument name, for example, "EURUSD"
+            timeframe: Timeframe the bars are requested for.
+            date_from: Date of opening of the first bar from the requested sample.
+            bars: Number of bars to receive.
+
+        Returns:
+            bars as the numpy array with the named time, open, high, low, close, tick_volume, spread and real_volume columns.
+            Returns an empty array in case of an error.
+
+        """
+        rates = mt5.copy_rates_from(symbol, TIMEFRAMES[timeframe], date_from, bars)
+        if rates is None or len(rates) == 0:
+            return np.array([], dtype=RateDtype)
+        return rates
+
+    def get_rates_range(
+        self,
+        symbol: str,
+        timeframe: str,
+        date_from: datetime | pd.Timestamp,
+        date_to: datetime | pd.Timestamp = datetime.now(),
+    ) -> NDArray[np.void]:
+        """
+        Get bars in the specified date range from the MetaTrader 5 terminal.
+
+        Args:
+            symbol: Financial instrument name, for example, "EURUSD"
+            timeframe: Timeframe the bars are requested for.
+            date_from: Date the bars are requested from.
+            date_to: Date, up to which the bars are requested.
+
+        Returns:
+            bars as the numpy array with the named time, open, high, low, close, tick_volume, spread and real_volume columns.
+            Returns an empty array in case of an error.
+        """
+        rates = mt5.copy_rates_range(symbol, TIMEFRAMES[timeframe], date_from, date_to)
+        if rates is None or len(rates) == 0:
+            return np.array([], dtype=RateDtype)
+        return rates
+
+    def get_tick_from_date(
+        self,
+        symbol: str,
+        date_from: datetime | pd.Timestamp,
+        ticks: int = 1,
+        flag: Literal["all", "info", "trade"] = "all",
+    ) -> NDArray[np.void]:
+        """
+        Get ticks from the MetaTrader 5 terminal starting from the specified date.
+
+        Args:
+            symbol: Financial instrument name, for example, "EURUSD"
+            date_from: Date the ticks are requested from.
+            ticks: Number of bars to receive.
+            flag: A flag to define the type of the requested ticks ("all", "info", "trade").
+
+        Returns:
+            Returns ticks as the numpy array with the named time, bid, ask, last and flags columns.
+            Return an empty array in case of an error.
+        """
+        ticks_data = mt5.copy_ticks_from(symbol, date_from, ticks, TickFlag[flag])
+        if ticks_data is None or len(ticks_data) == 0:
+            return np.array([], dtype=TickDtype)
+        return ticks_data
+
+    def get_tick_range(
+        self,
+        symbol: str,
+        date_from: datetime | pd.Timestamp,
+        date_to: datetime | pd.Timestamp = datetime.now(),
+        flag: Literal["all", "info", "trade"] = "all",
+    ) -> NDArray[np.void]:
+        """
+        Get ticks for the specified date range from the MetaTrader 5 terminal.
+
+        Args:
+            symbol: Financial instrument name, for example, "EURUSD"
+            date_from: Date the ticks are requested from.
+            date_to: Date, up to which the ticks are requested.
+            flag: A flag to define the type of the requested ticks ("all", "info", "trade").
+
+        Returns:
+            Returns ticks as the numpy array with the named time, bid, ask, last and flags columns.
+            Return an empty array in case of an error.
+        """
+        ticks_data = mt5.copy_ticks_range(symbol, date_from, date_to, TickFlag[flag])
+        if ticks_data is None or len(ticks_data) == 0:
+            return np.array([], dtype=TickDtype)
+        return ticks_data
+
+    def get_market_book(self, symbol: str) -> Tuple[BookInfo]:
         """
         Get the Market Depth content for a specific symbol.
         Args:
@@ -1185,7 +1348,7 @@ class Account(object):
         group: Optional[str] = None,
         ticket: Optional[int] = None,
         to_df: bool = False,
-    ) -> Union[pd.DataFrame, Tuple[TradePosition], None]:
+    ) -> Union[pd.DataFrame, Tuple[TradePosition]]:
         """
         Get open positions with the ability to filter by symbol or ticket.
         There are four call options:
@@ -1215,7 +1378,6 @@ class Account(object):
         Returns:
             Union[pd.DataFrame, Tuple[TradePosition], None]:
             - `TradePosition` in the form of a named tuple structure (namedtuple) or pd.DataFrame.
-            - `None` in case of an error.
 
         Notes:
             The method allows receiving all open positions within a specified period.
@@ -1271,7 +1433,7 @@ class Account(object):
         position: Optional[int] = None,  # TradePosition.ticket
         to_df: bool = True,
         save: bool = False,
-    ) -> Union[pd.DataFrame, Tuple[TradeDeal], None]:
+    ) -> Union[pd.DataFrame, Tuple[TradeDeal]]:
         """
         Get deals from trading history within the specified interval
         with the ability to filter by `ticket` or `position`.
@@ -1309,7 +1471,6 @@ class Account(object):
         Returns:
             Union[pd.DataFrame, Tuple[TradeDeal], None]:
             - `TradeDeal` in the form of a named tuple structure (namedtuple) or pd.DataFrame().
-            - `None` in case of an error.
 
         Notes:
             The method allows receiving all history orders within a specified period.
@@ -1372,7 +1533,7 @@ class Account(object):
         group: Optional[str] = None,
         ticket: Optional[int] = None,
         to_df: bool = False,
-    ) -> Union[pd.DataFrame, Tuple[TradeOrder], None]:
+    ) -> Union[pd.DataFrame, Tuple[TradeOrder]]:
         """
         Get active orders with the ability to filter by symbol or ticket.
         There are four call options:
@@ -1399,7 +1560,6 @@ class Account(object):
         Returns:
             Union[pd.DataFrame, Tuple[TradeOrder], None]:
             - `TradeOrder` in the form of a named tuple structure (namedtuple) or pd.DataFrame().
-            - `None` in case of an error.
 
         Notes:
             The method allows receiving all history orders within a specified period.
@@ -1464,7 +1624,7 @@ class Account(object):
         position: Optional[int] = None,  # position ticket
         to_df: bool = True,
         save: bool = False,
-    ) -> Union[pd.DataFrame, Tuple[TradeOrder], None]:
+    ) -> Union[pd.DataFrame, Tuple[TradeOrder]]:
         """
         Get orders from trading history within the specified interval
         with the ability to filter by `ticket` or `position`.
@@ -1502,7 +1662,6 @@ class Account(object):
         Returns:
             Union[pd.DataFrame, Tuple[TradeOrder], None]
             - `TradeOrder` in the form of a named tuple structure (namedtuple) or pd.DataFrame().
-            - `None` in case of an error.
 
         Notes:
             The method allows receiving all history orders within a specified period.
@@ -1583,16 +1742,11 @@ class Account(object):
         Returns:
             List[TradeDeal]: List of today deals
         """
-        date_from = datetime.now() - timedelta(days=2)
-        history = (
-            self.get_trades_history(date_from=date_from, group=group, to_df=False) or []
-        )
+        history = self.get_trades_history(group=group, to_df=False) or []
         positions_ids = set([deal.position_id for deal in history if deal.magic == id])
         today_deals = []
         for position in positions_ids:
-            deal = self.get_trades_history(
-                date_from=date_from, position=position, to_df=False
-            )
+            deal = self.get_trades_history(position=position, to_df=False) or []
             if deal is not None and len(deal) == 2:
                 deal_time = datetime.fromtimestamp(deal[1].time)
                 if deal_time.date() == datetime.now().date():

bbstrader/metatrader/analysis.py

@@ -4,17 +4,15 @@ import numpy as np
 import pandas as pd
 import seaborn as sns
 
-from bbstrader.metatrader.account import check_mt5_connection
+from bbstrader.metatrader.account import check_mt5_connection, shutdown_mt5
 from bbstrader.metatrader.utils import TIMEFRAMES
 
 sns.set_theme()
 
 
-def _get_data(path, symbol, timeframe, bars):
-    check_mt5_connection(path=path)
+def _get_data(symbol, timeframe, bars):
     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
 
 
@@ -76,10 +74,14 @@ def display_volume_profile(
     Returns:
         None: Displays a matplotlib chart of the volume profile.
     """
-    df = _get_data(path, symbol, TIMEFRAMES[timeframe], bars)
+    check_mt5_connection(path=path)
+    df = _get_data(symbol, TIMEFRAMES[timeframe], bars)
+    if df.empty:
+        raise ValueError(f"No data found for {symbol} in {path}")
     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
+    shutdown_mt5()
 
     plt.figure(figsize=(6, 10))
     plt.barh(bin_centers, hist, height=bin_centers[1] - bin_centers[0], color="skyblue")