首页 编写策略 数据平台 策略社区 我的策略 宽客学院 知识库
免费注册
BigQuant使用文档

BigModule模块模板

由small_q创建，最终由small_q 被浏览 275 用户

我们将向你简单介绍一个bigmodule模块内容的基本组织结构，为实际开发提供帮助🚀。

BigModule模块结构

下面将以一个bigmodule模块模板为例，向你介绍bigmodule模块的主要内容。

参考 📄BigModule简介与入门，当我们通过命令创建了一个模块模板后，产生的文件如下：

在开发时，我们在 ~/模块名/src/模块名/__init__.py 中编写模块的执行代码。

打开该文件，bigmodule模块模板代码如下：

"""hello package.

hello module
"""

from bigmodule import I

# 需要安装的第三方依赖包
# from bigmodule import R
# R.require("requests>=2.0", "isort==5.13.2")

# metadata
# 模块作者
author = "BigQuant"
# 模块分类
category = "示例模块"
# 模块显示名
friendly_name = "hello"
# 文档地址, optional
doc_url = "https://bigquant.com/wiki/"
# 是否自动缓存结果
cacheable = True


def run(
    input_1: I.port("某个输入端，对这个输入数据源的说明"),
    param1: I.int("没有限制的int参数") = 10,
    param2: I.int("一个int参数", min = 0, max = 100) = 50,
    param3: I.float("一个float参数", min = -100.21, max = 10) = 0.23,
)->[
    I.port("一个DataFrame", "data")
]:
    import pandas as pd
    import dai

    df = pd.DataFrame({"a": [param1, param2, param3]})
    return I.Outputs(data=dai.DataSource.write_bdb(df))


def post_run(outputs):
    """后置运行函数"""
    return outputs

代码的基本组织结构如下：

\

模块基本信息

基本信息部分包含的内容主要是：

  1. 模块名
  2. 模块描述

\

依赖包导入

在此部分中导入需要用到的外部包。

默认会从bigmodule中导入I，其主要用于run()函数传入和传出参数的定义。

在大部分情况下，AIStudio线上开发环境已经默认安装了许多常用的第三方库，例如numpy、pandas等，只需导入（import）即可使用。

但若开发者安装并使用了开发环境没有默认提供的第三方依赖库，则可以通过bigmodule.R，来检查并自动安装需要的库，以确保模块能够在其他使用者的开发环境中正常执行：

from bigmodule import R
R.require("库名>=版本号") # 在指定版本号时，可用使用 >= 或 ==

以下是示例：

# 需要安装的第三方依赖包
from bigmodule import R
R.require("requests>=2.0", "isort==5.13.2")
# "requests >= 2.0" 声明了需要使用requests库，且该库的版本应高于或等于2.0
# "isort==5.13.2" 声明了需要使用isort库，且该库的版本应等于5.13.2

\

模块元数据

模块元数据包含以下内容：

  1. author：模块作者署名
  2. category：模块分类，用于设置模块在可视化策略的目录中所在位置
  3. friendly_name：模块显示名，用于设置模块在可视化策略所显示的名称
  4. doc_url：模块相关文档（可选），添加文档的url链接，方便使用者了解该模块的功能
  5. cacheable：模块结果自动缓存，可设置为True或False。若设置为True，在多次重复执行同一模块时，会使用缓存加速该过程。

\

执行函数

若模块在可视化策略中被调用，便会执行run()函数，因此需要在run()中实现相关的操作流程。

run()与正常的函数基本结构一致，需要定义传入参数、传出参数和函数体。只不过略有不同的是，为了方便不同类型的数据在模块之间传输以及方便用户设置参数，需要使用 bigmodule.I 将参数的类型进行定义与封装。

传入参数定义

传入参数定义的基本格式为：

参数标识符1: 类型(该类型的相关设置)=默认值,
参数标识符2: 类型(该类型的相关设置)=默认值,
...
  • 参数标识符，将作为变量名在函数体中使用
  • 类型，定义具体类型，参考 📄BigModule中的基本类型
  • 默认值（可选），当用户不对参数进行设置时，便会使用默认值

例如：

def run(
    input_1: I.port("某个输入端，对这个输入数据源的说明"),
	param1: I.int("没有限制的int参数") = 10,
)->[...]:
	# do something

传出参数定义

传出参数定义的基本格式为：

I.port(相关设置1),
I.port(相关设置2),
...

run()函数定义的返回值，一般只有一种情况，就是要将某些数据传递给下一个模块，所以类型定义为I.port。

例如：

def run(
	...
)->[
    I.port("一个DataFrame", "data")
]:
    # do something

函数体

在函数体中编写主要的执行代码，同时注意，在使用return返回数据时，需要使用 I.Outputs 进行封装，详情请参考 📄BigModule中的基本类型

⚠请注意，run()函数通过return返回的结果outputs与传出参数有区别，这一点与普通函数不同，请多加确认以下规则：

  1. outputs一定包含所有被定义的传出参数，二者通过变量名相关联。

    def run(
	...
)->[
    # 定义一个传出参数
	I.port(desc="这是一个传出参数"， name="data")
]:
	# do something
    # 获得名为 some_data 的数据
    # 设置一个名为 print_data 的布尔变量

	# 在结果中设置同名属性
	return I.Outputs(data=some_data, print_data=print_data)

​ 这样，return 返回结果中的 data 就会作为模块的输出，允许传递给下一个模块，但是外部模块无法捕获到 print_data 变量，该变量只能在post_run()函数中使用。

  1. outputs可以包含除传出参数外的其他数据，post_run()后置函数可以使用run()函数返回的所有变量。
  2. 具体关系参考下图：

\

后置函数

post_run()函数将在run()函数执行后执行，并且自动捕获run()函数输出的结果，并允许使用该结果进行操作。

\

{link}