yut 0.2.24

轻量级 GUI 应用系统框架库，基于 (Qt)PySide 编写的通用表单、列表、统计组件以及 SqlAlchemy 扩展的数据库组件。利用 SQLAlchemy 反射机制构建数据集，前后端使用统一的数据字段定义，在业务级别动态决定数据项的输入和展示方式，并允许开发者进一步控制细节。后端生成的数据集封装为 Pandas Dataframe 传递给 GUI，作为 Model/View 机制的基础，并在此基础上实现通用统计功能，包括分组统计、交叉统计，绘制相应的统计图表。

YUT - 轻量级 GUI 应用系统框架库

YUT 是一个用于构建企业级 GUI 应用系统的轻量级框架库，可以实现基于数据库的两层架构应用系统。基于 PySide6 和 SQLAlchemy 构建，提供从前端界面到后端数据的完整解决方案。

✨ 特性亮点

🎨 前端 UI 组件（yui）

• 现代化界面：基于 PySide6，支持深色/浅色主题切换
• 导航框架：侧边栏导航、标签页管理、Logo 展示
• 通用表单：动态表单生成、数据验证、自定义字段类型
• 数据表格：支持排序、筛选、分页、自定义渲染
• 树形列表：层级数据展示、懒加载、图标定制
• 查找选择器：支持单选/多选、树形选择、自定义视图
• 统计图表：交叉统计、分组统计、可视化展示

💾 后端数据组件（yus）

• ORM 扩展：基于 SQLAlchemy 的增强封装
• 数据集管理：统一的查询接口和数据访问层
• 字段规范：丰富的数据类型定义（文本、金额、日期、百分比等）
• 查询操作符：完整的 CRUD 操作支持（=, >, <, LIKE, IN 等）
• 数据转换：DataFrame 与 JSON 的高效序列化/反序列化
• 业务逻辑层：支持复杂业务规则的实现

🔧 核心工具库（yut）

• 异步处理：线程池、任务队列、信号槽机制
• 数据工具：类型转换、格式化、安全计算
• JSON 处理：对象序列化、Base64 编码
• Windows 集成：进程模型 ID 设置、系统托盘

📦 安装

环境要求

• Python >= 3.12
• Windows 10/11（推荐）或 Linux/macOS

使用 Poetry 安装（推荐）

# 克隆仓库
git clone https://gitee.com/jy_tao/yut.git
cd yut

# 安装依赖
poetry install

# 激活虚拟环境
poetry shell

使用 pip 安装

pip install -r requirements.txt

主要依赖

• PySide6 ~= 6.9.0 - Qt6 Python 绑定
• SQLAlchemy ~= 2.0.41 - ORM 框架
• Pandas ~= 2.3.0 - 数据处理
• Jinja2 ~= 3.1.6 - 模板引擎
• Matplotlib ~= 3.9.0 - 图表绘制

🚀 快速开始

1. 创建基础应用

from yui import create_default_app, Theme
from PySide6.QtWidgets import QLabel, QVBoxLayout, QWidget

# 创建应用实例
app = create_default_app(theme=Theme.DARK, app_name='我的应用')

# 创建主窗口
window = QWidget()
window.setWindowTitle('Hello YUT')
layout = QVBoxLayout(window)
layout.addWidget(QLabel('欢迎使用 YUT 框架！'))
window.show()

# 启动事件循环
app.exec()

2. 使用数据组件

from yus import ColumnSpec, Op, UnitType
from yus.dbm import get_db, get_qm

# 初始化数据库环境
get_db().init_engine('sqlite:///mydb.db')

# 查询数据
df_org = get_qm().get_selection('DW_ORG').query(ORG_SCHEMA=1).dataframe()

# 带条件的查询
df_psn = get_qm().get_selection('DW_PSN').query(
    ORG_NO='ORG001',
    YEAR=2025,
    EMPL_STATE=(Op.NEQ, 3)  # 排除离职员工
).dataframe()

3. 创建数据表格组件

from yui.ytable import YTableWidget
from yui.ymodel import PandasModel
from yus import ColumnSpec, UnitType

# 定义列规格
column_specs = [
    ColumnSpec(name='EMP_NO', comment='员工编号', utype=UnitType.TEXT),
    ColumnSpec(name='EMP_NAME', comment='姓名', utype=UnitType.TEXT),
    ColumnSpec(name='SALARY', comment='工资', utype=UnitType.CURRENCY),
]

# 创建数据模型
model = PandasModel(dataframe, column_specs)

# 创建表格组件
table = YTableWidget(title='员工信息表', model=model)
table.show()

4. 使用查找选择器

from yui.ylookup import YLookup, YLookupDialog, YViewBuilder
from yus import UnitType

class OrgLookup(YLookup):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
    
    def create_dialog(self) -> YLookupDialog:
        return YLookupDialog(
            title='选择组织机构',
            view_type=YLookupViewType.Tree,
            view_builder=YViewBuilder(
                headers={'机构': '[{ORG_NO}] - {ORG_SHORT}',
                         '名称': '{ORG_NAME}'},
                loader=self.load_org_tree,
            ),
        )
    
    def load_org_tree(self, parent_org):
        # 加载树形数据
        return org_list

# 使用查找器
org_field = YFdCriteria(
    column_spec=ColumnSpec(name='ORG_NO', utype=UnitType.LOOKUP),
    lookup_key='my_module.OrgLookup'
)

📁 项目结构

yut-proj/
├── src/                        # 核心源代码
│   ├── yut/                    # 核心工具库
│   │   ├── __init__.py         # 基础工具函数
│   │   ├── asynx.py            # 异步处理和多线程
│   │   ├── mes.py              # 消息处理
│   │   ├── rmi.py              # 远程方法调用
│   │   └── win32.py            # Windows 系统集成
│   ├── yui/                    # GUI 组件库
│   │   ├── __init__.py         # UI 基础组件
│   │   ├── wdg.py              # 通用 Widget
│   │   ├── yfield.py           # 字段输入组件
│   │   ├── yform.py            # 表单组件
│   │   ├── ylookup.py          # 查找选择器
│   │   ├── ymodel.py           # 数据模型
│   │   ├── ytable.py           # 表格组件
│   │   ├── ytree.py            # 树形组件
│   │   └── images/             # 图标资源
│   └── yus/                    # 数据服务库
│       ├── __init__.py         # 数据规范定义
│       └── dbm.py              # 数据库管理
├── examples/                   # 示例代码
│   ├── yut_demo.py             # UI 框架演示
│   ├── yus_demo.py             # 数据组件演示
│   └── lazy_load.py            # 懒加载查询示例
├── example_package_yours/      # 完整应用示例
│   └── ndw/                    # NDW 业务系统
├── templates/                  # 代码模板
│   └── db_models.ptl           # 数据库模型模板
├── tests/                      # 测试用例
├── pyproject.toml              # Poetry 项目配置
├── requirements.txt            # pip 依赖列表
└── readme.md                   # 本文档

📖 使用场景

适用场景

✅ 企业内部管理系统（ERP、CRM、OA 等）
✅ 数据分析和报表系统
✅ 业务监控和仪表盘
✅ 快速原型开发
✅ 数据库管理工具

技术架构

┌─────────────────────────────────────┐
│         GUI 前端 (PySide6)          │
│  ┌───────┬───────┬───────┬───────┐  │
│  │ 主窗口 │ 导航  │ 表单  │ 表格  │  │
│  └───────┴───────┴───────┴───────┘  │
└─────────────────────────────────────┘
              ↕ JSON/Pandas
┌─────────────────────────────────────┐
│       业务逻辑层 (Python)            │
│  ┌───────┬───────┬───────┬───────┐  │
│  │查询器 │ 验证  │ 计算  │ 转换  │  │
│  └───────┴───────┴───────┴───────┘  │
└─────────────────────────────────────┘
              ↕ SQLAlchemy
┌─────────────────────────────────────┐
│         数据库层                     │
│  ┌───────┬───────┬───────┬───────┐  │
│  │SQLite │MySQL  │PG     │Oracle │  │
│  └───────┴───────┴───────┴───────┘  │
└─────────────────────────────────────┘

🔍 更多示例

详细示例请参考 examples/ 目录：

• yut_demo.py - UI 组件综合演示（主窗口、导航、表格、表单等）
• yus_demo.py - 数据查询和业务逻辑示例
• lazy_load.py - 大数据量懒加载查询优化

🛠️ 开发指南

运行测试

python -m pytest tests/

代码风格

• 遵循 PEP 8 规范
• 使用 UTF-8 编码
• 中文注释（业务逻辑部分）

📝 版本说明

当前版本使用 Git 标签自动管理，基于 setuptools-scm。

# 查看当前版本
poetry version

# 发布新版本
git tag v0.2.21
git push origin v0.2.21

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

📧 联系方式

• 作者: tjy
• 邮箱: [e-mail]
• 项目主页: https://gitee.com/jy_tao/yut

---

Happy Coding with YUT! 🚀