文档中心变量
变量（VAR）用于统一管理脚本、报表、流程等元素运行时需要使用的参数。适合承载年度、场景、期间、组织范围等跨元素共享参数，也支持按用户保存个性化变量值。
变量组件的 Python SDK 不仅支持读取变量值，也支持新增、更新、删除变量定义。以下方法按常见使用阶段归类；其中 get(...) 是高频调用方式。
1. 初始化变量对象
from deepfos.element.variable import Variable
var = Variable(element_name='VAR', path='/01_Application/07_VAR')
用于定位一个变量元素，后续读取或维护变量都基于该对象进行。
2. 读取变量
get(name, default=None)
按变量名称读取值。若变量不存在，可返回默认值。
year = var.get('vYear')
period = var.get('vPeriod', default='1')
适合脚本运行时读取年、场景、期间等公共参数。
get_value(name, is_customize_value=False, default=None)
按变量名称读取值，可控制是否读取自定义值。适合区分默认值和用户自定义值的场景。
curr_entity = var.get_value('curr_entity', is_customize_value=True, default='E0101')
get_variable(name)
读取变量完整定义，而不仅仅是变量值。适合需要查看变量类型、描述或其他元数据的场景。
variable_info = var.get_variable('vScenario')
3. 新增变量
支持按变量类型新增成员，常用方法包括：
-
add_text(...) -
add_number(...) -
add_dimension(...) -
add_date(...) -
add_custom_list(...)
示例：
var.add_text(name='curr_version', default_value='V01')
var.add_number(name='vPeriod', default_value='8')
var.add_dimension(name='curr_entity', dimension_name='Entity', default_value='E0101')
var.add_date(name='start_date', default_value='2025-01-01')
var.add_custom_list(name='curr_currency', default_value='CNY')
4. 更新变量
常见更新方法包括：
-
update_value(name, update_value, is_customize_value=True)：更新变量值 -
update_description(name, en_description, zh_cn_description)：更新变量描述
示例：
var.update_value('curr_entity', 'E0102', is_customize_value=True)
var.update_description('vPeriod', en_description='Current period', zh_cn_description='当前期间')
5. 删除变量
使用 delete_variables(*names) 删除一个或多个变量。
var.delete_variables('old_period', 'old_scenario')
6. 保存变更
使用 save() 统一提交前述新增、更新、删除操作。
var.save()
如果调用了新增、更新、删除类方法，通常需要再执行 save() 才会生效。
使用说明
-
变量通常用于统一管理脚本运行过程中需要反复使用的公共参数，如年度、场景、期间和组织范围。
-
读取场景中，
get(...)是最常见的调用方式，适合直接获取当前运行参数。 -
若需要区分默认值与用户个性化值，可使用
get_value(...)。 -
除统一的
VAR外，也可以按模块拆分为独立变量元素，例如集成类或业务模块专用变量。
常见示例
示例 1：读取全局运行变量
在脚本初始化阶段，通常会读取当前年、场景、期间等公共参数。
from deepfos.element import Variable
year = Variable(element_name='VAR', path='/01_Application/07_VAR').get('vYear')
scenario = Variable(element_name='VAR', path='/01_Application/07_VAR').get('vScenario')
period = Variable(element_name='VAR', path='/01_Application/07_VAR').get('vPeriod')
适用场景：
-
调度脚本获取当前运行期
-
预算/汇率/YTD 脚本读取全局参数
-
版本复制时决定期间范围
示例 2：先实例化 Variable，再多次 get
当同一个脚本需要多次读取变量时，通常会先实例化对象，再按名称分别获取变量值。
from deepfos.element import Variable
variable = Variable(element_name='VAR')
v_year = variable.get('vYear')
v_scenario = variable.get('vScenario')
v_period = int(variable.get('vPeriod'))
适用场景：
-
同一个脚本里连续读取多个变量
-
需要先做类型转换再参与计算
示例 3：在业务判断中读取变量
变量也可以直接参与业务判断，例如根据当前期间动态生成期间范围。
from deepfos.element import Variable
if source_scenario == 'Actual':
var_period = Variable(element_name='VAR', path='/01_Application/07_VAR').get('vPeriod')
period_list = [f"{i}" for i in range(1, int(var_period) + 1)]
适用场景：
-
根据变量动态决定期间范围
-
复制 Actual 到 Forecast 时按当前期间截断
示例 4：读取非 VAR 变量元素
变量元素不一定统一命名为 VAR，也可以按业务模块分别管理。
from deepfos.element import Variable
app_hb = Variable('GV_SAP').get('GV_HB_APP_NAME')
适用场景：
-
集成类脚本读取外部系统参数
-
按模块管理独立变量集
回到顶部
咨询热线
400-821-9199
