Forem: Ichinga Samuel

AIOMQL-The Complete Guide to Building Algorithmic Trading Bots with Python & MetaTrader 5

Ichinga Samuel — Sat, 28 Feb 2026 20:48:57 +0000

What is aiomql?

aiomql is a Python framework for building algorithmic trading bots on top of
MetaTrader 5. Rather than writing raw MT5 API calls and managing connection boilerplate, aiomql gives you:

An async-first MetaTrader 5 interface — every MT5 function wrapped with asyncio.to_thread and automatic reconnection on transient errors.
High-level abstractions — Strategy, Bot, Trader, Order, Symbol, Sessions, RAM, and more — so you can focus on trading logic.
A full synchronous API — every async class has a sync counterpart for scripts, notebooks, and quick prototyping.
Built-in technical analysis — pandas-ta integration with optional TA-Lib support.
Trade recording — persist results to CSV, JSON, or SQLite automatically.
Position tracking — monitor open positions with trailing stops, extending take-profits, hedging, and stacking.
Multi-process execution — run independent bots in parallel with a single call.

aiomql is designed for traders who want to build, test, and deploy algorithmic strategies in Python without reinventing the wheel.

Installation & Requirements

Prerequisites

Requirement	Details
Python	≥ 3.13
OS	Windows (MetaTrader 5 terminal requirement)
Account	A MetaTrader 5 trading account (demo or live)

Install via pip

pip install aiomql

Optional Extras

# TA-Lib technical indicators
pip install aiomql[talib]

# Optional accelerators (Cython, Numba, tqdm)
pip install aiomql[optional]

# Everything
pip install aiomql[all]

Configuration

aiomql uses a singleton Config class that can load settings from a JSON file or be configured programmatically. This single configuration object is shared across all components.

Option 1: JSON Configuration File

Create an aiomql.json file in your project root:

{
  "login": 12345678,
  "password": "your_password",
  "server": "YourBroker-Demo",
  "trade_record_mode": "csv"
}

The Config class automatically searches for aiomql.json in your project directory tree, starting from the current working directory and walking up to the root.

Option 2: Programmatic Configuration

from aiomql import Config

config = Config(
    login=12345678,
    password="your_password",
    server="YourBroker-Demo",
    trade_record_mode="csv"
)

Key Configuration Options

Setting	Type	Description
`login`	`int`	MetaTrader account number
`password`	`str`	Account password
`server`	`str`	Broker server name
`path`	`str`	Path to the MT5 terminal executable
`trade_record_mode`	`str`	Trade logging format: `"csv"`, `"json"`, or `"sql"`
`root`	`str`	Project root directory

Because Config is a singleton, any component in your application that creates a Config() instance receives the same shared configuration.

State & Store

The Config class also provides access to two persistent storage mechanisms:

config.state — A State object for persistent key-value storage (backed by SQLite).
config.store — A Store object for in-memory shared state accessible across components. These are useful for sharing data between strategies, trackers, and other components at runtime.

Connecting to MetaTrader 5

The MetaTrader class wraps every MT5 API function with async execution and automatic retry logic. It supports both async context manager usage and direct calls.

Basic Connection

import asyncio
from aiomql import MetaTrader

async def main():
    async with MetaTrader() as mt5:
        # Get account information
        account = await mt5.account_info()
        print(f"Balance: {account.balance}")
        print(f"Equity: {account.equity}")

        # Get terminal info
        terminal = await mt5.terminal_info()
        print(f"Terminal: {terminal.name}")

        # Get available symbols
        symbols = await mt5.symbols_get()
        print(f"{len(symbols)} symbols available")


asyncio.run(main())

How It Works

Under the hood, MetaTrader runs every MT5 call through asyncio.to_thread, which means your event loop stays responsive even during blocking I/O. If a connection
error occurs, the _handler method automatically retries initialization and login up to 3 times.

# The MetaTrader class is also a singleton — every instance shares the same state
mt5_a = MetaTrader()
mt5_b = MetaTrader()
assert mt5_a is mt5_b  # True

Key Methods

Method	Description
`initialize()`	Connect to the MT5 terminal
`login()`	Log in with credentials
`shutdown()`	Close the connection
`account_info()`	Get account details
`terminal_info()`	Get terminal details
`symbols_get()`	List available symbols
`symbol_info()`	Get info for a specific symbol
`copy_rates_from()`	Fetch OHLC bar data
`copy_rates_from_pos()`	Fetch recent bars by count
`copy_ticks_from()`	Fetch tick data
`order_check()`	Check if an order can be executed
`order_send()`	Send a trade order
`positions_get()`	Get open positions
`history_deals_get()`	Get historical deals
`history_orders_get()`	Get historical orders

Working with Symbols

The Symbol class is a high-level wrapper around a financial instrument. It pulls properties from MT5 (spread, lot sizes, contract size, etc.) and provides methods to fetch market data.

Initializing a Symbol

from aiomql import Symbol

async def main():
    symbol = Symbol(name="EURUSD")
    await symbol.initialize()

    # Now you can access all symbol properties
    print(f"Spread: {symbol.spread}")
    print(f"Point: {symbol.point}")
    print(f"Min volume: {symbol.volume_min}")
    print(f"Max volume: {symbol.volume_max}")
    print(f"Volume step: {symbol.volume_step}")
    print(f"Contract size: {symbol.trade_contract_size}")

Getting Price Data

# Get the current tick
tick = await symbol.info_tick()
print(f"Bid: {tick.bid}, Ask: {tick.ask}")

# Get the last 500 H1 candles
from aiomql import TimeFrame

candles = await symbol.copy_rates_from_pos(
    timeframe=TimeFrame.H1, count=500
)

Volume Utilities

The Symbol class includes helpers for working with lot sizes:

# Check if a volume is valid
is_valid, adjusted = symbol.check_volume(volume=0.15)

# Round volume to the nearest step
rounded = symbol.round_off_volume(volume=0.153, round_down=True)

Currency Conversion

# Convert between currencies using live rates
amount_in_usd = await symbol.convert_currency(
    amount=100.0,
    from_currency="EUR",
    to_currency="USD"
)

ForexSymbol — Specialized for Forex

The ForexSymbol class extends Symbol with forex-specific calculations:

from aiomql import ForexSymbol

eurusd = ForexSymbol(name="EURUSD")
await eurusd.initialize()

# Pip value (point * 10)
print(f"Pip: {eurusd.pip}")  # 0.0001 for most pairs

# Compute volume based on risk amount and stop loss distance
volume = await eurusd.compute_volume_sl(
    amount=100.0,     # risk $100
    price=1.1000,     # entry price
    sl=1.0950,        # stop loss
    round_down=True
)

# Compute volume based on risk amount and points
volume = await eurusd.compute_volume_points(
    amount=100.0,
    points=500,
    round_down=True
)

# Compute points needed for a given profit at a given volume
points = eurusd.compute_points(amount=50.0, volume=0.1)

Market Data: Candles & Ticks

Candles

The Candles class wraps pandas DataFrame with trading-specific functionality.
When you fetch rates from a Symbol, you receive a Candles object:

from aiomql import TimeFrame

candles = await symbol.copy_rates_from_pos(
    timeframe=TimeFrame.H1, count=500
)

# It's a DataFrame under the hood
print(candles.data.head())

# Access individual candles by index
last_candle = candles[-1]
print(f"Open: {last_candle.open}, Close: {last_candle.close}")

# Candle properties
print(f"Body: {last_candle.body}")
print(f"Range: {last_candle.range}")
print(f"Is Bullish: {last_candle.is_bullish()}")
print(f"Is Bearish: {last_candle.is_bearish()}")
print(f"Is Doji: {last_candle.is_doji()}")

# DataFrame columns are accessible directly
print(candles.open)   # Series of open prices
print(candles.close)  # Series of close prices
print(candles.high)   # Series of high prices
print(candles.low)    # Series of low prices

Renaming Columns

# Rename DataFrame columns (useful after adding indicators)
candles.rename(
    EMA_34="fast_ema",
    EMA_55="slow_ema",
    inplace=True
)

Ticks

The Tick class represents a single price tick, and Ticks is a collection:

# Get recent ticks
ticks = await symbol.copy_ticks_from(
    date_from=datetime.now() - timedelta(minutes=5),
    count=1000
)

# Access tick data
for tick in ticks:
    print(f"Time: {tick.time}, Bid: {tick.bid}, Ask: {tick.ask}")

# The Ticks object also supports technical analysis
ticks.ta.sma(length=20, append=True)

Technical Analysis

aiomql integrates pandas-ta (classic) out of the box, available through the .ta accessor on Candles and Ticks objects. Every pandas-ta indicator is available
directly.

Using pandas-ta Indicators

candles = await symbol.copy_rates_from_pos(
    timeframe=TimeFrame.H1, count=500
)

# Moving averages
candles.ta.sma(length=20, append=True)
candles.ta.ema(length=50, append=True)

# RSI
candles.ta.rsi(length=14, append=True)

# MACD
candles.ta.macd(fast=12, slow=26, signal=9, append=True)

# Bollinger Bands
candles.ta.bbands(length=20, std=2, append=True)

# ATR
candles.ta.atr(length=14, append=True)

# Stochastic
candles.ta.stoch(k=14, d=3, append=True)

# Access the results as DataFrame columns
print(candles.data.columns.tolist())

The ta_lib Helper

The Candles object also includes a ta_lib helper with convenience functions:

# Check if series A is above series B
above = candles.ta_lib.above(candles.fast_ema, candles.slow_ema)

# Check if series A is below series B
below = candles.ta_lib.below(candles.fast_ema, candles.slow_ema)

Optional: TA-Lib Integration

If you install aiomql[talib], you get access to the full C-based TA-Lib library for high-performance indicator computation.

Placing Orders

The Order class handles all trade order operations. It's a subclass of
TradeRequest and provides methods for checking, sending, and managing orders.

Creating and Sending a Market Order

from aiomql import Order, OrderType, TradeAction

# Create a buy order
order = Order(
    symbol="EURUSD",
    type=OrderType.BUY,
    volume=0.1,
    price=1.1000,
    sl=1.0950,
    tp=1.1100
)

# Check if the order can be executed
check_result = await order.check()
print(f"Margin required: {check_result.margin}")

# Send the order
result = await order.send()
print(f"Order ticket: {result.order}")
print(f"Return code: {result.retcode}")

Modifying an Order

order.modify(
    sl=1.0960,
    tp=1.1120
)

Margin and Profit Calculations

# Calculate required margin
margin = await order.calc_margin()
print(f"Margin needed: {margin}")

# Calculate expected profit (at take-profit level)
profit = await order.calc_profit()
print(f"Expected profit: {profit}")

# Calculate expected loss (at stop-loss level)
loss = await order.calc_loss()
print(f"Expected loss: {loss}")

Pending Order Management

# Get total pending orders
total = await Order.orders_total()

# Get all pending orders
pending = await Order.get_pending_orders()

# Get a specific pending order by ticket
order = await Order.get_pending_order(ticket=123456)

# Cancel a pending order
await Order.cancel_order(order=123456, symbol="EURUSD")

Connection Retry Logic

The send_order method automatically retries on connection errors (retcode 10031)
with exponential backoff, up to 3 retries.

The Trader Abstraction

While Order handles the low-level mechanics, the Trader class provides a
higher-level interface for placing trades with proper risk management and trade
recording.

Why Use Trader?

Trader ties together the Order, Symbol, and RAM (risk manager) classes
into a cohesive workflow:

Calculate position size based on your risk parameters
Set stop-loss and take-profit levels
Check the order before sending
Send the order and handle errors
Record the trade to your chosen storage format

Creating Orders with Stops

from aiomql import Trader, ForexSymbol, RAM, OrderType

symbol = ForexSymbol(name="EURUSD")
await symbol.initialize()

ram = RAM(risk=2, risk_to_reward=3)  # 2% risk, 1:3 R:R
trader = Trader(symbol=symbol, ram=ram)

# Create order with stop-loss and take-profit using absolute prices
await trader.create_order_with_stops(
    order_type=OrderType.BUY,
    sl=1.0950,
    tp=1.1150
)

# Create order with just a stop-loss (TP calculated from R:R ratio)
await trader.create_order_with_sl(
    order_type=OrderType.BUY,
    sl=1.0950
)

# Create order using points distance
await trader.create_order_with_points(
    order_type=OrderType.BUY,
    points=500
)

# Create a simple order with no stops
await trader.create_order_no_stops(
    order_type=OrderType.BUY,
    volume=0.01
)

Checking and Sending

# Check if the order passes broker validation
can_trade = await trader.check_order()

if can_trade:
    result = await trader.send_order()

Recording Trades

After sending, trades are automatically recorded via the record_trade method:

await trader.record_trade(
    result=result,
    parameters={"strategy": "EMA Crossover"},
    name="EMAXOver",
    expected_profit=25.50
)

Pre-Built Traders

aiomql ships with two ready-to-use Trader subclasses in the contrib package:

SimpleTrader

Places trades with a specified stop-loss. Volume is calculated based on the RAM
risk amount and the distance to the stop-loss.

from aiomql import SimpleTrader, ForexSymbol, OrderType

symbol = ForexSymbol(name="EURUSD")
trader = SimpleTrader(symbol=symbol)

await trader.place_trade(
    order_type=OrderType.BUY,
    sl=1.0950,
    parameters={"name": "MyStrategy"}
)

ScalpTrader

Places trades using minimum volume and no stop-loss/take-profit levels.
Ideal for scalping strategies where positions are managed manually.

from aiomql import ScalpTrader, ForexSymbol, OrderType

symbol = ForexSymbol(name="EURUSD")
trader = ScalpTrader(symbol=symbol)

await trader.place_trade(
    order_type=OrderType.BUY,
    parameters={"name": "ScalpBot"}
)

Risk & Money Management (RAM)

The RAM (Risk Assessment & Money) class is at the heart of aiomql's risk
management. It calculates position sizes, enforces trade limits, and manages
your exposure.

Configuration

from aiomql import RAM

ram = RAM(
    risk=2,              # Risk 2% of free margin per trade
    risk_to_reward=3,    # 1:3 risk-to-reward ratio
    min_amount=5,        # Minimum $5 risk per trade
    max_amount=500,      # Maximum $500 risk per trade
    loss_limit=3,        # Max 3 losing positions at once
    open_limit=5,        # Max 5 total open positions
    fixed_amount=None    # Set to override percentage-based calculation
)

Calculating Risk Amount

# Get the amount to risk per trade (based on free margin)
amount = await ram.get_amount()
print(f"Amount to risk: ${amount:.2f}")

# If fixed_amount is set, it always returns that
ram.modify_ram(fixed_amount=100.0)
amount = await ram.get_amount()  # Always $100

Enforcing Position Limits

# Check if we can open a new position
can_open = await ram.check_open_positions()
if not can_open:
    print("Too many open positions!")

# Check if we've hit the loss limit
can_trade = await ram.check_losing_positions()
if not can_trade:
    print("Too many losing positions!")

How the Amount is Calculated

The calculation flow is:

If fixed_amount is set → return fixed_amount
Otherwise → margin_free × (risk / 100)
If min_amount and max_amount are set → clamp the result

Building a Strategy

The Strategy class is the cornerstone of aiomql. You subclass it, define your
parameters, and implement the trade() method. The framework handles everything
else — initialization, the execution loop, session management, and error handling.

Anatomy of a Strategy

from aiomql import Strategy, ForexSymbol, TimeFrame, Tracker, OrderType, Sessions, ScalpTrader


class MyStrategy(Strategy):
    # Type annotations for strategy-specific parameters
    ttf: TimeFrame
    fast_period: int
    slow_period: int
    tracker: Tracker

    # Default parameter values — these become instance attributes
    parameters = {
        "ttf": TimeFrame.H1,
        "fast_period": 20,
        "slow_period": 50,
    }

    def __init__(self, *, symbol: ForexSymbol, params: dict = None,
                 sessions: Sessions = None, name: str = "MyStrategy"):
        super().__init__(symbol=symbol, params=params, sessions=sessions, name=name)
        self.tracker = Tracker(snooze=self.ttf.seconds)
        self.trader = ScalpTrader(symbol=self.symbol)

    async def trade(self):
        """This method is called repeatedly by the execution loop."""
        # 1. Fetch market data
        candles = await self.symbol.copy_rates_from_pos(
            timeframe=self.ttf, count=200
        )

        # 2. Apply indicators
        candles.ta.sma(length=self.fast_period, append=True)
        candles.ta.sma(length=self.slow_period, append=True)
        candles.rename(
            **{f"SMA_{self.fast_period}": "fast",
               f"SMA_{self.slow_period}": "slow"},
            inplace=True
        )

        # 3. Check for signals
        if candles.ta_lib.above(candles.fast, candles.slow).iloc[-1]:
            self.tracker.update(order_type=OrderType.BUY, snooze=3600)
        elif candles.ta_lib.below(candles.fast, candles.slow).iloc[-1]:
            self.tracker.update(order_type=OrderType.SELL, snooze=3600)
        else:
            self.tracker.update(order_type=None, snooze=self.ttf.seconds)

        # 4. Execute or sleep
        if self.tracker.order_type is not None:
            await self.trader.place_trade(
                order_type=self.tracker.order_type,
                parameters=self.parameters
            )
            await self.delay(secs=self.tracker.snooze)
        else:
            await self.sleep(secs=self.tracker.snooze)

Key Concepts

Parameters Dictionary

The parameters class attribute defines default values for your strategy. When you
instantiate the strategy, you can override any parameter via the params argument:

strategy = MyStrategy(
    symbol=ForexSymbol(name="EURUSD"),
    params={"fast_period": 10, "slow_period": 30}
)

Parameters are also accessible as attributes thanks to __getattr__:

print(strategy.fast_period)  # 10

The Tracker

The Tracker (from aiomql.contrib.utils) is a lightweight state holder for
strategies. It stores the current order_type, a snooze duration, and any extra
state you want to track:

from aiomql import Tracker

tracker = Tracker(snooze=300)  # default snooze of 5 minutes

# Update tracker state
tracker.update(
    order_type=OrderType.BUY,
    snooze=3600,
    trend="bullish",
    last_price=1.1050
)

# Access state
print(tracker.order_type)  # OrderType.BUY
print(tracker.trend)       # "bullish"

Sleep vs Delay

self.sleep(secs=...) — Computes the exact time until the next bar opens, ensuring your strategy wakes up right at the start of a new candle. This is critical for cooperative multitasking.
self.delay(secs=...) — A simple asyncio.sleep for the given duration.

Initialization

Override initialize() to run one-time setup. By default, it initializes the
symbol:

async def initialize(self):
    """Called once before the strategy starts trading."""
    result = await self.symbol.initialize()
    # Load historical data, train models, etc.
    return result

Stopping a Strategy

Raise StopTrading from within trade() to gracefully stop the strategy:

from aiomql.core.exceptions import StopTrading

async def trade(self):
    if some_condition:
        raise StopTrading("Reached daily profit target")

Trading Sessions

Sessions let you restrict when a strategy can trade. This is essential for forex
markets where different sessions (London, New York, Tokyo) have different
characteristics.

Defining Sessions

from datetime import time
from aiomql import Session, Sessions

# Define individual sessions (times are in UTC)
london = Session(
    name="London",
    start=time(8, 0),
    end=time(16, 0)
)

new_york = Session(
    name="New York",
    start=time(13, 0),
    end=time(21, 0)
)

tokyo = Session(
    name="Tokyo",
    start=time(0, 0),
    end=time(9, 0)
)

Session Actions

Sessions can automatically execute actions at their start and end:

# Close all positions when the London session ends
london = Session(
    name="London",
    start=time(8, 0),
    end=time(16, 0),
    on_end="close_all"
)

# Close only losing positions at session end
new_york = Session(
    name="New York",
    start=time(13, 0),
    end=time(21, 0),
    on_end="close_loss"
)

# Close only winning positions
tokyo = Session(
    name="Tokyo",
    start=time(0, 0),
    end=time(9, 0),
    on_end="close_win"
)

# Custom actions
async def my_start_action(session):
    print(f"{session.name} started!")

async def my_end_action(session):
    print(f"{session.name} ended!")

custom = Session(
    name="Custom",
    start=time(10, 0),
    end=time(18, 0),
    on_start="custom_start",
    on_end="custom_end",
    custom_start=my_start_action,
    custom_end=my_end_action
)

Combining Sessions

Group sessions together with the Sessions class. When a strategy uses
Sessions, the framework automatically:

Checks if the current time falls within any session
Waits (sleeps) if outside all sessions
Handles transitions between sessions (closing the previous, opening the next)

sessions = Sessions(sessions=[london, new_york])

strategy = MyStrategy(
    symbol=ForexSymbol(name="EURUSD"),
    sessions=sessions
)

Session Utilities

# Check if currently in session
print(london.in_session())

# Get session duration
duration = london.duration()
print(f"Duration: {duration.hours}h {duration.minutes}m")

# Seconds until session starts
secs = london.until()
print(f"Session starts in {secs} seconds")

The Bot Orchestrator

The Bot class is the top-level orchestrator that brings everything together.
It manages the MT5 terminal connection, initializes strategies, and coordinates
their execution.

Basic Usage

from aiomql import Bot, ForexSymbol
from my_strategies import EMAXOver, RSIStrategy

def main():
    # Create symbols
    symbols = [ForexSymbol(name=s) for s in ["EURUSD", "GBPUSD", "USDJPY"]]

    # Create strategies
    strategies = [EMAXOver(symbol=sym) for sym in symbols]

    # Create bot and add strategies
    bot = Bot()
    bot.add_strategies(strategies)

    # Run (blocks until shutdown)
    bot.execute()


if __name__ == "__main__":
    main()

Adding Coroutines

You can add background coroutines that run alongside your strategies:

async def log_account_status():
    """Periodically log account balances."""
    from aiomql import Account
    account = Account()
    while True:
        await account.refresh()
        print(f"Balance: {account.balance}, Equity: {account.equity}")
        await asyncio.sleep(60)


bot = Bot()
bot.add_strategies(strategies)

# Runs in the same event loop
bot.add_coroutine(coroutine=log_account_status)

# Runs on a separate thread (for CPU-intensive or blocking tasks)
bot.add_coroutine(
    coroutine=some_blocking_task,
    on_separate_thread=True
)

Adding Functions

For synchronous functions that should run in a thread pool:

import time

def heartbeat(interval=30):
    while True:
        print("Bot is alive...")
        time.sleep(interval)


bot.add_function(function=heartbeat, interval=30)

Async Entry Point

If you're already inside an async context, use start() instead of execute():

async def main():
    bot = Bot()
    bot.add_strategies(strategies)
    await bot.start()

asyncio.run(main())

What Happens Inside

When you call bot.execute():

Terminal Start — connects to the MT5 terminal and logs in
Strategy Initialization — each strategy's initialize() is called; strategies that fail are silently skipped
Executor Start — the Executor runs all strategies, coroutines, and functions concurrently using asyncio tasks and thread pools

Position Tracking

aiomql provides a sophisticated position tracking system through the contrib.trackers
package. This allows you to monitor open positions and apply automated management rules.

OpenPosition

The OpenPosition class wraps a trade position with tracking, hedging, and stacking
capabilities:

from aiomql import OpenPosition, PositionTracker

# Create an OpenPosition from a trade result
pos = OpenPosition(
    ticket=123456,
    symbol="EURUSD",
    # ... other position details
)

# Modify stop-loss and take-profit
await pos.modify_stops(sl=1.0960, tp=1.1120)

# Close the position
success, result = await pos.close_position()

# Add custom trackers to the position
pos.add_tracker(tracker=my_tracker, name="trailing_stop")

Position Tracking Functions

aiomql includes pre-built tracking functions:

exit_at_profit — Close a position when profit reaches a target price
extend_take_profit — Dynamically extend the take-profit as price moves favorably

OpenPositionsTracker

The OpenPositionsTracker manages all open positions and runs their trackers
automatically:

from aiomql import Bot, OpenPositionsTracker

bot = Bot()
bot.add_strategies(strategies)

# Track all open positions on a separate thread
bot.add_coroutine(
    coroutine=OpenPositionsTracker(autocommit=True).track,
    on_separate_thread=True
)

bot.execute()

This automatically:

Discovers all open positions
Runs any registered trackers on each position
Handles position closure and cleanup
Manages hedges, stacks, and pending orders

Trade Result Recording

Every trade can be automatically recorded for analysis. The Result class supports
three storage formats:

CSV

# In your Config or aiomql.json
config = Config(trade_record_mode="csv")

# Trades are saved to: <root>/trade_records/<strategy_name>.csv

JSON

config = Config(trade_record_mode="json")

# Trades are saved to: <root>/trade_records/<strategy_name>.json

SQLite

config = Config(trade_record_mode="sql")

# Trades are saved to a SQLite database in your project root

What Gets Recorded?

Each trade record includes:

Order result — ticket, deal, volume, price, retcode
Strategy parameters — all parameters from the strategy's parameters dict
Trade request — the actual request sent to the broker
Extras — timestamp, expected profit, strategy name

Manual Recording

from aiomql import Result
from aiomql.core.models import OrderSendResult

result = Result(
    result=order_send_result,
    parameters={"strategy": "EMA", "timeframe": "H1"},
    name="EMAXOver",
    expected_profit=25.0
)

await result.save(trade_record_mode="csv")

Trade History

The History class lets you retrieve completed deals and orders from your account
history:

from datetime import datetime, timedelta
from aiomql import History

# Get the last 7 days of history
history = History(
    date_from=datetime.now() - timedelta(days=7),
    date_to=datetime.now()
)

# Fetch deals and orders
await history.initialize()

# Access deals
print(f"Total deals: {history.total_deals}")
for deal in history.deals:
    print(f"  {deal.symbol}: {deal.profit}")

# Access orders
print(f"Total orders: {history.total_orders}")

# Filter by ticket
deals = history.filter_deals_by_ticket(ticket=123456)

# Filter by position ID
deals = history.filter_deals_by_position(position=789012)

# Filter by symbol group (e.g., only USD pairs)
history = History(
    date_from=datetime.now() - timedelta(days=30),
    date_to=datetime.now(),
    group="*USD*"
)

Contributed Extensions

The contrib package contains community extensions that build on the core framework.

Strategies

Chaos

A demo strategy that randomly buys or sells. Useful for testing your infrastructure:

from aiomql import Chaos, ForexSymbol

strategy = Chaos(symbol=ForexSymbol(name="EURUSD"))

Symbols

ForexSymbol

Specialized Symbol subclass with pip calculations and volume computation based on
stop-loss distance. See the Symbols section above for details.

Traders

SimpleTrader

Trades with a stop-loss, calculating volume from risk.
See above.

ScalpTrader

Trades with minimum volume and no stops.
See above.

Trackers

Tracker (Strategy Tracker)

A lightweight state holder for tracking strategy signals and snooze timers.
See the Strategy section.

PositionTracker

Wraps a tracking function to execute on an open position.

OpenPositionsTracker

Automatically discovers and manages all open positions.
See the Position Tracking section.

Multi-Process Execution

For running completely independent bots in parallel, use Bot.process_pool():

from aiomql import Bot, ForexSymbol
from strategies import ForexStrategy, CryptoStrategy


def run_forex():
    bot = Bot()
    symbols = [ForexSymbol(name=s) for s in ["EURUSD", "GBPUSD"]]
    strategies = [ForexStrategy(symbol=s) for s in symbols]
    bot.add_strategies(strategies)
    bot.execute()


def run_crypto():
    bot = Bot()
    symbols = [ForexSymbol(name=s) for s in ["BTCUSD", "ETHUSD"]]
    strategies = [CryptoStrategy(symbol=s) for s in symbols]
    bot.add_strategies(strategies)
    bot.execute()


# Run both bots in separate processes
Bot.process_pool(
    processes={
        run_forex: {},
        run_crypto: {}
    },
    num_workers=2
)

Each process gets its own event loop, MT5 connection, and strategy set. This is
useful when you want complete isolation between different trading systems.

Synchronous API

Every async class in aiomql has a synchronous counterpart. This makes the library
usable in Jupyter notebooks, simple scripts, or anywhere you don't want to deal with
asyncio.

Synchronous MetaTrader

from aiomql.core.sync import MetaTrader as SyncMetaTrader

mt5 = SyncMetaTrader()
mt5.initialize_sync()
mt5.login_sync(login=12345678, password="your_password", server="YourBroker-Demo")

account = mt5._account_info()
print(f"Balance: {account.balance}")

mt5.shutdown()

Synchronous Strategy Initialization

# The Bot class handles sync initialization internally
bot = Bot()
bot.execute()  # Uses sync initialization under the hood

Synchronous RAM

ram = RAM(risk=2)
amount = ram.get_amount_sync()
can_trade = ram.check_open_positions_sync()

Full Example: EMA Crossover Bot

Here's a complete, production-ready example that puts everything together:

Project Structure

my_trading_bot/
├── aiomql.json
├── strategies/
│   ├── __init__.py
│   └── ema_crossover.py
└── bot.py

aiomql.json

{
  "login": 12345678,
  "password": "your_password",
  "server": "YourBroker-Demo",
  "trade_record_mode": "csv"
}

strategies/ema_crossover.py

from aiomql import (
    Strategy, ForexSymbol, TimeFrame, Tracker,
    OrderType, Sessions, ScalpTrader
)


class EMAXOver(Strategy):
    """EMA Crossover strategy.

    Buys when the fast EMA crosses above the slow EMA.
    Sells when the fast EMA crosses below the slow EMA.
    """

    ttf: TimeFrame
    tcc: int
    fast_ema: int
    slow_ema: int
    tracker: Tracker
    interval: TimeFrame
    timeout: int

    parameters = {
        "ttf": TimeFrame.H1,
        "tcc": 3000,
        "fast_ema": 34,
        "slow_ema": 55,
        "interval": TimeFrame.M15,
        "timeout": 3 * 60 * 60,  # 3 hours cooldown after a trade
    }

    def __init__(self, *, symbol: ForexSymbol, params: dict = None,
                 sessions: Sessions = None, name: str = "EMAXOver"):
        super().__init__(
            symbol=symbol, params=params,
            sessions=sessions, name=name
        )
        self.tracker = Tracker(snooze=self.interval.seconds)
        self.trader = ScalpTrader(symbol=self.symbol)

    async def find_entry(self):
        # Fetch candle data
        candles = await self.symbol.copy_rates_from_pos(
            timeframe=self.ttf, count=self.tcc
        )

        # Calculate EMAs
        candles.ta.ema(length=self.fast_ema, append=True)
        candles.ta.ema(length=self.slow_ema, append=True)
        candles.rename(
            **{f"EMA_{self.fast_ema}": "fast_ema",
               f"EMA_{self.slow_ema}": "slow_ema"},
            inplace=True,
        )

        # Check for crossover signals
        fast_above_slow = candles.ta_lib.above(
            candles.fast_ema, candles.slow_ema
        )
        fast_below_slow = candles.ta_lib.below(
            candles.fast_ema, candles.slow_ema
        )

        if fast_above_slow.iloc[-1]:
            self.tracker.update(
                order_type=OrderType.BUY,
                snooze=self.timeout
            )
        elif fast_below_slow.iloc[-1]:
            self.tracker.update(
                order_type=OrderType.SELL,
                snooze=self.timeout
            )
        else:
            self.tracker.update(
                order_type=None,
                snooze=self.interval.seconds
            )

    async def trade(self):
        await self.find_entry()

        if self.tracker.order_type is None:
            # No signal — sleep until next bar
            await self.sleep(secs=self.tracker.snooze)
        else:
            # Signal found — place trade and cooldown
            await self.trader.place_trade(
                order_type=self.tracker.order_type,
                parameters=self.parameters,
            )
            await self.delay(secs=self.tracker.snooze)

bot.py

import logging
from aiomql import Bot, ForexSymbol, OpenPositionsTracker
from strategies.ema_crossover import EMAXOver

logging.basicConfig(level=logging.INFO)


def main():
    # Define symbols to trade
    symbols = [
        ForexSymbol(name=s)
        for s in ["EURUSD", "GBPUSD", "USDJPY"]
    ]

    # Create a strategy instance for each symbol
    strategies = [EMAXOver(symbol=sym) for sym in symbols]

    # Create the bot
    bot = Bot()
    bot.add_strategies(strategies)

    # Track open positions on a separate thread
    bot.add_coroutine(
        coroutine=OpenPositionsTracker(autocommit=True).track,
        on_separate_thread=True
    )

    # Start trading
    bot.execute()


if __name__ == "__main__":
    main()

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                     Bot (Orchestrator)               │
│  ┌──────────────────────────────────────────────┐   │
│  │               Executor                        │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────────────┐│   │
│  │  │Strategy 1│ │Strategy 2│ │  Coroutines/    ││   │
│  │  │(EURUSD) │ │(GBPUSD) │ │  Functions       ││   │
│  │  └────┬────┘ └────┬────┘ └────────┬────────┘│   │
│  └───────┼───────────┼───────────────┼──────────┘   │
│          │           │               │               │
│  ┌───────▼───────────▼───────────────▼──────────┐   │
│  │                Shared Services                 │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐│   │
│  │  │ Config │ │MetaTrader│ │  RAM   │ │ Result ││   │
│  │  │(single)│ │(single) │ │        │ │        ││   │
│  │  └────────┘ └────────┘ └────────┘ └────────┘│   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────┐
│  MetaTrader 5       │
│  Terminal           │
│  (asyncio.to_thread)│
└─────────────────────┘

Design Principles

Singletons — Config and MetaTrader in some cases are singletons, ensuring consistent state across all components.
Async-first — Every MT5 call is wrapped with asyncio.to_thread, keeping the event loop responsive.
Composition — Components are designed to be composed. A Strategy uses a Symbol, Trader, RAM, and Sessions.
Separation of concerns — Market data (Symbol, Candles, Ticks), trade execution (Order, Trader), risk management (RAM), and orchestration (Bot, Executor) are all separate modules.

Summary

Feature	Module	Description
MT5 Connection	`MetaTrader`	Async MT5 interface with retry
Configuration	`Config`	Singleton JSON/programmatic config
Market Data	`Symbol`, `Candles`, `Ticks`	Symbols, OHLC bars, tick data
Technical Analysis	`ta_libs`	pandas-ta + optional TA-Lib
Orders	`Order`	Check, send, margin/profit calc
Trade Execution	`Trader`, `SimpleTrader`, `ScalpTrader`	High-level trade placement
Risk Management	`RAM`	Position sizing, trade limits
Strategy	`Strategy`	Base class for trading logic
Sessions	`Session`, `Sessions`	Time-window trading restrictions
Orchestration	`Bot`, `Executor`	Multi-strategy concurrent execution
Position Tracking	`OpenPositionsTracker`, `OpenPosition`	Trailing stops, hedging, stacking
Trade Recording	`Result`	CSV, JSON, SQLite persistence
History	`History`	Deal and order history queries
Forex Helpers	`ForexSymbol`	Pip calc, volume from SL
Positions	`Positions`	Open position management
Multi-Process	`Bot.process_pool()`	Run bots in parallel processes
Sync API	`core.sync`, `lib.sync`	Synchronous mirrors

aiomql takes care of the infrastructure, the connection handling, the execution
loops, and the bookkeeping — so you can focus on what matters: your trading
strategy.

For the full API reference, see the documentation.

aiomql is MIT-licensed and maintained by Ichinga Samuel.

Support This Project

If you found this tutorial helpful, consider supporting the development of aiomql:

AIOMQL

Ichinga Samuel — Wed, 22 Jan 2025 14:18:16 +0000

Introduction

The aiomql package is an advanced algorithmic trading framework that enhances and extends the capabilities of the MetaTrader5 Python integration library (metatrader5). Its purpose is to simplify the process of building custom trading bots while offering a rich set of tools and abstractions tailored to algorithmic trading. The aiomql framework is designed with flexibility in mind, catering to a wide spectrum of users, from those looking for a lightweight asynchronous alternative to the MetaTrader5 Python integration to developers building complex, multi-strategy trading bots.

Requirements

This tutorial introduces version four of the aiomql framework, which boasts significant improvements in speed, efficiency, and design over its predecessors. A key highlight of this version is the inclusion of a powerful backtesting feature that allows users to test trading strategies on historical data before live deployment.
Although familiarity with previous versions of the aiomql framework may enhance your understanding, it is not a prerequisite. This tutorial is designed to be accessible even for beginners with no prior experience using the framework. However, to fully grasp and apply the concepts covered, a working knowledge of Python and a basic understanding of algorithmic trading are essential.
While this article serves primarily as an introduction to the framework rather than a step-by-step tutorial, it does include code snippets that require Python 3.11. If you experience compatibility issues with NumPy, you can resolve them by installing a supported version with the following command:
pip install numpy<v2.

pip install aiomql
pip uninstall numpy
pip install 'numpy<v2'

Organization and Structure of aiomql

The aiomql framework is structured into three main sub-packages (core, contrib, and lib) along with a top-level module, _utils.py, that provides utility functions used throughout the framework. All classes, functions, constants, and other components can be accessed directly from the top level for convenience.

The MetaTrader Class

As previously mentioned, the aiomql library serves as an asynchronous counterpart to the metatrader5 package. This functionality is enabled through the MetaTrader class, a fundamental component of the framework. The class replicates the features of the metatrader5 library, providing its functions, constants, and specialized types as methods and attributes.

Key Features

The functions from the metatrader5 package are accessible as asynchronous instance methods within the MetaTrader class, retaining their original names. This design ensures seamless integration for users familiar with the original library while leveraging the benefits of asynchronous programming.

The MetaTrader class, designed as an asynchronous context manager, simplifies the management of the MetaTrader terminal. Upon entering the context, it automatically initializes the terminal and performs login operations. When exiting, it ensures the proper cleanup of resources and disconnection, even in the event of errors. This structure offers a clean and efficient approach to lifecycle management, making it particularly suitable for asynchronous workflows.

The non-asynchronous versions of these functions remain accessible but are prefixed with an underscore (_), signifying that they can be treated as private methods.

The MetaBackTester

The MetaBackTester is a subclass of MetaTrader designed specifically for backtesting. It utilizes a BackTestEngine instance, which can be provided during initialization or retrieved from the configuration. When the config.mode is set to "backtest", this class automatically replaces MetaTrader in applications that depend on it for terminal connectivity, ensuring seamless integration of backtesting functionality.

Base and _Base

The Base and _Base classes are foundational components that underpin other classes in the framework, providing essential utilities such as data validation, serialization, and seamless access to either a MetaTrader or MetaBackTester instance, depending on whether the system is in live trading or backtesting mode. While these classes are rarely used directly, they ensure consistency and reliability across the system by serving as the backbone for more specialized functionalities.

Base

The Base class offers robust data handling capabilities, focusing on validation and serialization. During instantiation, only attributes explicitly annotated in the class body or inherited from parent classes can be assigned values, and these values must strictly conform to their defined types, ensuring structured and type-safe data management.

Important Attributes and Methods

exclude (set): A set of attribute names to exclude when accessing the attributes or generating a dictionary representation of the object.
include (set): A set of attribute names to include explicitly. This overrides the exclude set if both are provided.
dict: A property that returns all the attributes as a dictionary, applying the filters specified in the exclude and include sets.
set_attributes(**kwargs): A method to set attributes on the instance dynamically. It validates the inputs and ensures that they are of the correct type.
get_dict(exclude: set = None, include: set = None): A method to return the attributes of the instance as a dictionary, allowing the specification of exclude and include filters. The include parameter takes precedence over the exclude parameter if both are provided.

_Base

This class is a subclass of Base with additional attributes and functionality specifically designed for connecting to the terminal.

Important Attributes and Methods

config: Represents the configuration instance. This attribute holds all the necessary configuration settings required for the class to function.
mt5 (MetaTrader | MetaBackTester): Provides an instance of either MetaTrader or MetaBackTester, determined by the mode attribute of the config object. The type of instance depends on whether the system is operating in live trading mode (MetaTrader) or backtesting mode (MetaBackTester).

Constants

The MetaTrader5 library organizes its extensive set of constants into specialized enums, improving clarity and functionality for developers. These enums represent various trading actions, order types, timeframes, and more, streamlining their use by grouping related constants under intuitive categories. Each enum provides attributes and, where applicable, additional methods or properties, enabling functionality like conversions, opposites, or derived values. This organization reduces errors, improves code readability, and makes constants easier to manage, particularly in complex trading applications.
Enums such as TradeAction, OrderFilling, and TimeFrame encapsulate the constants as integer values while offering Pythonic string representations for better usability. Some enums, like TimeFrame, include advanced methods to convert seconds into predefined time intervals or access all possible values. By structuring these constants systematically, the MetaTrader5 library ensures a more efficient and developer-friendly experience, simplifying interaction with trading operations and platform data.

Models

The models module provides an organized set of data-handling classes built on top of the MetaTrader5 library’s structures. All classes inherit from the Base class, which adds functionalities like data validation, serialization, and filtering to streamline their use. These classes represent various trading-related entities, such as OrderSendResult, SymbolInfo, and TradeRequest, allowing developers to efficiently interact with MetaTrader5's trading environment.

Each class encapsulates specific attributes and properties related to its corresponding trading entity, ensuring robust and structured data management. For instance, SymbolInfo provides details about financial instruments, while TradeRequest enables the creation and submission of trade operations. This modular design enhances readability, simplifies complex trading workflows, and ensures data consistency and ease of use for developers leveraging MetaTrader5 in their applications.

TaskQueue

The TaskQueue class efficiently manages background tasks for a bot or backtester using an instance asyncio.PriorityQueue for concurrent execution. It operates continuously in the background, allowing seamless integration with other components, such as the Trader class, which uses it to record trade data post-execution. Tasks are added to the queue via the add method, but they must first be encapsulated in a QueueItem, which holds task metadata such as arguments, priority, and completion requirements.

With configurable worker count, timeout settings, and task prioritization, the TaskQueue ensures robust task management and error handling. It supports finite or infinite execution modes and can gracefully clean up remaining tasks based on the priority before termination. This design enhances the workflow by offloading and managing background operations asynchronously, ensuring smooth and reliable functionality for complex trading or testing environments.

res = Result(result=result, parameters=params, name=name)
self.config.task_queue.add(item=QueueItem(res.save), must_complete=True)

Account

The Account class is a singleton designed to manage broker account details, ensuring that only one instance exists during the application’s lifecycle. It inherits from both Base and **_AccountInfo**, offering a structured and user-friendly interface for accessing account-specific information. This architecture ensures consistency and prevents duplicate instances, centralizing account management within the application.

As an AsyncContextManager, the Account class simplifies resource management by automating initialization and cleanup processes. When entering its context, it initializes the MetaTrader terminal and logs into the specified account. Upon exiting, it ensures proper resource shutdown and cleanup. This streamlined approach enhances the reliability of resource handling, making account management more intuitive and reducing the likelihood of errors during trading operations.

Important Methods and Attributes

connected (bool): Indicates whether the login was successful and the connection to the terminal is active. Returns True if the account is connected.
refresh(): Updates the account instance by retrieving the latest account details from the terminal, ensuring that the account data remains current.

Risk and Asset Management

The RAM class is responsible for managing risk assessment and management during trading activities. With attributes like risk_to_reward, fixed_amount, min_amount, max_amount, and risk, it allows traders to define and control their risk exposure effectively. These attributes provide flexibility in setting parameters for risk per trade, minimum and maximum risk amounts, and risk-to-reward ratios.

The class includes methods such as get_amount, which calculates the amount to risk per trade based on available margin and risk percentage, and check_losing_positions and check_open_positions, which ensure that the number of losing or open positions stays within predefined limits. By integrating these features, the RAM class provides a comprehensive approach to risk management, enhancing decision-making and promoting safer trading practices.

Important Attributes and Methods

risk (float): The percentage of capital to risk per trade, expressed as a whole number (e.g., 1 for 1%). Defaults to 1.
risk_to_reward (float): The risk-to-reward ratio, indicating the relationship between potential risk and reward. Defaults to 2.
fixed_amount (float): A fixed amount to risk per trade, overriding percentage-based calculations if set.
get_amount(): Calculates and returns the amount to risk per trade based on the configured attributes, such as risk, fixed_amount, min_amount, and max_amount.

The RAM class is best used in the a Trader class, where it can be used just before the trade is placed.

Candle and Candles

The Candle and Candles classes are custom tools for managing price bars retrieved from the terminal. The Candle class encapsulates data for a single price bar, ensuring mandatory attributes like Open, High, Low, and Close (OHLC) are present in every instance. It supports Python protocols, including hashing, iteration, and comparison, while providing methods like keys() and values() for attribute management. Additionally, it dynamically adds attributes passed during instantiation, allowing flexible customization.

The Candles class acts as a container for multiple Candle objects organized in chronological order. It utilizes a pandas DataFrame to store and manage its data, offering seamless integration with tools like pandas-ta for advanced technical analysis. By supporting various Python protocols, such as slicing and iteration, and extending functionality with specialized properties like timeframe, this class serves as a robust foundation for developing trading strategies. Its versatility ensures frequent utilization in complex analytical workflows.

Attributes and Methods of the Candle Class

time (int): The start time of the candle's period.
open (float): The opening price of the candle.
high (float): The highest price reached during the candle's period.
low (float): The lowest price reached during the candle's period.
close (float): The closing price of the candle.
tick_volume (float): The tick volume during the candle's period.
real_volume (float): The actual traded volume during the candle's period.
spread (float): The spread during the candle's period.
Index (int): A custom attribute indicating the position of the candle in a sequence.
set_attributes(**kwargs): Dynamically sets attributes of the candle instance from the provided keyword arguments.
is_bullish(): Returns True if the candle is bullish (closing price is greater than or equal to opening price), otherwise False.
is_bearish(): Returns True if the candle is bearish (closing price is less than opening price), otherwise False.
dict(exclude: set = None, include: set = None): Returns a dictionary of the candle's attributes, optionally filtering attributes using exclude or include sets.

Attributes and Methods of the Candles Class

Index (Series[int]): A pandas Series of the indexes of all candles in the object.
time (Series[int]): A pandas Series of the time of all candles in the object.
open (Series[float]): A pandas Series of the opening prices of all candles in the object.
high (Series[float]):A pandas Series of the highest prices of all candles in the object.
low (Series[float]): A pandas Series of the lowest prices of all candles in the object.
close (Series[float]): A pandas Series of the closing prices of all candles in the object.
tick_volume (Series[float]): A pandas Series of the tick volumes of all candles in the object.
real_volume (Series[float]): A pandas Series of the actual traded volumes of all candles in the object.
spread (Series[float]): A pandas Series of the spreads of all candles in the object.
Candle (Type[Candle]): The class used for representing individual candles within the object.
timeframe (TimeFrame): The timeframe of the candles, calculated from their timestamps.
data (DataFrame): The pandas DataFrame containing the underlying data of all candles in the object.
rename(inplace=True, **kwargs): Renames the columns of the underlying DataFrame.
ta: Provides access to the pandas-ta library for performing technical analysis directly on the candles, via the data attribute.
ta_lib: Provides access to the ta library for additional technical analysis, use this for functions that requires you to pass in the Series or the DataFrame object as an argument.
columns: Returns the column names of the underlying DataFrame.

Tick and Ticks

The Ticks and Tick classes are designed to manage tick data from the trading terminal, similar to the Candle classes. The Tick class represents an individual tick with attributes like bid, ask, last price, and volume, ensuring each instance encapsulates the necessary data for a single tick event. It supports dynamic attribute management and provides dictionary-like access, making it adaptable and easy to manipulate in different contexts.

The Ticks class acts as a container for multiple Tick objects, storing the data in a pandas DataFrame for efficient manipulation and analysis. It supports iteration, slicing, and various data operations, enabling seamless integration with tools like pandas-ta for technical analysis. This class is pivotal for handling large volumes of tick data in trading systems, providing a robust structure for real-time or historical data analysis.

Symbols

The _Symbol _ class provides a robust structure for encapsulating the data of financial instruments, supporting computations and operations required before initiating trades. As a subclass of _Base and SymbolInfo, it integrates extensive attributes and methods to handle financial instruments efficiently. This class can be tailored for various instruments from different brokers, ensuring adaptability across trading platforms.

With utility methods for accessing current tick data, managing market depth, and performing currency conversions, the Symbol class simplifies complex trading tasks. It offers functionality to initialize symbols, validate trading volumes, and retrieve historical rates or ticks, making it an essential component for developing trading strategies. Its design ensures that developers can extend and customize its behavior to suit specific trading requirements.

Important Attributes and Methods.

The Symbol class is a feature rich class. For the purpose of this introductory article I will only touch on some few vital ones, that you are most likely to use. tick and account are the only attributes of the Symbol class that are not the same as those defined in the SymbolInfo parent class.

tick (Tick): Represents the current price tick of the financial instrument, providing real-time market data.
account (Account): An instance of the current trading account associated with the symbol.
__init__(*, name: str, **kwargs): Initializes a symbol instance. The name attribute is mandatory and must match the name of the symbol as specified by the broker in the terminal.
initialize(): Populates the symbol instance with data from the terminal. It calls the info_tick method to retrieve the latest price tick and the info method to pull detailed symbol data. If successful, the select attribute is set to True, and all attributes are populated with server data.
convert_currency(*, amount: float, from_currency: str, to_currency: str): Converts a specified amount from one currency to another.
amount_in_quote_currency(*, amount: float): Converts an amount from the account currency to the quote currency if they are different. This method is especially useful for performing risk management calculations.
info_tick: Retrieves the current price tick of the financial instrument.
symbol_select(enable: bool = True): Adds or removes the symbol from the MarketWatch window.
check_volume(volume: float): Validates if a specified trading volume is within the allowed limits and adjusts it if necessary.
round_off_volume(volume: float, round_down: bool = False): Rounds the volume to the nearest valid step.
compute_volume: Computes the appropriate trading volume for a trade.
copy_rates_from_pos(timeframe, start_position=0, count=500): Fetches bars starting from a specific index.
copy_rates_from(timeframe, date_from, count=500): Retrieves historical rates (bars) starting from a specified date.
copy_ticks_from(date_from, count=100, flags=CopyTicks.ALL): Fetches tick data starting from a specified date.

The Symbol class is a versatile and feature-rich tool designed to manage financial instruments, providing essential methods for retrieving and converting data. While this introduction highlights key functionalities like initialization, currency conversion, and retrieving the latest tick data, many of its other features will be explored in future discussions. These include its integration into algorithmic trading systems, showcasing its adaptability for various use cases.

A notable contribution is the ForexSymbol class, a specialized extension of the Symbol class tailored for forex trading. This subclass is designed to handle the unique requirements of trading currency pairs, further demonstrating the flexibility and customization potential of the Symbol class for different trading scenarios.

Order

The Order class streamlines the management of trade orders by grouping related attributes and methods, making it easier to check, validate, and send orders. As a subclass of _Base and TradeRequest, it inherits robust functionality while offering additional convenience. With sensible defaults for attributes like action, type_time, and type_filling, it minimizes repetitive code during instantiation, ensuring efficiency and clarity in trading operations.

This class simplifies core tasks such as retrieving pending orders, checking fund sufficiency, and calculating margins, profits, and losses. The integration of methods like send() and check() ensures a seamless workflow for initiating and validating trade operations, while utilities like calc_margin() and calc_profit() assist in pre-trade analysis. Its design makes it an essential tool for implementing algorithmic trading strategies efficiently.

Important Attributes and Methods of the Order Class

__init__: Initializes an order instance using keyword arguments that must be valid TradeRequest attributes. Defaults are set for action as DEAL, type_time as DAY, and type_filling as FOK, though they can be customized during instantiation.
check(**kwargs): Validates the order before placing it. Any keyword arguments provided will update the request object.
send: Sends the order to the terminal for execution.
calc_margin: Calculates the margin required for placing the trade.
calc_profit: Calculates the potential profit for the trade.
calc_loss: Calculates the potential loss for the trade.
request: This property returns the trade request object as a dictionary.

Trader

The Trader class serves as a utility-rich abstract base class for managing trade placements. It provides foundational methods for creating and managing various order types while handling critical processes like validation, sending, and recording of trades. This class requires implementation of the place_trade method in its subclasses, ensuring flexibility to suit specific trading strategies.

Key features include methods for setting stop-loss and take-profit levels based on pips or points, creating orders with or without stop levels, and calculating appropriate volumes for trades. The class integrates with a properly initialized Symbol instance and an optional RAM instance for risk assessment, enabling seamless trade management. It also supports trade result recording, facilitating tracking and analysis of executed trades.

Important Attributes and Methods of the Trader Class

modify_order(**kwargs): Modifies the order attributes using the provided keyword arguments.
modify_ram(**kwargs): Updates the RAM (Risk Assessment and Management) instance attributes using the provided keyword arguments.
check_order: Validates the order before placing it, ensuring it meets the necessary criteria.
send_order: Sends the order to the broker for execution.
record_trade(*, result: OrderSendResult, parameters: dict = None, name: str = ""): Records trade details in a CSV or JSON file, delegating the task to the config.task_queue instance. Includes trade results and strategy parameters if provided.

The contrib package comes with two simple traders, ScalpTrader and SimpleTrader, one of which the ScalpTrader is shown below.

Session and Sessions

The Session and Sessions classes provide a robust framework for managing and enforcing trading times. A Session represents a defined time period in UTC with a start and end time, which can be specified as integers or datetime.time objects. These sessions can trigger predefined actions, such as closing all trades or only profitable/losing positions, or custom actions specified by the user. This allows strategies to maintain precise control over trading activities during specific periods.

The Sessions class groups multiple Session instances into a sorted collection, making it easy to manage overlapping or sequential trading periods. Acting as an asynchronous context manager, it continuously monitors the current time to determine the active session. If no session is active, the Sessions instance suspends trading operations until the next scheduled session begins, ensuring adherence to designated trading windows.

By integrating these classes, trading strategies can incorporate time-based rules with ease, enhancing their precision and reliability. This functionality is particularly useful in scenarios requiring strict adherence to trading hours, such as forex or stock market trading, or in automated systems where operations need to align with predefined time intervals.

Important Attributes and Methods of the Session Class

start (datetime.time): The start time of the session in UTC.
end (datetime.time): The end time of the session in UTC.
on_start (str): Specifies the action to take when the session starts, such as "close_all", "close_win", "close_loss", or a custom action.
on_end (str): Specifies the action to take when the session ends, similar to on_start.
custom_start (Callable): An optional custom function to be executed when the session starts.
custom_end (Callable): An optional custom function to be executed when the session ends.
name (str): A name for the session, defaulting to a combination of the start and end times if not provided.
in_session: Checks if the current time is within the session.
begin: Executes the action specified by on_start or custom_start when the session begins.
close: Executes the action specified by on_end or custom_end when the session ends.
duration: Returns the duration of the session as a Duration object with hours, minutes, and seconds.
close_all: Closes all open positions when called.
close_win: Closes all winning positions when called.
close_loss: Closes all losing positions when called.
action(action: str): Executes the specified action, such as closing positions or triggering a custom function.
until: Calculates the time in seconds until the session starts from the current time.

Important Attributes and Methods of the Sessions Class

sessions (list[Session]): A list of Session objects, sorted by their start times.
current_session (Session | None): The currently active session, if any.
find(moment: datetime.time = None): Finds and returns the session that includes the specified time. If no time is provided, the current time is used.
find_next(moment: datetime.time = None): Finds and returns the next session after the specified time. Defaults to the current time if no time is provided.
check: Monitors the current session. If no session is active, it waits until the next session begins.
config: The configuration instance associated with the sessions, determining the mode (live or backtesting).

Strategy

The Strategy class is the foundational framework for developing trading strategies that integrate seamlessly with both the Bot and the Backtester. As an abstract base class, it comes equipped with numerous features but requires the implementation of the trade method in derived classes. This method serves as the core trading logic for the strategy. The Strategy class acts as an asynchronous context manager and uses the run_strategy method to execute the strategy, invoking either the live_strategy or backtest_strategy method based on the operational mode.

With attributes like symbol, sessions, and parameters, the class ensures that strategies can be customized and tailored to specific financial instruments and trading sessions. The integration of cooperative multitasking methods, such as sleep and delay, ensures that the strategy remains efficient and synchronized with market updates, whether in live or backtesting environments. This makes the Strategy class a robust and flexible tool for building sophisticated trading systems.

Attributes and Methods

name (str): The name of the strategy. Defaults to the class name if not explicitly provided.
symbol (Symbol): The financial instrument associated with the strategy.
parameters (dict): A dictionary of parameters specific to the strategy.
sessions (Sessions): The trading sessions during which the strategy is active.
mt5 (MetaTrader | MetaBackTester): The MetaTrader or MetaBackTester instance based on the mode (live or backtesting).
config: Configuration settings for the strategy.
running (bool): Indicates whether the strategy is currently running.
backtest_controller (BackTestController): A controller for managing backtesting operations.
current_session (Session): The currently active trading session.
__init__(symbol: Symbol, params: dict = None, sessions: Sessions = None, name: str = ""): Initializes the strategy with the given symbol, parameters, and sessions.
run_strategy: Runs the strategy by invoking either the live or backtesting method based on the mode.
live_strategy: Executes the strategy in live trading mode.
backtest_strategy: Executes the strategy in backtesting mode.
trade: Abstract method to be implemented by subclasses for placing trades.
test: Calls the trade method during backtesting if not implemented in the child class.
live_sleep(secs: float): Ensures synchronization with the terminal by computing precise sleep durations in live mode.
backtest_sleep(secs: float): Manages sleep durations during backtesting to align with the terminal's cursor.
sleep(secs: float): General sleep method that delegates to live_sleep or backtest_sleep based on the mode.
delay(secs: float): Introduces a delay for a specified number of seconds. Adjusts for live or backtest mode.

Position

The Position class is a utility class designed to manage and interact with open positions in a trading account. It allows filtering positions by attributes like ticket, symbol, or symbol group, providing flexible and efficient handling of active trades. Additionally, it includes methods for closing positions, either individually or in bulk, with support for executing opposite trades to close open positions.

Methods and Attributes

mt5 (MetaTrader | MetaBackTester): The MetaTrader or MetaBackTester instance used for managing positions.
positions (tuple[TradePosition, ...]):A tuple of all currently open positions.
total_positions (int): The total number of open positions.
get_positions(symbol: str = None, ticket: int = None, group: str = None): Retrieves open positions, with optional filtering by symbol, ticket, or symbol group.
get_position_by_ticket(ticket: int): Retrieves a specific open position using its ticket number.
get_positions_by_symbol(symbol: str): Retrieves all open positions for a specific financial instrument.
close(ticket: int, symbol: str, price: float, volume: float, order_type: OrderType): Closes an open position using the provided ticket and parameters.
close_position_by_ticket(ticket: int): Closes a specific position identified by its ticket number.
close_position(position: TradePosition): Closes a position using a TradePosition object.
close_all(): Closes all open positions for the trading account.
get_total_positions(): Returns the total number of currently open positions.

History

The History class is a utility for managing and retrieving completed trade deals and orders from an account’s trading history. It allows filtering and accessing historical data by parameters such as tickets, positions, or symbols, providing a detailed view of past trading activity. This class is particularly useful for analyzing trading performance or implementing post-trade analysis.

Methods and Attributes of the History Class

mt5 (MetaTrader | MetaBackTester): The MetaTrader or MetaBackTester instance used for retrieving historical data.
config (Config): Configuration instance for managing operational settings.
deals (tuple[TradeDeal, ...]): A tuple containing the trade deals retrieved from the account's history.
orders (tuple[TradeOrder, ...]): A tuple containing the trade orders retrieved from the account's history.
total_deals (int): The total number of trade deals retrieved.
total_orders (int): The total number of trade orders retrieved.
group (str): A filter for selecting history by symbol group.
initialize(): Retrieves and populates trade deals and orders for the specified date range and group.
get_deals: Fetches trade deals based on the parameters set during initialization.
get_deals_by_ticket(ticket: int): Filters and retrieves trade deals associated with a specific order ticket.
get_deals_by_position(position: int): Filters and retrieves trade deals associated with a specific position.
get_orders: Fetches trade orders based on the parameters set during initialization.
get_orders_by_ticket(ticket: int): Filters and retrieves trade orders associated with a specific order ticket.
get_orders_by_position(position: int): Filters and retrieves trade orders associated with a specific position.

Results

The Result class is a utility for recording trade outcomes and associated strategy parameters for tracking and analysis. It supports saving trade data in either CSV or JSON formats, based on the configured trade_record_mode. This functionality is critical for maintaining a detailed history of trades, enabling performance evaluation and strategy refinement.

Methods and Attributes of the Result Class

config (Config): The configuration object managing settings like file directories and trade_record_mode.
parameters (dict): Additional parameters associated with the trade that need to be recorded.
result (OrderSendResult): The result of the executed trade, containing detailed trade information.
name (str): The name of the result file. Defaults to "Trades" if not explicitly provided.
lock (Lock): A threading lock to ensure thread-safe operations when saving results.
get_data: Combines trade result details and additional parameters into a single dictionary for saving.
save(trade_record_mode: Literal['csv', 'json'] = None): Saves the trade record in the specified format (CSV or JSON). Defaults to the mode configured in trade_record_mode.
to_csv: Saves the trade results and associated parameters to a CSV file.
to_json: Saves the trade results and associated parameters to a JSON file.
serialize(value): Converts the trade records and parameters to a string format for saving in JSON files.

The Result class ensures that trade outcomes are properly documented, enabling traders to analyze their strategies and improve future performance.

Trade Records

The TradeRecords class is a utility for managing and updating trade records stored in CSV or JSON files. It ensures that trade outcomes, including profits and win statuses, are updated accurately based on the actual trading history retrieved from the MetaTrader terminal. This functionality supports comprehensive trade tracking and analysis.

Methods and Attributes of the TradeRecords Class

config (Config): Configuration instance for managing settings like record directories.
mt5 (MetaTrader | MetaBackTester): The MetaTrader or MetaBackTester instance used to retrieve trade data.
records_dir (Path | str): The directory where trade record files (CSV or JSON) are stored.
positions (list[TradePosition] | None): A list of currently open positions, retrieved dynamically.
get_csv_records(): Retrieves all CSV trade record files from the records directory.
get_json_records(): Retrieves all JSON trade record files from the records directory.
read_update_csv(file: Path): Reads and updates a specific CSV trade record file.
read_update_json(file: Path): Reads and updates a specific JSON trade record file.
update_row(row: dict): Updates a single row of trade data, calculating actual profit, win status, and closure status.
update_rows(rows: list[dict]): Updates multiple rows of trade data with actual outcomes.
update_csv_records(): Updates all CSV trade records in the records directory.
update_json_records(): Updates all JSON trade records in the records directory.
update_csv_record(file: Path | str): Updates a single specified CSV trade record file.
update_json_record(file: Path | str): Updates a single specified JSON trade record file. This class is essential for maintaining accurate and up-to-date trade records, facilitating robust performance analysis and strategy optimization.

Executor

The Executor class is a critical utility that powers both the Bot and BackTester, providing the capability to manage multiple strategies and tasks concurrently. It encapsulates a ThreadPoolExecutor to execute tasks efficiently in parallel, enabling seamless integration of strategies, coroutines, and functions within the trading framework.

Methods and Attributes of the Executor Class

executor (ThreadPoolExecutor): The thread pool executor that manages concurrent task execution.
strategy_runners (list[Strategy]): A list of strategy instances to be executed.
coroutines (list[Coroutine]): A list of coroutine tasks to run.
coroutine_threads (list[Coroutine]): Coroutines that need to run on separate threads.
functions (dict[Callable, dict]): A dictionary of functions and their respective arguments to be executed.
tasks (list[asyncio.Task]): A list of asyncio tasks currently managed by the Executor.
config (Config): Configuration instance for managing executor settings.
timeout: Timeout setting for the Executor, used for testing purposes.

Key Methods

add_function(function: Callable, kwargs: dict = None): Adds a function to the executor with optional arguments.
add_coroutine(coroutine: Coroutine, kwargs: dict = None, on_separate_thread: bool = False): Adds a coroutine to the executor, with an option to run it on a separate thread.
add_strategies(strategies: tuple[Strategy]): Adds multiple strategies to the executor.
add_strategy(strategy: Strategy): Adds a single strategy to the executor.
run_strategy(strategy: Strategy): Runs a single strategy using the asyncio event loop.
run_coroutine_tasks(): Runs all coroutines managed by the executor.
run_function(function: Callable, kwargs: dict): Executes a single function with provided arguments.
exit(): Gracefully shuts down the executor and cancels all running tasks.
execute(workers: int = 5): Executes all strategies, coroutines, and functions using the thread pool executor, with a configurable number of workers.

The Executor class ensures efficient execution of concurrent tasks, making it a robust solution for managing complex trading operations.

Bot

The Bot class is designed to run trading strategies in live mode, offering a structured and scalable framework for managing multiple strategies and symbols simultaneously. It connects with the *MetaTrader * terminal and uses the Executor class to efficiently handle concurrent tasks, such as executing strategies, managing coroutines, and running custom functions.

Methods and Attributes of the Bot Class Attributes

config (Config): Configuration object for managing bot settings.
executor (Executor): Instance of the Executor class for concurrent task execution.
mt (MetaTrader): The MetaTrader instance for interacting with the trading terminal.
strategies (list[Strategy]): A list of trading strategies to be executed by the bot.
__init__(): Initializes the bot with a configuration, executor, and MetaTrader instance.
add_function(function: Callable, **kwargs): Adds a custom function to the executor for execution.
add_coroutine(coroutine: Coroutine, on_separate_thread: bool = False, **kwargs): Adds a coroutine to the executor, optionally running it on a separate thread.
add_strategy(strategy: Strategy): Adds a single strategy to the bot's list of strategies.
add_strategies(strategies: Iterable[Strategy]): Adds multiple strategies to the bot at once.
add_strategy_all(strategy: Type[Strategy], params: dict, symbols: list[Symbol], **kwargs): Runs a single strategy on multiple symbols with the same parameters.
initialize(): Asynchronously prepares the bot by signing in to the trading account, initializing symbols, and adding tasks to the executor.
initialize_sync(): Synchronously prepares the bot, similar to initialize().
start(): Starts the bot by initializing it and invoking the executor.
execute(): Executes the bot using the executor's thread pool.
init_strategy(strategy: Strategy): Initializes a single strategy asynchronously and adds it to the executor.
init_strategies(): Asynchronously initializes all strategies added to the bot.
init_strategy_sync(strategy: Strategy): Synchronously initializes a single strategy and adds it to the executor.
init_strategies_sync(): Synchronously initializes all strategies added to the bot.

The Bot class offers robust functionality for managing live trading strategies, ensuring efficient execution and streamlined integration with trading systems.

BackTester

The BackTester class provides a seamless way to backtest trading strategies, enabling developers to evaluate performance over historical data before deploying strategies live. Like the Bot class, the BackTester uses an Executor instance to manage multiple strategies concurrently. It integrates with a BackTestEngine to handle backtesting logic and operations. During backtesting, the mode attribute must be set to "backtest" to ensure proper functionality.

Methods and Attributes of the BackTester Class

config (Config): Configuration object for managing backtester settings.
executor (Executor): Instance of the Executor class for managing concurrent strategy execution.
mt (MetaBackTester): MetaBackTester instance for interacting with the simulated trading environment.
backtest_engine (BackTestEngine): The engine responsible for managing backtesting operations.
backtest_controller (BackTestController): Manages synchronization and controls the backtesting process.
strategies (list[Strategy]): A list of trading strategies to be backtested.
__init__(backtest_engine: BackTestEngine): Initializes the BackTester with a BackTestEngine instance.
initialize_sync(): Synchronously prepares the backtester, logging in and initializing strategies.
initialize(): Asynchronously prepares the backtester, logging in and initializing strategies.
execute(): Executes the backtester by initializing and running the executor.
start(): Asynchronously initializes and starts the backtester.
add_strategy(strategy: Strategy): Adds a single strategy to the backtester.
add_strategies(strategies: Iterable[Strategy]): Adds multiple strategies to the backtester at once.
add_strategy_all(strategy: Type[Strategy], params: dict, symbols: list[Symbol], **kwargs): Runs a single strategy on multiple symbols using the same parameters.
init_strategy(strategy: Strategy): Asynchronously initializes a single strategy and adds it to the executor.
init_strategy_sync(strategy: Strategy): Synchronously initializes a single strategy and adds it to the executor.
init_strategies(): Asynchronously initializes all strategies for the backtesting session.
init_strategies_sync(): Synchronously initializes all strategies for the backtesting session.

The BackTester class, combined with its integration with the BackTestEngine and Executor, provides a robust framework for testing strategies, optimizing performance, and ensuring readiness for live trading environments.

Utils

The _utils module provides a collection of utility functions and decorators that encapsulate commonly needed logic for various parts of the framework. These utilities enhance code reusability, streamline repetitive tasks, and improve error handling and performance optimization.

Functions and Decorators in the _utils Module

backtest_sleep(secs: float): Simulates an asynchronous sleep function for backtesting, synchronizing actions with the backtest engine's cursor.
sleep(secs: float): Sleep until the interval specified. This is just like the sleep method in the Strategy class.
dict_to_string(data: dict, multi: bool = False): Converts a dictionary to a string format for logging, optionally formatting key-value pairs on separate lines.
backoff_decorator(func=None, max_retries: int = 2, retries: int = 0, error=""): Retries a function or coroutine a specified number of times before raising an error. Useful for handling transient issues.
error_handler(func=None, msg: str = "", exe=Exception, response=None, log_error_msg: bool = True): A decorator for catching and logging exceptions in asynchronous functions, with options to return a fallback response.
error_handler_sync(func=None, msg: str = "", exe=Exception, response=None, log_error_msg: bool = True): A synchronous version of the error_handler for standard functions.
round_down(value: int | float, base: int): Rounds a number down to the nearest multiple of the specified base.
round_up(value: int | float, base: int): Rounds a number up to the nearest multiple of the specified base.
round_off(value: float, step: float, round_down: bool = False):Rounds a number to the nearest step, with an option to specify rounding direction.
async_cache(fun): Caches the result of an asynchronous function to avoid redundant computations, improving performance.

These tools simplify implementation details and support developers in writing cleaner, more efficient, and maintainable code across the framework.

Conclusion

This is an introductory article that provides an overview of the powerful capabilities and features of this library, highlighting the key classes and functions essential for effectively leveraging it in trading systems. In the next tutorial, we’ll dive deeper into assembling these components to build a sophisticated and efficient trading system, guiding you step-by-step through the process.

If you found this article and the library helpful you can support my work by buying me a coffee. Your contributions go a long way in keeping this content flowing and inspiring more innovative ideas. Let’s learn and grow together!. Check out the repo here.

Create a Product Rating System with MongoDB and Node.js

Ichinga Samuel — Thu, 13 Jul 2023 20:34:02 +0000

Introduction

In this tutorial, you will learn how to make good use of Mongoose schema mixed type, getters and, setters to manipulate data in your MongoDB database

Most product rating systems such as that of amazon make use of the weighted average system. The weighted average is calculated in almost the same way as the ‘normal’ simple average except that each unit in the summation has a multiplier which is called the weight. For example in a five-star rating system. One star could have a weight of 1, two stars will have a weight of 2, and so on.

Example.

Let say a product has the following star reviews.
One Star — — 8
Two Star — — 10
Three Stars — — 7
Four Stars — — 5
Five Stars — — 3
The simple average will be
const SA = (8+10+7+5+3) / 5 console.log(Math.round(SA)) // 2
The weighted average system gives a better result as it gives a good impression of what consumers think of this product.

How do you implement this?

Implementing this on the backend means that you need a place to store not just the ratings of each product but also the number each start receives. There are different approaches to solving this problem. Personally, I prefer a combination of Mongoose schema mixed types with setters and getters.

Requirements

For this project will need only Mongoose as our MongoDB driver and a local Mongo shell and optionally Compass for nice visualization.
To start with let’s create a simple Node project and install Mongoose.
npm install -s mongoose
Create a file model.js and start the local Mongo client

const mongoose = require('mongoose');

const connectDB = async () => {
     try{
         const conn = await mongoose.connect('mongodb://localhost:27017/myapp', {useNewUrlParser: true, useFindAndModify: false})
         console.log(`MongoDb connected: ${conn.connection.host}`)
         return conn
     }
     catch (e) {
         console.error(e);
         process.exit(1);

     }
 };

Next, let’s create a basic mongoose schema for the product collection. It will have just two paths name a string path to hold the name of the product and ratings a mixed path object to store the ratings of the product.

const ProductSchema = new mongoose.Schema({
    name: String,
    ratings:{
        type: mongoose.Mixed, 
 // A mixed type object to handle ratings. Each star level is represented in the ratings object
        1: Number, //  the key is the weight of that star level
        2: Number,
        3: Number,
        4: Number,
        5: Number,
    default: {1:1, 2:1, 3:1, 4:1, 5:1}}
    })

Since we are using getters lets make sure to include the options below in the schema object so that the getters can be used when obtaining JSON or JavaScript Object.
{toObject:{getters: true, }, toJSON:{getters: true}}

The Getter Function

Next, we going to write a getter function for obtaining the rating of a product from the rating path. When we call a getter function on a path it accepts a single argument that represents the path. In this case, it is a plain JavaScript object that contains our star reviews. This simplifies the getter function. As shown below.

The Setter Function

This function will handle the setting of values to the rating path. It will enable us to have a simple interface for updating the ratings of a product. Let say a user gives the product a rating of three or we want to replace the entire rating object with a new object. We want to be able to update the rating of a product with simple one-liners such as this.

product.ratings = 3
product.ratings = {1:1, 2:1, 3:1, 4:1, 5:1}
Product.findByIdAndUpdate(id, {$inc:{'ratings.3': 1}})
Product.findByIdAndUpdate('61084b72b346c52e8482ed3b', {ratings: {1:3, 2:1, 3:1, 4:1, 5:1}}, {new: true})

The first two snippets will update the number of 3-star ratings by 1. While the other two will assign a new object to the ratings path.

set: function(r){
    if (!(this instanceof mongoose.Document)){
        // only call setter when updating the whole path with an object
        if(r instanceof Object) return r
        else{throw new Error('')}
    }else{
        // get the actual ratings object without using the getter which returns  an integer value
        // r is the ratings which is an integer value that represent the star level from 1 to 5
        if(r instanceof Object){
            return r    // handle setting default when creating object
        }
        this.get('ratings', null, {getters: false})[r] = 1 + parseInt(this.get('ratings', null, {getters: false})[r])
        return this.get('ratings', null, {getters: false})} // return the updated ratings object
},

The setter function is a bit complicated as we need to obtain the rating object for that document without using the getter which returns an integer value. The argument to the setter function is either the star level we want to update by one or a JavaScript object containing the star levels as keys just as specified in the schema. Mongoose setters get called when running update operations as well as when assigning directly to a path. The difference is that when running update operations “this” in the function refers to the query object and not an instance of the mongoose document we are updating this makes it difficult to carry out our custom update operation for a sub-path since we are updating a specific sub-path and not the whole path. Therefore, we will throw an error if someone tries to update the whole path with an integer value using any of the Mongoose model update methods.

The remaining logic in the setter function is simple, we will simply obtain the product rating object without using getters then use the argument to the setter function to update the specific path after which we will return the updated rating object.

Validation

It will be nice to add a validator to prevent increasing the value of a sub-path by more than one at a time but, Mongoose validators do not run when using the increment operator “$inc” so, it will be up to us to validate data before passing it to the database. Our validator function will simply prevent the addition of an extra star level outside that specified in our Schema.

validate:{
    validator: function(i){
        let b = [1, 2, 3, 4, 5] // valid star levels
        let v = Object.keys(i).sort()
        return b.every((x, j) => (v.length === b.length) && x === parseInt(v[j]))
    },
    message: "Invalid Star Level"
},

Testing
Let’s create a product and console log it with and without getters to see what it looks like. Here is what our code looks like. We can then copy the product id to test our update methods and validators.

const create = async () => {
    let prod = await product.create({name: "Product One"})
    // display the newly created object with and without getters
    console.log(prod)
    console.log(prod.get( 'ratings', null, {getters: false}))
}
create()

// result without the getter
{
    ratings: 3,
        _id: 61069af7547cd8335409a926,
    name: 'Product One',
    __v: 0,
    id: '61069af7547cd8335409a926'
}

// the ratings object
{ '1': 1, '2': 1, '3': 1, '4': 1, '5': 1 }

Having seen our getters at work. We are going to try and update the ratings of our product in a few different ways to test our setters.
Lets’s write a code to give our product a five-star rating. As you can see by simply assigning the value five to the rating object we have updated the number of five-star reviews from 1 to 2. The average rating is still three because of the weighted average computation we use in obtaining the rating.

const test1 = async () => {
    // increment a particular star level.
    // by assigning directly to the ratings object
    let prod = await product.findById('61084b72b346c52e8482ed3b')
    prod.ratings = 5
    prod.markModified('ratings')  // Add markModified because ratings is a mixed object type
    prod.save()
    console.log(prod.get( 'ratings', null, {getters: false}))
    console.log(prod)
}
test1()

{ '1': 1, '2': 1, '3': 1, '4': 1, '5': 2 }

{
    ratings: 3,
        _id: 61084b72b346c52e8482ed3b,
    name: 'Product One',
    __v: 0,
    id: '61084b72b346c52e8482ed3b'
}

Conclusion

As Always in computer science there are many ways to solve a problem some more intuitive than others. However, finding a solution that is adaptable, maintainable and, involves a minimal amount of code is always preferable. The complete code can be found at https://github.com/Ichinga-Samuel/Rating-System.git