BigModule模块模板
由small_q创建,最终由small_q 被浏览 139 用户
我们将向你简单介绍一个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
代码的基本组织结构如下:
\
模块基本信息
基本信息部分包含的内容主要是:
- 模块名
- 模块描述
\
依赖包导入
在此部分中导入需要用到的外部包。
默认会从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
\
模块元数据
模块元数据包含以下内容:
- author:模块作者署名
- category:模块分类,用于设置模块在可视化策略的目录中所在位置
- friendly_name:模块显示名,用于设置模块在可视化策略所显示的名称
- doc_url:模块相关文档(可选),添加文档的url链接,方便使用者了解该模块的功能
- 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与传出参数有区别,这一点与普通函数不同,请多加确认以下规则:
-
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()函数中使用。
- outputs可以包含除传出参数外的其他数据,post_run()后置函数可以使用run()函数返回的所有变量。
- 具体关系参考下图:
\
后置函数
post_run()函数将在run()函数执行后执行,并且自动捕获run()函数输出的结果,并允许使用该结果进行操作。
\