tee-orm 0.1.0

一个小巧的 Python ORM 框架，带有完整的类型系统支持

Tee

一个小巧的 Python ORM 框架，可以理解成带有类型系统的 Peewee。Tee 专注于提供简洁、类型安全的数据库操作体验。

✨ 特性

• 🎯 类型安全: 完整的类型提示支持，IDE 友好
• 🚀 简洁语法: 链式调用，直观易懂的 API 设计
• 🔧 轻量级: 最小化依赖，核心功能专注
• 🎪 灵活查询: 支持复杂条件查询和排序
• 🔄 事务支持: 内置事务管理
• 📊 多数据库: 支持多数据库连接配置

📦 安装

pip install tee-orm

🚀 快速开始

1. 配置数据库连接

from tee import set_default_db

# 配置默认数据库
set_default_db(
    host="localhost",
    port=3306,
    user="root",
    password="password",
    database="test_db"
)

2. 定义模型

from tee import Model, Int, Str, DateTime

class User(Model):
    id = Int()
    name = Str()
    email = Str()
    age = Int()
    created_at = DateTime()

class Post(Model):
    id = Int()
    title = Str()
    content = Str()
    user_id = Int()
    created_at = DateTime()

3. 查询操作

# 查询单条记录
user = User.select().eq(User.id, 1).get()
print(user.name)

# 查询多条记录
users = User.select().gt(User.age, 18).list()

# 条件查询
adult_users = (User.select()
               .gt(User.age, 18)
               .like(User.name, "张")
               .list())

# 排序和分页
users = (User.select()
         .desc(User.created_at)
         .limit(10)
         .offset(0)
         .list())

# 查询指定字段
users = User.select(["id", "name", "email"]).list()

# 安全的单条查询（不存在时返回 None）
user = User.select().eq(User.email, "[e-mail]").one()
if user:
    print(f"Found user: {user.name}")

4. 新增操作

# 单条插入
affected_rows = User.insert().execute({
    "name": "张三",
    "email": "[e-mail]", 
    "age": 25,
    "created_at": "2024-01-01 00:00:00"
})

# 使用模型对象插入
user = User(name="李四", email="[e-mail]", age=30)
User.insert().execute(user)

# 批量插入
users_data = [
    {"name": "王五", "email": "[e-mail]", "age": 28},
    {"name": "赵六", "email": "[e-mail]", "age": 32}
]
User.insert().execute_bulk(users_data)

# 插入时处理重复键
User.insert().execute(
    {"name": "张三", "email": "[e-mail]"}, 
    duplicate_key_update=["name"]  # 重复时更新 name 字段
)

5. 更新操作

# 条件更新
affected_rows = (User.update()
                 .eq(User.id, 1)
                 .set(name="新名字", age=26)
                 .execute())

# 批量更新
(User.update()
 .gt(User.age, 18)
 .set({"status": "adult"})
 .execute())

6. 删除操作

# 条件删除
affected_rows = (User.delete()
                 .eq(User.id, 1)
                 .execute())

# 批量删除
(User.delete()
 .lt(User.age, 18)
 .execute())

🔧 高级用法

事务管理

from tee import transaction

# 自动事务管理
with transaction():
    User.insert().execute({"name": "事务用户", "email": "[e-mail]"})
    Post.insert().execute({"title": "事务文章", "user_id": 1})
    # 如果发生异常，自动回滚

多数据库支持

from tee import set_db

# 配置多个数据库
set_db("analytics", 
       host="analytics-host", 
       port=3306,
       user="analytics_user", 
       password="password",
       database="analytics_db")

# 在特定数据库上执行操作
users = User.select().list()  # 使用默认数据库

复杂查询条件

from tee.where import Or

# OR 条件查询
or_condition = Or().eq(User.age, 25).eq(User.age, 30)
users = User.select().or_(or_condition).list()

# 多种操作符
users = (User.select()
         .ge(User.age, 18)        # 大于等于
         .le(User.age, 65)        # 小于等于
         .ne(User.status, "banned") # 不等于
         .in_(User.role, ["admin", "user"])  # IN 操作
         .like(User.name, "张")    # LIKE 搜索
         .list())

模型方法

# 转换为字典
user_dict = user.to_dict()

# 转换为 JSON
user_json = user.to_json()

# 获取表名（自动转换为 snake_case）
table_name = User.get_table_name()  # "user"

# 获取字段名列表
field_names = User.get_field_names()  # ["id", "name", "email", "age", "created_at"]

🎯 类型系统

Tee 提供完整的类型提示支持，让你的 IDE 能够提供准确的代码补全和类型检查：

from typing import Optional

# 查询返回带类型的对象
user: Optional[User] = User.select().eq(User.id, 1).one()
if user:
    # IDE 能够识别 user.name 的类型为 Optional[str]
    print(user.name.upper())  # 类型安全

# 列表查询返回类型化列表
users: List[User] = User.select().list()

📝 支持的字段类型

• Int() - 整数字段
• Str() - 字符串字段
• Float() - 浮点数字段
• DateTime() - 日期时间字段

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• PyMySQL - MySQL 数据库连接器
• Peewee - 灵感来源

---

Made with ❤️ by tian-gua