hydra-editor 0.1.0

Hydra Editor（Tkinter GUI + CLI）

hydra editor

一个基于 Tkinter 的 Hydra 配置管理 GUI：浏览配置组、组合预览、编辑 YAML，并可将当前选择写回主配置的 defaults。

环境要求

• Python 3.8+

依赖：hydra-core、omegaconf、PyYAML。

Linux 下如遇到 Tkinter 缺失：

• Debian/Ubuntu：sudo apt-get install python3-tk

安装

从 PyPI 安装（若已发布）：

pip install hydra-editor

从源码安装（推荐用于本仓库直接运行/开发）：

pip install -e .

启动

默认启动会尝试使用“当前工作目录”下的 ./conf/config.yaml。

# 模块方式
python3 -m hydra_editor

# 命令行入口
hydra-editor

指定主配置文件（相对/绝对路径都可）：

hydra-editor conf/config.yaml

# 等同写法
hydra-editor --config conf/config.yaml
python3 -m hydra_editor --config /abs/path/to/conf/config.yaml

说明：传入的必须是一个 .yaml 文件。程序会自动把该文件所在目录作为 Hydra 的 config_dir，并使用文件名（不含扩展名）作为 config_name。

GUI 使用指南（详细）

1) 界面布局

• 左侧：配置树（Config Groups）
  • 展示配置组目录结构（例如 db/、model/）。
  • 额外有一个顶层节点“同级文件”，用于展示主配置所在目录下的同级 YAML（例如 basis.yaml）。
• 右侧：当前组信息与选择控件
  • 普通配置组：使用下拉框选择 option。
  • “同级文件”：使用列表框多选（Ctrl/Shift 组合选择）。
• 右侧中部：Overrides 显示
  • 展示你当前的选择，会实时更新。
  • 如果某个组不在主配置的 defaults 中，显示时会带 + 前缀（表示 compose 时以追加方式启用）。
• 右侧底部：功能按钮
  • “生成并预览配置 / 保存为默认配置 / 编辑主配置 / 退出 / 重置选择”。

2) 选择一个配置组并选择 option

1. 在左侧树中点击某个配置组（例如 db）。
2. 在右侧下拉框选择该组的 option（例如 mysql）。
3. Overrides 框会立刻显示类似 db=mysql 的条目。

提示：如果你新增了一个新的配置组目录，但它没有出现在主配置的 defaults 里，GUI 仍然允许选择；预览合成时会把它作为 +group=option 追加。

3) 选择“同级文件”（根目录 YAML，多选）

当你在左侧点击“同级文件”后：

• 右侧会出现一个列表框，列出主配置目录下的同级 YAML（例如 basis）。
• 这些项可以多选；选择结果会显示在 Overrides 的最后（每行一个）。

说明：为了允许你“取消 defaults 里原本启用的同级 YAML”，GUI 预览时会以你当前的勾选为准，而不是强制保留 defaults。

4) 编辑配置文件（编辑按钮）

当你已经选中一个 option（或在“同级文件”里选中了一个条目）后，“编辑该配置文件”按钮会变为可点击：

1. 点击“编辑该配置文件”。
2. 在弹窗中编辑 YAML。
3. 点击“保存”。
   • 程序会先做 YAML 语法校验（不是语义校验）。
   • 校验通过后写回原文件，并直接关闭弹窗（不弹成功提示）。

5) 生成并预览配置（Compose Preview）

点击“生成并预览配置”后：

1. GUI 会在主配置目录旁生成一个临时预览文件 _gui_preview.yaml（仅用于本次预览）。
2. 使用 Hydra compose 合成最终配置。
3. 以 YAML 文本窗口展示合成结果。

如果合成失败，会弹窗显示错误原因（常见是某个 YAML 语法错误、引用不存在的 option、defaults 冲突等）。

6) 保存为默认配置（写回 defaults）

点击“保存为默认配置”会把你当前在 GUI 中的选择写回主配置文件的 defaults：

• 配置组选择（例如 db=mysql、model=bert）会以 - db: mysql 这种形式写回。
• “同级文件”的多选会以字符串项形式写回（例如 - basis）。
• 会尽量只替换 defaults 段，保留主配置其余内容。

7) 编辑主配置（不含 defaults）

点击“编辑主配置”会打开一个编辑器，只允许编辑主配置 config.yaml 中除 defaults 以外的内容：

• 如果你在该编辑器里写了 defaults 字段，会被阻止保存。
• 保存后 GUI 会重新加载配置树与默认选择。

8) 重置选择 / 退出

• “重置选择”：将选择恢复到主配置 defaults 中定义的默认状态。
• “退出”：关闭应用。

常见问题

• 启动时报 Tkinter 相关错误：按“环境要求”安装 python3-tk。
• 预览时报 Hydra compose 错误：通常是某个 YAML 语法或 defaults 引用不合法；可先用“编辑该配置文件”检查并保存校验。
• 想从任意目录运行：用 --config 或位置参数传入你的主配置文件绝对路径。