持久化数据

python SDK gm库需要升级到 3.0.191版本及以上版本

gmsdk 提供一组持久化数据 key-value 接口，供策略在运行期间读写自定义数据（如：股票池、实时动态参数、策略级持仓记录等）。接口通用约定如下：

① 调用时机：允许在策略运行（init 初始化策略 + run 运行策略）和数据研究场景调用，非策略运行期间调用将被拒绝；

② 策略隔离：每个策略运行时可绑定并使用 1 个 bucket，对应 1 个持久化数据文件；

③ 模式切换：同一个策略，1 个 bucket 对应的持久化数据文件不区分回测（MODE_BACKTEST）与实时（MODE_LIVE）模式，策略切换运行模式 bucket 不变会访问同一个持久化数据；

④ 返回约定：写操作类接口统一返回 status，status = 0 表示成功，非 0 表示失败（错误码定义见 gmsdk 全局错误码表）。

ERR_PERSIST_INIT_ERROR              71001   # Persist组件初始化失败
ERR_PERSIST_NOT_INIT                71002   # Persist组件未初始化
ERR_PERSIST_KEY_ERROR               71003   # KEY太长或为空
ERR_PERSIST_STSTEM_ERROR            71004   # Persist系统错误
ERR_PERSIST_USING                   71005   # bucket正在使用中，无法删除
ERR_PERSIST_INIT_ALREADY            71006   # Persist组件已初始化，不能再初始化别的bucket

persist_init - 初始化持久化数据

初始化指定bucket，限定一个策略运行周期只能操作一个持久化数据。

函数原型：

persist_init(bucket, is_async=True)

参数：

返回值：int

示例：

bucket = "strategy_demo"  # 持久化数据标识，同一策略全局唯一

status = persist_init(bucket)
if status == 0:
    print("初始化成功")
else:
    print("初始化失败, 错误码:", status)

注意：

1. persist_init 必须在策略运行期间调用（init 策略初始化阶段），且每个策略运行周期内只允许初始化 1 个 bucket；重复初始化同一 bucket 幂等返回成功，初始化不同 bucket 会报错。

2. persist_init 成功后，才能调用后续 persist_set / persist_get / persist_delete / persist_clear 方法，且这些方法无需再指定 bucket。

3. 同一持久化数据文件可被多个策略访问，但在同一时间只能被一个策略进程访问读写，后访问的策略会在初始化时报错并被拒绝访问。

persist_set - 写入持久化数据

向当前绑定的 bucket 写入数据。

函数原型：

persist_set(key, value)

参数：

返回值：int

示例：

key = "stock_pool"              # 数据键，长度不超过 512
value = "SHSE.600519,SZSE.000001"  # 字符串数据值

status = persist_set(key, value)
if status == 0:
    print("写入成功")
else:
    print("写入失败, 错误码:", status)

注意：

1. 首次向当前绑定的 bucket 写入数据，会新创建该 bucket 的持久化数据文件。

2. 向当前绑定的 bucket 再次写入数据时，若指定 key 已存在会覆盖写入，若指定 key 不存在会创建新的数据键并写入数据值。

persist_get - 读取持久化数据

从当前绑定的 bucket 读取数据。

函数原型：

persist_get(key)

参数：

返回值：str | None

示例：

value = persist_get("stock_pool")
if value is not None:
    print("读取成功:", value)
else:
    print("该 key 不存在")

persist_delete - 删除持久化数据中指定的key-value数据

删除当前绑定 bucket 中指定 key-value 的数据。

函数原型：

persist_delete(key)

参数：

返回值：int

示例：

status = persist_delete("stock_pool")
if status == 0:
    print("删除成功")

注意：

1. 此接口只能删除当前绑定 bucket 中的 key，不会删除其他 bucket 中的 key; 删除在当前 bucket 中不存在的 key（其他 bucket 的 key），也会返回 status = 0.

persist_clear - 清空持久化的全部key-value数据

清空当前绑定 bucket 中全部 key-value 的数据。

函数原型：

persist_clear()

返回值：int

示例：

status = persist_clear()
if status == 0:
    print("清空成功")

persist_delete_bucket - 删除持久化数据 bucket

删除非当前绑定的持久化数据 bucket。

函数原型：

persist_delete_bucket(bucket)

参数：

返回值：int

示例：

status = persist_delete_bucket(bucket="other_strategy_bucket")
if status == 0:
    print("删除成功")

注意：

1. 删除非当前绑定的 bucket，将删除对应的持久化数据文件；删除后该 bucket 不存在，策略重启后重新初始化 persist_init 绑定该 bucket 并用 persist_set 重新写入数据时，会重新创建该 bucket 的持久化数据文件。

persist_get_all_buckets - 查询持久化数据 bucket 列表

查询当前已创建的全部持久化数据标识（bucket），用于盘点本地持久化数据文件（单个策略可创建多个 bucket，单次运行进程内读写时绑定并使用其中一个）。

函数原型：

persist_get_all_buckets()

返回值：list[str]

示例：

ids = persist_get_all_buckets()
print("本地持久化数据标识:", ids)  # 例如 ['strategy_demo', 'signal_cache']

注意：

1. 查询接口只读取本地持久化数据目录的元数据（标识列表），不读写具体数据文件内容，不受"单次运行进程内最多只能读写 1 个持久化数据 bucket"限制。

2. 调用时机：仅策略运行期间可调用，可在persist_init()初始化前被调用。

persist_get_all_keys - 查询当前绑定 bucket 所有 key

查询当前绑定的 bucket 下已保存的全部数据键（key），用于盘点该持久化数据文件中的数据健。

函数原型：

persist_get_all_keys()

返回值：list[str]

示例：

keys = persist_get_all_keys()
print("bucket 下全部 key:", keys)  # 例如 ['stock_pool', 'strategy_name']

注意：

1. 查询接口只读取元数据（键名列表），不读取数据值。

2. 调用时机与策略隔离规则与其他接口一致：仅策略运行期间可调用，需在 persist_init() 初始化后调用，查询当前绑定 bucket 的 key。

persist_set/get_obj - JSON可序列化对象读写方法

自动将 dict / list 等 JSON 可序列化对象序列化后写入，读取时反序列化还原，适合保存股票池、实时动态参数、策略级持仓等结构化数据。

函数原型：

persist_set_obj(key, value)
persist_get_obj(key)

参数：

返回值：int（set接口），Any | None （get接口）

示例：

pool = {"stocks": ["SHSE.600519", "SZSE.000001"], "updated_at": 20260928}
status = persist_set_obj("stock_pool", pool)
if status == 0:
    print("写入成功")

data = persist_get_obj("stock_pool")
print(data["stocks"])  # ["SHSE.600519", "SZSE.000001"]