gp-autowidget 0.1.0

General Platform AutoWidget

gp-aw: General Platform AutoWidget

gp-aw 是一个通用平台自动化小部件库，用于根据类型信息自动推断和创建适当的UI小部件。它提供了一套完整的工具链，将数据类型映射到相应的UI控件，简化了GUI应用程序的开发过程。

许可证

本项目采用 MIT 许可证:

MIT License

Copyright (c) 2023 notmmao

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

特性

• 类型推断: 自动根据Python类型提示推断合适的UI小部件类型
• 多类型支持: 支持基本类型(bool, int, float, str)、枚举、字面量、集合等
• Qt集成: 提供Qt小部件工厂，轻松创建PySide6控件
• 元数据提取: 从类型信息中提取UI所需的额外元数据
• 可扩展性: 易于扩展的工厂模式，支持自定义小部件类型
• 向后兼容: 兼容旧版小部件类型，确保平滑迁移

安装

pip install gp-aw

快速开始

以下是一个简单的使用示例：

from gp_aw import WidgetType, infer_widget_type
import pathlib
from typing import Literal, List, Dict
from enum import Enum

# 基本类型推断
print(infer_widget_type(int))  # WidgetType.SPIN_INT
print(infer_widget_type(float))  # WidgetType.SPIN_FLOAT
print(infer_widget_type(bool))  # WidgetType.CHECKBOX
print(infer_widget_type(str))  # WidgetType.LINE_EDIT

# 枚举类型推断
class Color(Enum):
    RED = "red"
    GREEN = "green"
    BLUE = "blue"

print(infer_widget_type(Color))  # WidgetType.ENUM_COMBO

# 字面量类型推断
Status = Literal["active", "inactive", "pending"]
print(infer_widget_type(Status))  # WidgetType.LITERAL_COMBO

# 集合类型推断
print(infer_widget_type(List[str]))  # WidgetType.LIST_EDITOR
print(infer_widget_type(Dict[str, int]))  # WidgetType.DICT_EDITOR

# 路径类型推断
print(infer_widget_type(pathlib.Path))  # WidgetType.FILE_PATH

架构

核心组件

• WidgetType: 定义所有支持的小部件类型枚举
• infer_widget_type: 核心类型推断函数，根据类型信息推断UI小部件类型
• build_widget_schema: 构建完整的小部件schema（递归）
• extract_widget_metadata: 从类型信息中提取UI所需的额外元数据
• QtWidgetFactory: Qt小部件创建工厂，用于实例化实际的UI控件

扩展机制

框架提供了可扩展的工厂模式：

1. 类型推断扩展: 可以扩展infer_widget_type函数以支持新类型
2. 元数据提取扩展: 可以扩展extract_widget_metadata以提取新类型的元数据
3. 小部件工厂扩展: 可以使用QtWidgetFactory.register装饰器注册新的小部件创建函数

项目结构

gp-aw/
├── gp_aw/                 # 核心模块
│   ├── __init__.py       # 模块入口
│   ├── widget_type.py    # 小部件类型定义和推断逻辑
│   ├── factory.py        # Qt小部件工厂
│   └── editors/          # 各种编辑器组件
│       ├── __init__.py
│       ├── scalar.py     # 标量编辑器
│       ├── text.py       # 文本编辑器
│       ├── enum.py       # 枚举编辑器
│       ├── collection.py # 集合编辑器
│       ├── composite.py # 复合编辑器
│       └── path.py       # 路径编辑器
├── examples/             # 使用示例
└── README.md            # 项目说明

文档

完整的文档可在以下位置找到：

• 在线文档：https://gp-aw.readthedocs.io/ (如果配置了 Read the Docs)
• 本地构建：运行 pip install .[docs] 后，在 docs 目录执行 make html
• API 参考：自动生成的 API 文档包含在在线文档中

贡献

欢迎提交 Issue 和 Pull Request 来改进项目！

支持

如有问题，请在 GitHub 仓库中创建 Issue。