BigModule模块模板
由small_q创建，最终由small_q 被浏览 226 用户
我们将向你简单介绍一个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()函数输出的结果，并允许使用该结果进行操作。
\