Pyruns

Appearance

API 参考 ​

公开 API ​

用户脚本中可直接调用以下函数：

python
import pyruns

pyruns.read(file_path=None) ​

读取配置文件并初始化全局 ConfigManager。

参数：

参数类型默认值说明
file_pathstr?None配置文件路径（YAML 或 JSON）

查找优先级：

优先级来源说明
1环境变量 __PYRUNS_CONFIG__由 pyr executor 自动设置，指向任务的 config.yaml
2显式传入的 file_path—
3默认路径_pyruns_/{script}/config_default.yaml

示例：

python
pyruns.read()                          # 自动查找
pyruns.read("configs/experiment.yaml") # 指定路径

异常：配置文件不存在时抛出 FileNotFoundError；解析失败时抛出 RuntimeError。

pyruns.load() ​

返回已加载的配置对象。在 pyr 环境下会自动加载当前任务配置，无需手动调用 read()。

使用 pyruns.load() 的脚本需要确保 _pyruns_/{script}/config_default.yaml 已存在。可通过 pyr script.py your_config.yaml 一次性导入，后续直接 pyr script.py 即可。

返回值：ConfigNode | list[ConfigNode] — 支持点号属性访问的配置对象。

示例：

python
pyruns.read()
config = pyruns.load()

# 点号访问
print(config.lr)               # 0.001
print(config.model.name)       # "resnet50"

# 列表类型
print(config.layers)           # [64, 128, 256]

# 转回字典
d = config.to_dict()

异常：未调用 read() 且无法自动定位配置时抛出 RuntimeError。

pyruns.add_monitor(data=None, **kwargs) ​

向当前任务的 task_info.json 追加监控数据。适用于在训练结束时记录关键指标，随后可在 Monitor 页面跨任务聚合导出。

参数：

参数类型说明
datadict?字典形式的监控数据
**kwargs关键字参数形式的监控数据

行为：

  • 同一次 Run 内多次调用会合并到同一条记录
  • 数据追加到 task_info.json 的 "monitors" 列表
  • 不在 pyr 管理的任务中运行时（无 __PYRUNS_CONFIG__ 环境变量），调用被静默忽略
  • 写入失败时自动重试（最多 5 次）

示例：

python
import pyruns

# 1. 记录最终指标（推荐）
# 训练结束后调用一次
pyruns.add_monitor(loss=0.234, acc=95.2)

# 2. 混合使用字典参数
pyruns.add_monitor({"base_loss": 0.5}, final_acc=98.1)

写入的 JSON 结构：

json
{
    "monitors": [
        {
            "loss": 0.234,
            "acc": 95.2
        }
    ]
}

异常：data 非 dict 类型时抛出 TypeError。

ConfigNode ​

pyruns.load() 返回的配置对象类型。

属性访问 ​

python
node = ConfigNode({"a": 1, "b": {"c": 2}})
node.a      # 1
node.b.c    # 2

to_dict() → dict ​

递归转换回普通 Python 字典。

python
config.to_dict()  # {"a": 1, "b": {"c": 2}}

__repr__() ​

仿 argparse 风格的字符串表示：

python
repr(config)  # "ConfigNode(a=1, b=ConfigNode(c=2))"

工具函数 ​

pyruns.utils.config_utils ​

generate_batch_configs(base_config) → list[dict] ​

根据 Product / Zip 语法生成多个配置组合。详见 批量生成语法。

count_batch_configs(base_config) → int ​

预览将生成的配置数量（不实际生成）。

load_yaml(path) → dict ​

安全加载 YAML 文件，异常时返回空字典。

save_yaml(path, data) ​

将字典保存为 YAML 文件。

parse_value(val_str) → Any ​

将字符串输入解析为 Python 原生类型。

flatten_dict(d, sep='.') → dict ​

将嵌套字典展平为点号分隔的单层字典。

python
flatten_dict({"a": {"b": 1, "c": 2}})
# {"a.b": 1, "a.c": 2}

unflatten_dict(d, sep='.') → dict ​

将展平的字典还原为嵌套字典。

pyruns.utils.info_io ​

load_task_info(task_dir) → dict ​

从任务目录加载 task_info.json。

save_task_info(task_dir, info) ​

将字典保存到任务目录的 task_info.json。

load_monitor_data(task_dir) → list[dict] ​

从 task_info.json 中提取 "monitors" 字段。

get_log_options(task_dir) → dict[str, str] ​

返回 {显示名: 文件路径} 映射，包含 run_logs/ 目录下所有 runN.log 文件。

resolve_log_path(task_dir, log_file_name=None) → str? ​

解析日志文件的完整路径。未指定名称时返回第一个可用的日志。

pyruns.utils.parse_utils ​

detect_config_source_fast(filepath) → tuple[str, str?] ​

用正则快速检测脚本的配置来源：

python
("argparse", None)           # 使用 argparse
("pyruns_read", "config.yaml")  # 使用 pyruns.read("config.yaml")
("unknown", None)            # 无法检测

extract_argparse_params(filepath) → dict[str, dict] ​

通过 AST 解析提取 add_argument() 调用的所有参数信息。当同时提供短参数和长参数名时（如 -b, --batch_size），会优先使用长参数名作为字典的键。

python
{
    "lr": {"name": "--lr", "type": float, "default": 0.001, "help": "学习率"},
    "epochs": {"name": "--epochs", "type": int, "default": 10},
    "batch_size": {"name": "--batch_size", "type": int, "default": 32, "help": "批大小"},
}

pyruns.utils.process_utils ​

is_pid_running(pid) → bool ​

跨平台检测进程是否仍在运行。Windows 使用 kernel32.OpenProcess，Unix 使用 os.kill(pid, 0)。

kill_process(pid) ​

跨平台终止进程树。Windows 使用 taskkill /F /T /PID，Unix 使用 os.kill(SIGTERM)。