firefly-orm

firefly-orm 是 Firefly Python 的异步 ORM 公共包，基于 SQLAlchemy 2.x 提供数据库连接、 模型基类和常用 mixin。发布包名为 firefly-orm，导入根为 firefly.orm。

首期能力保持克制，重点对齐 Go gormx 的连接语义，并提供 Python 侧可维护的 ORM 基座：

• DatabaseConfig、PoolConfig、TLSConfig、SQLLogConfig：描述数据库、连接池、TLS 和 SQL 日志配置。
• build_async_database_url()：构造 MySQL / PostgreSQL 异步 SQLAlchemy URL，不创建网络连接。
• build_connect_args()：根据配置构造驱动连接参数，当前主要承载 TLS SSLContext。
• create_async_engine()、create_async_sessionmaker()：创建 SQLAlchemy 异步 engine 与 session 工厂。
• Base、TimeStampedMixin、TableMixin、TableUUIDMixin、TableNameMixin：提供通用模型基座。
• table_name()、new_uuid_v7()：提供表名约定与 UUIDv7 主键辅助能力。

本地开发

uv sync
uv run pytest
uv run ruff check src tests
uv run mypy
uv build --no-sources

使用示例

from firefly.orm import (
    Base,
    DatabaseConfig,
    DatabaseType,
    TableMixin,
    TableNameMixin,
    build_async_database_url,
    create_async_engine,
    create_async_sessionmaker,
)


class User(TableNameMixin, TableMixin, Base):
    pass


config = DatabaseConfig(
    type=DatabaseType.MYSQL,
    address="127.0.0.1:3306",
    database="firefly",
    username="firefly",
    password="secret",
)

url = build_async_database_url(config)
engine = create_async_engine(config)
Session = create_async_sessionmaker(engine)

边界说明

• 本包聚焦 ORM 基座、连接配置和模型基础能力，不在首期封装 Repository、迁移工具或业务查询 DSL。
• TableNameMixin 只是默认命名约定；生产模型需要精确控制表名时，应显式声明 __tablename__。
• MySQL 默认使用 mysql+asyncmy，PostgreSQL 默认使用 postgresql+asyncpg；其他数据库类型当前仅保留枚举占位。
• firefly 使用隐式 namespace package，包内不提供 src/firefly/__init__.py。