dclassql 0.1.0__tar.gz

dclassql-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.3
+Name: dclassql
+Version: 0.1.0
+Summary: Add your description here
+Author: myuanz
+Author-email: myuanz <provefars@gmail.com>
+Requires-Dist: pypika>=0.48.9
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# DataclassQL
+
+DataclassQL 是一个基于 **平凡 dataclass 定义** 的 ORM 生成器, 可生成类型提示完整精巧的数据库客户端. 
+
+模型文件保持干净、直观, 无需起手加一堆导入, 也没有 `mapped_column()`、`Annotation` 或额外的基类继承, 只需要 `dataclass`
+
+---
+
+## 设计目标
+
+* **最小语法负担**: 模型定义就是合法平凡的 Python dataclass, Python 即 DSL
+* **常用路径简洁**: 常用的定义只需要写少量的代码
+* **静态类型安全**: 模型定义和生成代码全都类型安全. 本库作为 [prisma client python](https://prisma-client-py.readthedocs.io/en/stable/) 的精神继承者, 致力于完成如下体验: 
+
+![](https://prisma-client-py.readthedocs.io/en/stable/showcase.gif)
+
+---
+
+## 示例
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+    last_login: datetime
+
+    def index(self):
+        yield self.name
+        yield self.last_login
+
+    def unique_index(self):
+        yield self.name, self.email
+```
+
+写出如下代码时: 
+
+```python
+from dclassql import client
+
+client.user.insert({
+    "name": "Alice",
+    "email": "test@example.com",
+})
+```
+
+将在类型空间得到报错: 
+
+```
+error: Argument of type "dict[str, str]" cannot be assigned to parameter "data" of type "UserInsertDict" in function "insert"
+    "last_login" is required in "UserInsertDict" (reportArgumentType)
+```
+
+
+## 安装
+
+```
+uv add dclassql
+```
+
+## 当前状态
+
+DataclassQL 仍在早期开发阶段, 已完成代码生成和 SQLite 支持, 后续将扩展更多数据库与查询功能. 
+
+## 一份更长的例子
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+__datasource__ = {
+    "provider": "sqlite",
+    "url": "sqlite:///test.db",
+}
+
+
+@dataclass
+class Address:
+    id: int
+    location: str
+    user_id: int
+    user: 'User'
+
+    def foreign_key(self):
+        yield self.user.id == self.user_id, User.addresses
+
+
+@dataclass
+class BirthDay:
+    user_id: int
+    user: 'User'
+    date: datetime
+
+    def primary_key(self):
+        return self.user_id
+
+    def foreign_key(self):
+        yield self.user.id == self.user_id, User.birthday
+
+
+@dataclass
+class Book:
+    id: int
+    name: str
+    users: list['UserBook']
+
+    def index(self):
+        return self.name
+
+
+@dataclass
+class UserBook:
+    user_id: int
+    book_id: int
+    user: 'User'
+    book: Book
+    created_at: datetime
+
+    def primary_key(self):
+        return (self.user_id, self.book_id)
+
+    def index(self):
+        yield self.created_at
+
+    def foreign_key(self):
+        yield self.user.id == self.user_id, User.books
+        yield self.book.id == self.book_id, Book.users
+
+
+@dataclass
+class User:
+    id: int | None
+    name: str
+    email: str
+    last_login: datetime
+    birthday: BirthDay | None
+    addresses: list[Address]
+    books: list[UserBook]
+
+    def index(self):
+        yield self.name
+        yield self.name, self.email
+        yield self.last_login
+
+    def unique_index(self):
+        yield self.name, self.email
+
+```
+
+生成的代码请见: https://github.com/myuanz/dataclassql/blob/master/tests/results.py

dclassql-0.1.0/README.md

@@ -0,0 +1,154 @@
+# DataclassQL
+
+DataclassQL 是一个基于 **平凡 dataclass 定义** 的 ORM 生成器, 可生成类型提示完整精巧的数据库客户端. 
+
+模型文件保持干净、直观, 无需起手加一堆导入, 也没有 `mapped_column()`、`Annotation` 或额外的基类继承, 只需要 `dataclass`
+
+---
+
+## 设计目标
+
+* **最小语法负担**: 模型定义就是合法平凡的 Python dataclass, Python 即 DSL
+* **常用路径简洁**: 常用的定义只需要写少量的代码
+* **静态类型安全**: 模型定义和生成代码全都类型安全. 本库作为 [prisma client python](https://prisma-client-py.readthedocs.io/en/stable/) 的精神继承者, 致力于完成如下体验: 
+
+![](https://prisma-client-py.readthedocs.io/en/stable/showcase.gif)
+
+---
+
+## 示例
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+    last_login: datetime
+
+    def index(self):
+        yield self.name
+        yield self.last_login
+
+    def unique_index(self):
+        yield self.name, self.email
+```
+
+写出如下代码时: 
+
+```python
+from dclassql import client
+
+client.user.insert({
+    "name": "Alice",
+    "email": "test@example.com",
+})
+```
+
+将在类型空间得到报错: 
+
+```
+error: Argument of type "dict[str, str]" cannot be assigned to parameter "data" of type "UserInsertDict" in function "insert"
+    "last_login" is required in "UserInsertDict" (reportArgumentType)
+```
+
+
+## 安装
+
+```
+uv add dclassql
+```
+
+## 当前状态
+
+DataclassQL 仍在早期开发阶段, 已完成代码生成和 SQLite 支持, 后续将扩展更多数据库与查询功能. 
+
+## 一份更长的例子
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+__datasource__ = {
+    "provider": "sqlite",
+    "url": "sqlite:///test.db",
+}
+
+
+@dataclass
+class Address:
+    id: int
+    location: str
+    user_id: int
+    user: 'User'
+
+    def foreign_key(self):
+        yield self.user.id == self.user_id, User.addresses
+
+
+@dataclass
+class BirthDay:
+    user_id: int
+    user: 'User'
+    date: datetime
+
+    def primary_key(self):
+        return self.user_id
+
+    def foreign_key(self):
+        yield self.user.id == self.user_id, User.birthday
+
+
+@dataclass
+class Book:
+    id: int
+    name: str
+    users: list['UserBook']
+
+    def index(self):
+        return self.name
+
+
+@dataclass
+class UserBook:
+    user_id: int
+    book_id: int
+    user: 'User'
+    book: Book
+    created_at: datetime
+
+    def primary_key(self):
+        return (self.user_id, self.book_id)
+
+    def index(self):
+        yield self.created_at
+
+    def foreign_key(self):
+        yield self.user.id == self.user_id, User.books
+        yield self.book.id == self.book_id, Book.users
+
+
+@dataclass
+class User:
+    id: int | None
+    name: str
+    email: str
+    last_login: datetime
+    birthday: BirthDay | None
+    addresses: list[Address]
+    books: list[UserBook]
+
+    def index(self):
+        yield self.name
+        yield self.name, self.email
+        yield self.last_login
+
+    def unique_index(self):
+        yield self.name, self.email
+
+```
+
+生成的代码请见: https://github.com/myuanz/dataclassql/blob/master/tests/results.py

dclassql-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "dclassql"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "myuanz", email = "provefars@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pypika>=0.48.9",
+]
+
+[project.scripts]
+"dql" = "dclassql.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.22,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.407",
+    "pytest>=8.4.2",
+]

dclassql-0.1.0/src/dclassql/__init__.py

@@ -0,0 +1,12 @@
+from .db_pool import BaseDBPool, save_local
+from .push import db_push
+from .unwarp import unwarp, unwarp_or, unwarp_or_raise
+
+__all__ = [
+    'db_push',
+    'unwarp',
+    'unwarp_or',
+    'unwarp_or_raise',
+    'BaseDBPool',
+    'save_local',
+]

dclassql-0.1.0/src/dclassql/cli.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Sequence
+
+from .codegen import generate_client
+from .push import db_push
+from .runtime.datasource import open_sqlite_connection, resolve_sqlite_path
+
+
+DEFAULT_MODEL_FILE = "model.py"
+
+
+def load_module(module_path: Path) -> ModuleType:
+    module_path = module_path.resolve()
+    if not module_path.exists():
+        raise FileNotFoundError(f"Model file '{module_path}' does not exist")
+    module_name = module_path.stem
+    spec = importlib.util.spec_from_file_location(module_name, module_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Unable to load module from '{module_path}'")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    sys.path.insert(0, str(module_path.parent))
+    try:
+        spec.loader.exec_module(module)
+    finally:
+        sys.path.pop(0)
+    return module
+
+
+def collect_models(module: ModuleType) -> list[type[Any]]:
+    from dataclasses import is_dataclass
+
+    models: list[type[Any]] = []
+    for value in vars(module).values():
+        if isinstance(value, type) and is_dataclass(value) and value.__module__ == module.__name__:
+            models.append(value)
+    if not models:
+        raise ValueError("No dataclass models were found in the provided module")
+    return models
+
+
+def push_database(models: Sequence[type[Any]]) -> None:
+    from .model_inspector import inspect_models
+
+    model_infos = inspect_models(models)
+    connections: dict[str, Any] = {}
+    opened: list[Any] = []
+    try:
+        for info in model_infos.values():
+            config = info.datasource
+            key = config.key
+            if key in connections:
+                continue
+            if config.provider != "sqlite":
+                raise ValueError(f"Unsupported provider '{config.provider}'")
+            connection = open_sqlite_connection(config.url)
+            connections[key] = connection
+            opened.append(connection)
+        db_push(models, connections)
+    finally:
+        for conn in opened:
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+
+def command_generate(module_path: Path) -> None:
+    module = load_module(module_path)
+    models = collect_models(module)
+    generated = generate_client(models)
+    sys.stdout.write(generated.code)
+
+
+def command_push_db(module_path: Path) -> None:
+    module = load_module(module_path)
+    models = collect_models(module)
+    push_database(models)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="typed-db", description="Typed DB utilities.")
+    parser.add_argument(
+        "-m",
+        "--module",
+        type=Path,
+        default=Path(DEFAULT_MODEL_FILE),
+        help="Path to the model module file (default: model.py)",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    generate_parser = subparsers.add_parser("generate", help="Generate client code for given models")
+    generate_parser.set_defaults(handler=lambda args: command_generate(args.module))
+
+    push_parser = subparsers.add_parser("push-db", help="Apply schema and indexes to configured databases")
+    push_parser.set_defaults(handler=lambda args: command_push_db(args.module))
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help()
+        return 1
+    try:
+        handler(args)
+        return 0
+    except Exception as exc:  # pragma: no cover - CLI error reporting
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())