简介
aiomql 包是一个先进的算法交易框架，它增强并扩展了 MetaTrader5 Python 集成库 (metatrader5) 的功能。其目的是简化构建自定义交易机器人的过程，同时提供一套丰富的工具和抽象，专门用于算法交易。 aiomql 框架的设计理念是灵活性和适应性，它可以满足各种用户的需求，从寻求 MetaTrader5 Python 集成的轻量级异步替代方案的用户，到构建复杂的多策略交易机器人的开发人员。
需求
本教程介绍了 aiomql 框架的第四版，它在速度、效率和设计方面比之前的版本有了显着的改进。此版本的一个重要亮点是包含了一个强大的回测功能，允许用户在实时部署之前使用历史数据测试交易策略。
虽然熟悉 aiomql 框架的早期版本可以增强您的理解，但这并不是先决条件。本教程旨在即使是从未使用过该框架的初学者也能轻松理解。但是，要充分理解和应用所涵盖的概念，需要具备 Python 的工作知识和对算法交易的基本理解。
虽然本文主要作为框架的介绍而不是逐步教程，但它确实包含需要 Python 3.11 的代码片段。如果您在 NumPy 中遇到兼容性问题，您可以使用以下命令安装受支持的版本来解决这些问题：
<code class="language-bash">pip install aiomql pip uninstall numpy pip install 'numpy<v2></v2></code>
aiomql 框架分为三个主要子包（core、contrib 和 lib），以及一个顶级模块 utils.py，该模块提供整个框架中使用的实用程序函数。为了方便起见，所有类、函数、常量和其他组件都可以直接从顶级访问。
如前所述，aiomql 库是 metatrader5 包的异步对应版本。此功能是通过 MetaTrader 类实现的，它是框架的一个基本组件。该类复制了 metatrader5 库的功能，将其函数、常量和专用类型作为方法和属性提供。
metatrader5 包中的函数作为 MetaTrader 类中的异步实例方法访问，保留其原始名称。这种设计确保了熟悉原始库的用户可以无缝集成，同时利用异步编程的优势。
MetaTrader 类设计为异步上下文管理器，简化了 MetaTrader 终端的管理。进入上下文后，它会自动初始化终端并执行登录操作。退出时，即使发生错误，它也能确保资源的正确清理和断开连接。这种结构提供了一种简洁高效的生命周期管理方法，使其特别适合异步工作流程。
这些函数的非异步版本仍然可以访问，但前面带有下划线 (_) 前缀，表示它们可以被视为私有方法。
MetaBackTester 是 MetaTrader 的一个子类，专门用于回测。它使用 BackTestEngine 实例，可以在初始化期间提供该实例，也可以从配置中检索该实例。当 config.mode 设置为“backtest”时，此类会自动替换依赖于终端连接的应用程序中的 MetaTrader，从而确保回测功能的无缝集成。
Base 和 _Base 类是构成框架中其他类的基础组件，提供基本实用程序，例如数据验证、序列化以及根据系统是处于实时交易还是回测模式，无缝访问 MetaTrader 或 MetaBackTester 实例。虽然这些类很少直接使用，但它们通过作为更专业功能的支柱来确保整个系统的稳定性和可靠性。
Base 类提供强大的数据处理功能，重点是验证和序列化。在实例化期间，只能为在类主体中显式注释或从父类继承的属性赋值，并且这些值必须严格符合其定义的类型，从而确保结构化和类型安全的数据管理。
exclude (set): 在访问属性或生成对象的字典表示时要排除的属性名称集合。include (set): 要显式包含的属性名称集合。如果同时提供这两个集合，则此集合会覆盖 exclude 集合。dict: 一个属性，它将所有属性作为字典返回，应用在 exclude 和 include 集合中指定的过滤器。set_attributes(**kwargs): 一个动态设置实例属性的方法。它会验证输入并确保它们具有正确的类型。get_dict(exclude: set = None, include: set = None): 一个将实例的属性作为字典返回的方法，允许指定 exclude 和 include 过滤器。如果同时提供这两个参数，则 include 参数优先于 exclude 参数。此类是 Base 的子类，具有专门用于连接到终端的其他属性和功能。
config: 表示配置实例。此属性包含类运行所需的所有必要的配置设置。mt5 (MetaTrader | MetaBackTester): 提供 MetaTrader 或 MetaBackTester 实例，由 config 对象的 mode 属性确定。实例的类型取决于系统是处于实时交易模式 (MetaTrader) 还是回测模式 (MetaBackTester)。MetaTrader5 库将其大量的常量组织成专门的枚举，从而提高了开发人员的清晰度和功能性。这些枚举表示各种交易操作、订单类型、时间范围等等，通过将相关的常量分组到直观的类别下，简化了它们的使用。每个枚举都提供属性，并在适用的情况下提供其他方法或属性，从而实现转换、反向或派生值等功能。这种组织减少了错误，提高了代码可读性，并使常量更容易管理，尤其是在复杂的交易应用程序中。
例如 TradeAction、OrderFilling 和 TimeFrame 等枚举将常量封装为整数值，同时提供 Python 风格的字符串表示，以提高可用性。某些枚举（如 TimeFrame）包含高级方法，用于将秒转换为预定义的时间间隔或访问所有可能的值。通过系统地组织这些常量，MetaTrader5 库确保了更高效且更易于开发人员使用的体验，简化了与交易操作和平台数据的交互。
models 模块提供了一组组织良好的数据处理类，这些类构建在 MetaTrader5 库的结构之上。所有类都继承自 Base 类，该类添加了数据验证、序列化和过滤等功能，以简化其使用。这些类表示各种与交易相关的实体，例如 OrderSendResult、SymbolInfo 和 TradeRequest，允许开发人员有效地与 MetaTrader5 的交易环境进行交互。
每个类都封装了与其对应的交易实体相关的特定属性和特性，确保了健壮且结构化的数据管理。例如，SymbolInfo 提供有关金融工具的详细信息，而 TradeRequest 允许创建和提交交易操作。这种模块化设计增强了可读性，简化了复杂的交易工作流程，并确保了开发人员在其应用程序中利用 MetaTrader5 时的数据一致性和易用性。
TaskQueue 类使用 asyncio.PriorityQueue 实例有效地管理机器人或回测器的后台任务，以进行并发执行。它在后台持续运行，允许与其他组件（例如使用它来记录交易后执行数据的 Trader 类）无缝集成。任务通过 add 方法添加到队列中，但必须首先将其封装在 QueueItem 中，其中包含任务元数据，例如参数、优先级和完成要求。
通过可配置的工作人员数量、超时设置和任务优先级，TaskQueue 确保了强大的任务管理和错误处理。它支持有限或无限执行模式，并且可以根据优先级在终止之前优雅地清理剩余的任务。这种设计通过异步卸载和管理后台操作来增强工作流程，确保复杂交易或测试环境的平稳和可靠的功能。
Account 类是一个单例，用于管理经纪商帐户详细信息，确保在应用程序的生命周期中只存在一个实例。它继承自 Base 和 _AccountInfo，为访问特定于帐户的信息提供了结构化且用户友好的界面。这种体系结构确保了一致性并防止了重复实例，从而将帐户管理集中在应用程序中。
作为 AsyncContextManager，Account 类通过自动化初始化和清理过程来简化资源管理。进入其上下文时，它会初始化 MetaTrader 终端并登录到指定的帐户。退出时，它会确保正确关闭和清理资源。这种简化的方法增强了资源处理的可靠性，使帐户管理更直观，并减少了交易操作过程中出现错误的可能性。
connected (bool): 指示登录是否成功以及与终端的连接是否处于活动状态。如果帐户已连接，则返回 True。refresh(): 通过从终端检索最新的帐户详细信息来更新帐户实例，确保帐户数据保持最新。RAM 类负责在交易活动期间管理风险评估和风险管理。它具有 risk_to_reward、fixed_amount、min_amount、max_amount 和 risk 等属性，允许交易者有效地定义和控制其风险敞口。这些属性提供了设置每笔交易风险参数、最低和最高风险金额以及风险回报率的灵活性。
该类包括诸如 get_amount 之类的方法，该方法根据可用保证金和风险百分比计算每笔交易的风险金额，以及 check_losing_positions 和 check_open_positions，确保亏损或持仓数量保持在预定义的限制内。通过集成这些功能，RAM 类提供了一种全面的风险管理方法，增强了决策能力并促进了更安全的交易实践。
risk (float): 每笔交易的风险资本百分比，表示为整数（例如，1 表示 1%）。默认为 1。risk_to_reward (float): 风险回报率，表示潜在风险和回报之间的关系。默认为 2。fixed_amount (float): 每笔交易的固定风险金额，如果设置，则会覆盖基于百分比的计算。get_amount(): 根据配置的属性（例如风险、fixed_amount、min_amount 和 max_amount）计算并返回每笔交易的风险金额。RAM 类最好在 Trader 类中使用，可以在下单前使用它。
Candle 和 Candles 类是用于管理从终端检索的价格柱的自定义工具。Candle 类封装单个价格柱的数据，确保每个实例中都存在必填属性，如开盘价、最高价、最低价和收盘价 (OHLC)。它支持 Python 协议，包括哈希、迭代和比较，同时提供 keys() 和 values() 等方法来管理属性。此外，它还动态添加在实例化期间传递的属性，允许灵活的自定义。
Candles 类充当多个 Candle 对象的容器，这些对象按时间顺序排列。它使用 pandas DataFrame 来存储和管理其数据，从而与 pandas-ta 等工具无缝集成，以进行高级技术分析。通过支持各种 Python 协议（例如切片和迭代）并通过时间范围等专用属性扩展功能，此类作为开发交易策略的强大基础。它的多功能性确保在复杂分析工作流程中经常使用。
time (int): 蜡烛周期开始时间。open (float): 蜡烛的开盘价。high (float): 蜡烛周期内达到的最高价。low (float): 蜡烛周期内达到的最低价。close (float): 蜡烛的收盘价。tick_volume (float): 蜡烛周期内的 Tick 量。real_volume (float): 蜡烛周期内的实际交易量。spread (float): 蜡烛周期内的价差。Index (int): 一个自定义属性，指示蜡烛在序列中的位置。set_attributes(**kwargs): 从提供的关键字参数动态设置蜡烛实例的属性。is_bullish()：如果蜡烛是看涨的（收盘价大于或等于开盘价），则返回 True，否则返回 False。is_bearish()：如果蜡烛是看跌的（收盘价小于开盘价），则返回 True，否则返回 False。dict(exclude: set = None, include: set = None): 返回蜡烛属性的字典，可以选择使用 exclude 或 include 集合过滤属性。Index (Series[int]): 包含对象中所有蜡烛索引的 pandas Series。time (Series[int]): 包含对象中所有蜡烛时间的 pandas Series。open (Series[float]): 包含对象中所有蜡烛开盘价的 pandas Series。high (Series[float]): 包含对象中所有蜡烛最高价的 pandas Series。low (Series[float]): 包含对象中所有蜡烛最低价的 pandas Series。close (Series[float]): 包含对象中所有蜡烛收盘价的 pandas Series。tick_volume (Series[float]): 包含对象中所有蜡烛 Tick 量的 pandas Series。real_volume (Series[float]): 包含对象中所有蜡烛实际交易量的 pandas Series。spread (Series[float]): 包含对象中所有蜡烛价差的 pandas Series。Candle (Type[Candle]): 用于表示对象内单个蜡烛的类。timeframe (TimeFrame): 蜡烛的时间范围，根据其时间戳计算得出。data (DataFrame): 包含对象中所有蜡烛基础数据的 pandas DataFrame。rename(inplace=True, **kwargs): 重命名基础 DataFrame 的列。ta: 通过 data 属性直接对蜡烛执行技术分析，从而访问 pandas-ta 库。ta_lib: 提供对 ta 库的访问，用于额外的技术分析，将其用于需要您将 Series 或 DataFrame 对象作为参数传递的函数。columns: 返回基础 DataFrame 的列名。Ticks 和 Tick 类旨在管理来自交易终端的 Tick 数据，类似于 Candle 类。Tick 类表示单个 Tick，其属性包括 bid、ask、last price 和 volume，确保每个实例都封装单个 Tick 事件的必要数据。它支持动态属性管理并提供类似字典的访问，使其能够在不同的上下文中适应和易于操作。
Ticks 类充当多个 Tick 对象的容器，将数据存储在 pandas DataFrame 中，以便有效地进行操作和分析。它支持迭代、切片和各种数据操作，从而与 pandas-ta 等工具无缝集成，以进行技术分析。此类对于在交易系统中处理大量 Tick 数据至关重要，它为实时或历史数据分析提供了强大的结构。
_Symbol_ 类提供了一个强大的结构来封装金融工具的数据，支持启动交易之前所需的计算和操作。作为 _Base 和 SymbolInfo 的子类，它集成了广泛的属性和方法来有效地处理金融工具。此类可以针对来自不同经纪商的不同工具进行定制，确保跨交易平台的适应性。
通过用于访问当前 Tick 数据、管理市场深度和执行货币转换的实用程序方法，Symbol 类简化了复杂的交易任务。它提供了初始化符号、验证交易量和检索历史汇率或 Tick 的功能，使其成为开发交易策略的重要组成部分。它的设计确保开发人员可以扩展和自定义其行为以满足特定的交易要求。
Symbol 类是一个功能丰富的类。出于本文介绍的目的，我只触及一些您最有可能使用的重要内容。tick 和 account 是 Symbol 类的唯一属性，与在 SymbolInfo 父类中定义的属性不同。
tick (Tick): 表示金融工具的当前价格 Tick，提供实时市场数据。account (Account): 与符号关联的当前交易帐户的实例。__init__(*, name: str, **kwargs): 初始化符号实例。name 属性是必需的，并且必须与终端中经纪商指定的符号名称匹配。initialize(): 通过从终端检索最新的价格 Tick 和详细信息来填充符号实例。如果成功，则 select 属性设置为 True，并且所有属性都将填充服务器数据。convert_currency(*, amount: float, from_currency: str, to_currency: str): 将指定金额从一种货币转换为另一种货币。amount_in_quote_currency(*, amount: float): 如果帐户货币与报价货币不同，则将金额从帐户货币转换为报价货币。此方法对于执行风险管理计算特别有用。info_tick: 检索金融工具的当前价格 Tick。symbol_select(enable: bool = True): 将符号添加到 MarketWatch 窗口或从中移除。check_volume(volume: float): 验证指定的交易量是否在允许的限制内，并在必要时进行调整。round_off_volume(volume: float, round_down: bool = False): 将交易量四舍五入到最近的有效步长。compute_volume: 计算交易的适当交易量。copy_rates_from_pos(timeframe, start_position=0, count=500): 从特定索引开始获取柱线。copy_rates_from(timeframe, date_from, count=500): 从指定的日期开始检索历史汇率（柱线）。copy_ticks_from(date_from, count=100, flags=CopyTicks.ALL): 从指定的日期开始获取 Tick 数据。Symbol 类是一个多功能且功能丰富的工具，旨在管理金融工具，提供检索和转换数据的必要方法。虽然本介绍重点介绍了初始化、货币转换和检索最新 Tick 数据等关键功能，但在未来的讨论中将探讨其许多其他功能。这包括将其集成到算法交易系统中，展示其对各种用例的适应性。
一个值得注意的贡献是 ForexSymbol 类，它是 Symbol 类的专门扩展，专为外汇交易而设计。此子类旨在处理货币对交易的独特要求，进一步证明了 Symbol 类在不同交易场景中的灵活性和定制潜力。
Order 类通过组合相关的属性和方法来简化交易订单的管理，从而更容易检查、验证和发送订单。作为 _Base 和 TradeRequest 的子类，它继承了强大的功能，同时提供了额外的便利。通过为 action、type_time 和 type_filling 等属性设置合理的默认值，它最大限度地减少了实例化期间重复代码，确保了交易操作的效率和清晰度。
此类简化了核心任务，例如检索挂单、检查资金充足性以及计算保证金、利润和损失。send() 和 check() 等方法的集成确保了启动和验证交易操作的无缝工作流程，而 calc_margin() 和 calc_profit() 等实用程序有助于交易前分析。它的设计使其成为高效实施算法交易策略的重要工具。
__init__: 使用必须是有效 TradeRequest 属性的关键字参数初始化订单实例。action 的默认值为 DEAL，type_time 的默认值为 DAY，type_filling 的默认值为 FOK，尽管可以在实例化期间自定义它们。check(**kwargs): 在下单前验证订单。提供的任何关键字参数都将更新请求对象。send: 将订单发送到终端以执行。calc_margin: 计算进行交易所需的保证金。calc_profit: 计算交易的潜在利润。calc_loss: 计算交易的潜在损失。request: 此属性将交易请求对象作为字典返回。Trader 类充当用于管理交易下单的实用程序丰富的抽象基类。它提供了创建和管理各种订单类型的基础方法，同时处理关键流程，例如交易的验证、发送和记录。此类需要在其子类中实现 place_trade 方法，以确保灵活地适应特定的交易策略。
关键功能包括基于点或点数设置止损和止盈水平的方法、创建带有或不带有止损水平的订单以及计算交易的适当数量的方法。该类与已正确初始化的 Symbol 实例和可选的 RAM 实例集成以进行风险评估，从而实现无缝的交易管理。它还支持交易结果记录，方便跟踪和分析已执行的交易。
modify_order(**kwargs): 使用提供的关键字参数修改订单属性。modify_ram(**kwargs): 使用提供的关键字参数更新 RAM（风险评估和管理）实例属性。check_order: 在下单前验证订单，确保它满足必要的条件。send_order: 将订单发送给经纪商以执行。record_trade(*, result: OrderSendResult, parameters: dict = None, name: str = ""): 将交易详细信息记录到 CSV 或 JSON 文件中，并将任务委托给 config.task_queue 实例。包括交易结果和策略参数（如果提供）。contrib 包附带两个简单的交易者，ScalpTrader 和 SimpleTrader，其中 ScalpTrader 如下所示。
Session 和 Sessions 类提供了一个强大的框架来管理和执行交易时间。Session 表示一个在 UTC 中定义的时间段，具有开始时间和结束时间，可以指定为整数或 datetime.time 对象。这些会话可以触发预定义的操作，例如关闭所有交易或仅关闭盈利/亏损的仓位，或者用户指定的自定义操作。这允许策略在特定时期内对交易活动进行精确控制。
Sessions 类将多个 Session 实例分组到一个排序的集合中，从而可以轻松管理重叠或连续的交易时期。它充当异步上下文管理器，持续监控当前时间以确定活动会话。如果没有活动会话，则 Sessions 实例会暂停交易操作，直到下一个计划的会话开始，确保遵守指定的交易窗口。
通过集成这些类，交易策略可以轻松地结合基于时间的规则，从而提高其精度和可靠性。此功能在需要严格遵守交易时间（例如外汇或股票市场交易）或在需要操作与预定义时间间隔对齐的自动化系统中特别有用。
start (datetime.time): 会话在 UTC 中的开始时间。end (datetime.time): 会话在 UTC 中的结束时间。on_start (str): 指定会话开始时要执行的操作，例如 "close_all"、"close_win"、"close_loss" 或自定义操作。on_end (str): 指定会话结束时要执行的操作，类似于 on_start。custom_start (Callable): 会话开始时要执行的可选自定义函数。custom_end (Callable): 会话结束时要执行的可选自定义函数。name (str): 会话的名称，如果未提供，则默认为开始时间和结束时间的组合。in_session: 检查当前时间是否在会话内。begin: 在会话开始时执行 on_start 或 custom_start 指定的操作。close: 在会话结束时执行 on_end 或 custom_end 指定的操作。duration: 将会话的持续时间作为具有小时、分钟和秒的 Duration 对象返回。close_all: 关闭所有未平仓头寸。close_win: 关闭所有盈利头寸。close_loss: 关闭所有亏损头寸。action(action: str): 执行指定的操作，例如关闭头寸或触发自定义函数。until: 计算从当前时间到会话开始的时间（以秒为单位）。sessions (list[Session]): 按其开始时间排序的 Session 对象列表。current_session (Session | None): 当前活动会话（如果有）。find(moment: datetime.time = None): 查找并返回包含指定时间的会话。如果未提供时间，则使用当前时间。find_next(moment: datetime.time = None): 查找并返回指定时间后的下一个会话。如果未提供时间，则默认为当前时间。check: 监控当前会话。如果没有活动会话，它将等待直到下一个会话开始。config: 与会话关联的配置实例，确定模式（实时或回测）。Strategy 类是开发交易策略的基础框架，可以与 Bot 和 Backtester 无缝集成。作为抽象基类，它配备了许多功能，但在派生类中需要实现 trade 方法。此方法充当策略的核心交易逻辑。Strategy 类充当异步上下文管理器，并使用 run_strategy 方法执行策略，根据操作模式调用 live_strategy 或 backtest_strategy 方法。
通过 symbol、sessions 和 parameters 等属性，该类确保可以自定义策略并将其调整为特定的金融工具和交易会话。协作多任务方法（例如 sleep 和 delay）的集成确保策略在实时或回测环境中保持高效且与市场更新同步。这使得 Strategy 类成为构建复杂交易系统的强大而灵活的工具。
name (str): 策略的名称。如果未明确提供，则默认为类名。symbol (Symbol): 与策略关联的金融工具。parameters (dict): 特定于策略的参数字典。sessions (Sessions): 策略处于活动状态的交易会话。mt5 (MetaTrader | MetaBackTester): 基于模式（实时或回测）的 MetaTrader 或 MetaBackTester 实例。config: 策略的配置设置。running (bool): 指示策略当前是否正在运行。backtest_controller (BackTestController): 用于管理回测操作的控制器。current_session (Session): 当前活动的交易会话。__init__(symbol: Symbol, params: dict = None, sessions: Sessions = None, name: str = ""): 使用给定的符号、参数和会话初始化策略。以上是人工智能OMQL的详细内容。更多信息请关注PHP中文网其他相关文章！
