Metadata-Version: 2.4
Name: hydra-editor
Version: 0.1.0
Summary: Hydra Editor（Tkinter GUI + CLI）
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: hydra-core>=1.3
Requires-Dist: omegaconf>=2.3
Requires-Dist: PyYAML>=6.0

# 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 安装（若已发布）：

```bash
pip install hydra-editor
```

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

```bash
pip install -e .
```

## 启动

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

```bash
# 模块方式
python3 -m hydra_editor

# 命令行入口
hydra-editor
```

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

```bash
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` 或位置参数传入你的主配置文件绝对路径。

