bbstrader 2.0.3__cp312-cp312-macosx_11_0_arm64.whl

bbstrader/__init__.py

@@ -0,0 +1,27 @@
+"""
+Simplified Investment & Trading Toolkit with Python & C++
+
+"""
+
+__author__ = "Bertin Balouki SIMYELI"
+__copyright__ = "2023-2026 Bertin Balouki SIMYELI"
+__email__ = "bertin@bbs-trading.com"
+__license__ = "MIT"
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("bbstrader")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+
+from bbstrader import compat  # noqa: F401
+from bbstrader import core  # noqa: F401
+from bbstrader import btengine  # noqa: F401
+from bbstrader import metatrader  # noqa: F401
+from bbstrader import models  # noqa: F401
+from bbstrader import trading  # noqa: F401
+from bbstrader.config import config_logger  # noqa: F401
+
+version = __version__

bbstrader/__main__.py

@@ -0,0 +1,92 @@
+import argparse
+import multiprocessing
+import sys
+from enum import Enum
+
+import pyfiglet
+from colorama import Fore
+from loguru import logger
+
+from bbstrader.scripts import backtest, copy_trades, execute_strategy, send_news_feed
+
+from . import __author__, __version__
+
+logger.remove()
+
+custom_format = "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level}</level> | <white>{message}</white>"
+
+logger.add(sys.stdout, level="DEBUG", format=custom_format, colorize=True)
+
+
+class _Module(Enum):
+    COPIER = "copier"
+    BACKTEST = "backtest"
+    EXECUTION = "execution"
+    NEWS_FEED = "news_feed"
+
+
+FONT = pyfiglet.figlet_format("BBSTRADER", font="big")
+
+
+def main() -> None:
+    DESCRIPTION = "BBSTRADER"
+    USAGE_TEXT = """
+    Usage:
+        python -m bbstrader --run <module> [options]
+
+    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
+        news_feed: Send news feed from Coindesk to Telegram channel
+    
+    python -m bbstrader --run <module> --help for more information on the module
+    """
+    print(Fore.BLUE + FONT)
+    print(Fore.WHITE + "")
+    parser = argparse.ArgumentParser(
+        prog="BBSTRADER",
+        usage=USAGE_TEXT,
+        description=DESCRIPTION,
+        formatter_class=argparse.RawTextHelpFormatter,
+        add_help=False,
+    )
+    parser.add_argument("--run", type=str, nargs="?", default=None, help="Run a module")
+    args, unknown = parser.parse_known_args()
+    if ("-h" in sys.argv or "--help" in sys.argv) and args.run is None:
+        print(Fore.WHITE + USAGE_TEXT)
+        sys.exit(0)
+    if "-v" in sys.argv or "--version" in sys.argv:
+        print(Fore.GREEN + f"bbstrader version {__version__}")
+        print(Fore.WHITE + f"bbstrader maintained and supported by {__author__}")
+        sys.exit(0)
+    try:
+        match args.run:
+            case _Module.COPIER.value:
+                copy_trades(unknown)
+            case _Module.BACKTEST.value:
+                backtest(unknown)
+            case _Module.EXECUTION.value:
+                execute_strategy(unknown)
+            case _Module.NEWS_FEED.value:
+                send_news_feed(unknown)
+            case _:
+                print(Fore.RED + f"Unknown module: {args.run}")
+                sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as e:
+        print(Fore.RED + f"Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    multiprocessing.freeze_support()
+    try:
+        main()
+    except KeyboardInterrupt:
+        print(Fore.RED + "\nExecution interrupted by user")
+        sys.exit(0)
+    except Exception as e:
+        print(Fore.RED + f"Error: {e}")
+        sys.exit(1)

bbstrader/api/__init__.py

@@ -0,0 +1,96 @@
+"""
+Overview
+========
+
+The API Module provides a high-level client for interacting with the MetaTrader 5 platform.
+It serves as the primary interface for connecting to, retrieving data from, and sending commands
+to a MetaTrader 5 terminal from a Python application. The module is designed to simplify
+interactions and provide convenient data handling.
+
+Features
+========
+
+- **High-Level MT5 Client**: A simplified client (`Mt5client`) for easy access to MetaTrader 5 functionalities.
+- **Dynamic Object Representation**: Automatically patches MetaTrader 5 data objects for better string representation, making debugging easier.
+- **DataFrame Conversion**: Includes a utility function (`trade_object_to_df`) to quickly convert lists of MT5 trade objects (like deals, orders, positions) into pandas DataFrames for analysis.
+- **Handler-Based Architecture**: Uses a handler class (`Mt5Handlers`) to manage the underlying MetaTrader 5 API calls, promoting modularity.
+
+Components
+==========
+
+- **Mt5client**: The main client instance used to interact with the MetaTrader 5 terminal.
+- **Mt5Handlers**: A class that encapsulates the direct calls to the MetaTrader 5 API.
+- **Helper Functions**:
+  - `trade_object_to_df`: Converts lists of trade-related objects to pandas DataFrames.
+  - Dynamic patching of `__str__` and `__repr__` for improved object inspection.
+
+Notes
+=====
+
+This module requires a running MetaTrader 5 terminal and the `MetaTrader5` Python package to be installed.
+The connection is managed by the `Mt5client`.
+"""
+
+from operator import attrgetter
+
+import pandas as pd
+
+from bbstrader.api.handlers import Mt5Handlers
+from bbstrader.api.metatrader_client import *  # type: ignore # noqa: F403
+
+# ruff: noqa: F405
+classes_to_patch = [
+    AccountInfo,
+    BookInfo,
+    OrderCheckResult,
+    OrderSentResult,
+    RateInfo,
+    SymbolInfo,
+    TerminalInfo,
+    TickInfo,
+    TradeDeal,
+    TradeOrder,
+    TradePosition,
+    TradeRequest,
+]
+
+
+def dynamic_str(self):
+    fields = set()
+    for name in dir(self):
+        if name.startswith("_"):
+            continue
+        try:
+            value = getattr(self, name)
+            if not callable(value):
+                fields.add(f"{name}={value!r}")
+        except Exception:
+            pass
+    return f"{type(self).__name__}({', '.join(fields)})"
+
+
+for cls in classes_to_patch:
+    cls.__str__ = dynamic_str
+    cls.__repr__ = dynamic_str
+
+
+def trade_object_to_df(obj_list):
+    """
+    Fast conversion of a list of C++ bound objects to a pandas DataFrame.
+    """
+    if not obj_list:
+        return pd.DataFrame()
+
+    first_obj = obj_list[0]
+    columns = [
+        name
+        for name in dir(first_obj)
+        if not name.startswith("_") and not callable(getattr(first_obj, name))
+    ]
+    fetcher = attrgetter(*columns)
+    data = [fetcher(obj) for obj in obj_list]
+    df = pd.DataFrame(data, columns=columns)
+    return df
+
+
+Mt5client = MetaTraderClient(Mt5Handlers)

bbstrader/api/handlers.py

@@ -0,0 +1,245 @@
+from datetime import datetime
+
+import pytz
+
+from bbstrader.api.metatrader_client import (  # type: ignore
+    AccountInfo,
+    BookInfo,
+    MetaTraderHandlers,
+    OrderCheckResult,
+    OrderSentResult,
+    SymbolInfo,
+    TerminalInfo,
+    TickInfo,
+    TradeDeal,
+    TradeOrder,
+    TradePosition,
+    TradeRequest,
+)
+
+try:
+    import MetaTrader5 as mt5
+except ImportError:
+    import bbstrader.compat  # noqa: F401
+
+
+def _convert_obj(obj, obj_type):
+    """Converts a single MT5 object to the target C++ class instance."""
+    if obj is None:
+        return None
+
+    if hasattr(obj, "_asdict"):
+        field_data: dict = obj._asdict()
+        instance = obj_type()
+
+        for k, v in field_data.items():
+            if not hasattr(instance, k):
+                continue
+            if (
+                k == "request"
+                and hasattr(v, "_asdict")
+                and obj_type in (OrderCheckResult, OrderSentResult)
+            ):
+                setattr(instance, k, v._asdict())
+            else:
+                setattr(instance, k, v)
+
+        return instance
+    else:
+        raise TypeError(f"Expected MT5 namedtuple, got {type(obj)}")
+
+
+def _convert_list(obj_list, obj_type):
+    if obj_list is None:
+        return None
+    return [_convert_obj(obj, obj_type) for obj in obj_list]
+
+
+def _build_request(req: TradeRequest | dict) -> dict:
+    if isinstance(req, dict):
+        return req
+
+    request = {}
+    attrs = [
+        "action",
+        "magic",
+        "order",
+        "symbol",
+        "volume",
+        "price",
+        "stoplimit",
+        "sl",
+        "tp",
+        "deviation",
+        "type",
+        "type_filling",
+        "type_time",
+        "expiration",
+        "comment",
+        "position",
+        "position_by",
+    ]
+    enum_types = {"action", "type", "type_time", "type_filling"}
+    for attr in attrs:
+        val = getattr(req, attr)
+        if attr in enum_types or (val != 0 and val != ""):
+            request[attr] = val
+    return request
+
+
+def check_order(request: TradeRequest) -> OrderCheckResult:
+    return mt5.order_check(_build_request(request))
+
+
+def send_order(request: TradeRequest) -> OrderSentResult:
+    return mt5.order_send(_build_request(request))
+
+
+def get_time(ts):
+    timezone = pytz.timezone("UTC")
+    if isinstance(ts, datetime):
+        return ts
+    elif isinstance(ts, int):
+        return datetime.fromtimestamp(ts, tz=timezone)
+    else:
+        raise ValueError(f"Invalide Time format {type(ts)} must be and int or datetime")
+
+
+def get_mt5_handlers():
+    """
+    Exhaustively maps all MetaTrader 5 Python functions to the C++ Handlers struct,
+    converting return values to the appropriate types.
+    """
+    h = MetaTraderHandlers()
+
+    # 1. System & Session Management (Functions returning structs are wrapped)
+    h.init_auto = lambda: mt5.initialize()
+    h.init_path = lambda path: mt5.initialize(path)
+    h.init_full = (
+        lambda path, login, password, server, timeout, portable: mt5.initialize(
+            path=path,
+            login=login,
+            password=password,
+            server=server,
+            timeout=timeout,
+            portable=portable,
+        )
+    )
+    h.login = lambda login, password, server, timeout: mt5.login(
+        login=login, password=password, server=server, timeout=timeout
+    )
+    h.shutdown = mt5.shutdown
+    h.get_version = mt5.version
+    h.get_last_error = mt5.last_error
+    h.get_terminal_info = lambda: _convert_obj(mt5.terminal_info(), TerminalInfo)
+    h.get_account_info = lambda: _convert_obj(mt5.account_info(), AccountInfo)
+
+    # 2. Symbols & Market Depth (Level 2)
+    h.get_total_symbols = mt5.symbols_total
+    h.get_symbols_all = lambda: _convert_list(mt5.symbols_get(), SymbolInfo)
+    h.get_symbol_info = lambda symbol: _convert_obj(mt5.symbol_info(symbol), SymbolInfo)
+    h.select_symbol = mt5.symbol_select
+    h.get_symbols_by_group = lambda group: _convert_list(
+        mt5.symbols_get(group), SymbolInfo
+    )
+    h.subscribe_book = mt5.market_book_add
+    h.unsubscribe_book = mt5.market_book_release
+    h.get_book_info = lambda symbol: _convert_list(
+        mt5.market_book_get(symbol), BookInfo
+    )
+
+    # 3. Market Data (Rates & Ticks)
+    h.get_rates_by_date = (
+        lambda symbol, timeframe, date_from, count: mt5.copy_rates_from(
+            symbol, timeframe, get_time(date_from), count
+        )
+    )
+    h.get_rates_by_pos = (
+        lambda symbol, timeframe, start_pos, count: mt5.copy_rates_from_pos(
+            symbol, timeframe, start_pos, count
+        )
+    )
+    h.get_rates_by_range = (
+        lambda symbol, timeframe, date_from, date_to: mt5.copy_rates_range(
+            symbol, timeframe, get_time(date_from), get_time(date_to)
+        )
+    )
+    h.get_ticks_by_date = lambda symbol, date_from, count, flags: mt5.copy_ticks_from(
+        symbol, get_time(date_from), count, flags
+    )
+    h.get_ticks_by_range = (
+        lambda symbol, date_from, date_to, flags: mt5.copy_ticks_range(
+            symbol, get_time(date_from), get_time(date_to), flags
+        )
+    )
+
+    h.get_tick_info = lambda symbol: _convert_obj(
+        mt5.symbol_info_tick(symbol), TickInfo
+    )
+
+    # 4. Trading Operations
+    h.check_order = lambda request: _convert_obj(check_order(request), OrderCheckResult)
+    h.send_order = lambda request: _convert_obj(send_order(request), OrderSentResult)
+    h.calc_margin = mt5.order_calc_margin
+    h.calc_profit = mt5.order_calc_profit
+
+    # 5. Active Orders & Positions
+    h.get_orders_all = lambda: _convert_list(mt5.orders_get(), TradeOrder)
+    h.get_orders_by_symbol = lambda symbol: _convert_list(
+        mt5.orders_get(symbol=symbol), TradeOrder
+    )
+    h.get_orders_by_group = lambda group: _convert_list(
+        mt5.orders_get(group=group), TradeOrder
+    )
+    h.get_order_by_ticket = lambda ticket: _convert_obj(
+        (mt5.orders_get(ticket=ticket) or [None])[0], TradeOrder
+    )
+    h.get_total_orders = mt5.orders_total
+    h.get_positions_all = lambda: _convert_list(mt5.positions_get(), TradePosition)
+    h.get_positions_symbol = lambda symbol: _convert_list(
+        mt5.positions_get(symbol=symbol), TradePosition
+    )
+    h.get_positions_group = lambda group: _convert_list(
+        mt5.positions_get(group=group), TradePosition
+    )
+    h.get_position_ticket = lambda ticket: _convert_obj(
+        (mt5.positions_get(ticket=ticket) or [None])[0], TradePosition
+    )
+    h.get_total_positions = mt5.positions_total
+
+    # 6. Trade History (Orders & Deals)
+    h.get_hist_orders_group = lambda date_from, date_to, group: _convert_list(
+        mt5.history_orders_get(get_time(date_from), get_time(date_to), group=group),
+        TradeOrder,
+    )
+    h.get_hist_orders_range = lambda date_from, date_to: _convert_list(
+        mt5.history_orders_get(get_time(date_from), get_time(date_to)),
+        TradeOrder,
+    )
+    h.get_hist_order_ticket = lambda ticket: _convert_obj(
+        mt5.history_orders_get(ticket=ticket), TradeOrder
+    )
+    h.get_hist_orders_pos = lambda position: _convert_list(
+        mt5.history_orders_get(position=position), TradeOrder
+    )
+    h.get_hist_orders_total = mt5.history_orders_total
+    h.get_hist_deals_group = lambda date_from, date_to, group: _convert_list(
+        mt5.history_deals_get(get_time(date_from), get_time(date_to), group=group),
+        TradeDeal,
+    )
+    h.get_hist_deals_range = lambda date_from, date_to: _convert_list(
+        mt5.history_deals_get(get_time(date_from), get_time(date_to)), TradeDeal
+    )
+
+    h.get_hist_deals_ticket = lambda ticket: _convert_obj(
+        mt5.history_deals_get(ticket=ticket), TradeDeal
+    )
+    h.get_hist_deals_pos = lambda position: _convert_list(
+        mt5.history_deals_get(position=position), TradeDeal
+    )
+    h.get_hist_deals_total = mt5.history_deals_total
+
+    return h
+
+
+Mt5Handlers = get_mt5_handlers()