Mod

创建您的第一个Mod

每一个Mod都遵循扩展事件源的细则，通过对接接口即可实现各种逻辑的组合，而 Mod 接口是扩展事件源的标准格式，下面我们将创建一个最简单的Mod帮助大家理解。

警告

在克隆RQAlpha的时候发现我们有一些系统集成的 Mod 在 RQAlpha 里，这是为了大家可以能更好了解Mod逻辑，但是在开发Mod的过程里我们不建议您在原有的 RQAlpha 项目中做更改，而是将 Mod 以独立的项目进行开发。

Mod开发环境搭建

首先我们创建独立的开发虚拟环境：

  1. $ conda create rqalpha-mod-hello

在虚拟环境下将 RQAlpha 安装好：

如有问题请参考：安装指南

创建Mod项目

我们以 rqalpha-mod-hello 项目为例，介绍如何实现一个简单的 Mod

项目结构:

  1. rqalpha-mod-hello
  2. ├── __init__.py
  3. ├── requirements.txt
  4. ├── README.rst
  5. ├── setup.py
  6. └── rqalpha_mod_hello
  7.     ├── __init__.py
  8.     └── mod.py

假设在新的环境中已经可以成功运行 RQAlpha ，便按照Mod的标准命名格式创建项目 rqalpha-mod-hello。进入 rqalpha-mod-hello 文件夹，创建 init.py，填入以下代码：

  1. __config__ = {
  2.     "url": None,
  3.  
  4. }
  5.  
  6. def load_mod():
  7.     from .mod import HelloWorldMod
  8.     return HelloWorldMod()

创建 mod.py ，填入以下代码：

  1. from rqalpha.interface import AbstractMod
  2.  
  3.  
  4. class HelloWorldMod(AbstractMod):
  5.     def start_up(self, env, mod_config):
  6.         print(">>> HelloWorldMod.start_up")
  7.  
  8.     def tear_down(self, success, exception=None):
  9.         print(">>> HelloWorldMod.tear_down")

我们第一个 Mod 就写好了，接下来我们需要写一个 setup.py 以便我们以PyPI的形式发布以及安装。

PyPI方式安装Mod

在项目 rqalpha-mod-hello 下新建 setup.py ，按照以下格式填入代码。

  1. #from pip.req import parse_requirements 这样的话如果pip版本较高会报错
  2. try: # for pip >= 10
  3.     from pip._internal.req import parse_requirements
  4. except ImportError: # for pip <= 9.0.3
  5.     from pip.req import parse_requirements
  6.  
  7. from setuptools import (
  8.     find_packages,
  9.     setup,
  10. )
  11.  
  12. setup(
  13.     name='rqalpha-mod-hello',     #mod名
  14.     version="0.1.0",
  15.     description='RQAlpha Mod to say hello',
  16.     packages=find_packages(exclude=[]),
  17.     author='your name',
  18.     author_email='your email address',
  19.     license='Apache License v2',
  20.     package_data={'': ['*.*']},
  21.     url='https://github.com/johnsonchak/rqalpha-mod-hello',
  22.     install_requires=[str(ir.req) for ir in parse_requirements("requirements.txt", session=False)],
  23.     zip_safe=False,
  24.     classifiers=[
  25.         'Programming Language :: Python',
  26.         'Operating System :: Microsoft :: Windows',
  27.         'Operating System :: Unix',
  28.         'Programming Language :: Python :: 3.5',
  29.         'Programming Language :: Python :: 3.6',
  30.     ],
  31. )

在完成 setup.py 文件的同时需要为Mod添加版本信息 VERSION.txt 以及运行所需环境说明文件 requirements.txt :

完成以后即可在命令进入Mod项目的 setup.py 所在路径下进行安装:

  1. $ rqalpha mod install -e .

注解

  1. $ rqalpha mod install -e .

会扫描当前目录下的 setup.py 文件执行安装，同时直接修改项目内文件就可以实现修改对应Mod。

安装成功后将看到下图：https://raw.githubusercontent.com/ricequant/rq-resource/master/rqalpha/mod-install-success.png

激活以及使用Mod

对 Mod 进行激活：

  1. $ rqalpha mod enable hello

运行RQAlpha即可看到如下：https://raw.githubusercontent.com/ricequant/rq-resource/master/rqalpha/mod-run-success.png

注解

至此，完成了第一个Mod的创建以及安装，如您想与RQAlpha用户分享自己的Mod，您需要遵守一些发布格式，以便他人进行管理及使用。

发布独立 Pypi 包作为 Mod

扩展 RQAlpha API

如果你想为 RQAlpha 创建自己的 API，你也可以通过 Mod 来注册新的 API。在内建的 mod 中，有一个 FuncatAPIMod ，将通达信、同花顺的公式表达能力移植到 Python 中，扩展了 RQAlpha 的 API。

其中的关键点，是通过了 register_api 来注册 API。

我们只需要实现一个 Mod，然后在 start_up 过程中，使用 register_api 来注册 API ，既可以达到扩展 RQAlpha API 的功能。

  1. class FuncatAPIMod(AbstractMod):
  2.     def start_up(self, env, mod_config):
  3.         try:
  4.             import funcat
  5.         except ImportError:
  6.             print("-" * 50)
  7.             print(">>> Missing funcat. Please run `pip install funcat`")
  8.             print("-" * 50)
  9.             raise
  10.  
  11.         # change funcat data backend to rqalpha
  12.         from funcat.data.rqalpha_backend import RQAlphaDataBackend
  13.         funcat.set_data_backend(RQAlphaDataBackend())
  14.  
  15.         # register funcat api into rqalpha
  16.         from rqalpha.api.api_base import register_api
  17.         for name in dir(funcat):
  18.             obj = getattr(funcat, name)
  19.             if getattr(obj, "__module__", "").startswith("funcat"):
  20.                 register_api(name, obj)
  21.  
  22.     def tear_down(self, code, exception=None):
  23.         pass

发布独立 Pypi 包作为 Mod

RQAlpha 支持安装、卸载、启用、停止第三方Mod。

  1. # 以名为 "xxx" 的 Mod 为例，介绍RQAlpha 第三方Mod的使用
  2.  
  3. # 安装
  4. $ rqalpha mod install xxx
  5.  
  6. # 卸载
  7. $ rqalpha mod uninstall xxx
  8.  
  9. # 启用
  10. $ rqalpha mod enable xxx
  11.  
  12. # 关闭
  13. $ rqalpha mod disable xxx

如果您希望发布自己的Mod并被 RQAlpha 的用户使用，只需要遵循简单的约定即可。

下面为一个 RQAlpha Mod 的模板:

  1. from rqalpha.interface import AbstractMod
  2.  
  3.  
  4. class XXXMod(AbstractMod):
  5.     def __init__(self):
  6.         pass
  7.  
  8.     def start_up(self, env, mod_config):
  9.         pass
  10.  
  11.     def tear_down(self, code, exception=None):
  12.         pass
  13.  
  14.  
  15. def load_mod():
  16.     return XXXMod()
  17.  
  18.  
  19. __mod_config__ = """
  20.   param1: "111"
  21.   param2: "222"
  22. """

约定如下：

  • 需要定义并实现 load_mod 函数, 其返回值为对应的继承自 AbstractMod 的类，并且 load_mod 所在文件必须按照 rqalpha_mod_xxx 规则进行命名。
  • 如果有自定义参数的话，需要实现 mod_config 变量，其为字符串，配置的具体格式为 yaml 格式(支持注释)。RQAlpha 会自动将其扩展到默认配置项中。
  • 当写好 Mod 以后，需要发布到 Pypi 仓库中，并且包名需要如下格式: rqalpha-mod-xxx，一下的 setup.py 文件可作参考。
  1. from pip.req import parse_requirements
  2.  
  3. from setuptools import (
  4.     find_packages,
  5.     setup,
  6. )
  7.  
  8. setup(
  9.     name='rqalpha-mod-xxx',
  10.     version="0.1.0",
  11.     description='RQAlpha Mod XXX',
  12.     packages=find_packages(exclude=[]),
  13.     author='',
  14.     author_email='',
  15.     license='Apache License v2',
  16.     package_data={'': ['*.*']},
  17.     url='',
  18.     install_requires=[str(ir.req) for ir in parse_requirements("requirements.txt", session=False)],
  19.     zip_safe=False,
  20.     classifiers=[
  21.         'Programming Language :: Python',
  22.         'Operating System :: Microsoft :: Windows',
  23.         'Operating System :: Unix',
  24.         'Programming Language :: Python :: 3.5',
  25.         'Programming Language :: Python :: 3.6',
  26.     ],
  27. )

按此编写好 Mod 并发布到 Pypi 上以后，就可以直接使用RQAlpha的命令来安装和启用该Mod了。

如您不熟悉PyPI发布的流程，请参考官方文档：https://packaging.python.org/distributing/

如果您希望更多人使用您的Mod，您也可以联系我们，我们审核通过后，会在 RQAlpha 项目介绍和文档中增加您的Mod的介绍和推荐。