Metadata-Version: 2.4
Name: yut
Version: 0.2.24
Summary: 轻量级 GUI 应用系统框架库，基于 (Qt)PySide 编写的通用表单、列表、统计组件以及 SqlAlchemy 扩展的数据库组件。利用 SQLAlchemy 反射机制构建数据集，前后端使用统一的数据字段定义，在业务级别动态决定数据项的输入和展示方式，并允许开发者进一步控制细节。后端生成的数据集封装为 Pandas Dataframe 传递给 GUI，作为 Model/View 机制的基础，并在此基础上实现通用统计功能，包括分组统计、交叉统计，绘制相应的统计图表。
Author: tjy
Author-email: tjy@yeah.net
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Project-URL: Homepage, https://gitee.com/jy_tao/yut
Description-Content-Type: text/markdown

# 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 安装（推荐）
```bash
# 克隆仓库
git clone https://gitee.com/jy_tao/yut.git
cd yut

# 安装依赖
poetry install

# 激活虚拟环境
poetry shell
```

### 使用 pip 安装
```bash
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. 创建基础应用
```python
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. 使用数据组件
```python
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. 创建数据表格组件
```python
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. 使用查找选择器
```python
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** - 大数据量懒加载查询优化

## 🛠️ 开发指南

### 运行测试
```bash
python -m pytest tests/
```

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

## 📝 版本说明

当前版本使用 Git 标签自动管理，基于 [setuptools-scm](https://pypi.org/project/setuptools-scm/)。

```bash
# 查看当前版本
poetry version

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

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 📧 联系方式

- **作者**: tjy
- **邮箱**: tjy@yeah.net
- **项目主页**: https://gitee.com/jy_tao/yut

---

**Happy Coding with YUT! 🚀**

