ns-orm 0.0.0__tar.gz → 0.0.2__tar.gz

{ns_orm-0.0.0 → ns_orm-0.0.2}/MANIFEST.in

@@ -1,3 +1,3 @@
 recursive-exclude .gitee *
 recursive-exclude tests *
-recursive-exclude doc *
+recursive-include doc *.md

{ns_orm-0.0.0/src/ns_orm.egg-info → ns_orm-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: ns-orm
-Version: 0.0.0
+Version: 0.0.2
 Summary: A ORM built on Pydantic models.
 Author: ns-orm contributors
 License:                                  Apache License
@@ -210,12 +210,13 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic
 Requires-Dist: lesscode-database
-Requires-Dist: typing-extensions>=4.0
+Requires-Dist: typing-extensions
 Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
-Requires-Dist: ruff>=0.5; extra == "dev"
-Dynamic: license-file
+Requires-Dist: pytest<8,>=7; python_version < "3.8" and extra == "dev"
+Requires-Dist: pytest>=8; python_version >= "3.8" and extra == "dev"
+Requires-Dist: pytest-asyncio<0.21.2,>=0.20; python_version < "3.8" and extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; python_version >= "3.8" and extra == "dev"
+Requires-Dist: ruff>=0.5; python_version >= "3.8" and extra == "dev"
 
 # ns-orm
 
@@ -240,44 +241,82 @@ from typing import Optional
 
 from typing_extensions import Annotated
 
-from ns_orm import Database, ForeignKey, Int, Model, String, create_all
-from ns_orm.dialects import dialect_from_url
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import ForeignKey, Int, Model, String, create_all, get_connection
 
 
 class User(Model):
+    class Meta:
+        connect_name = "default"
+
     id: Annotated[Optional[int], Int(primary_key=True)] = None
     name: Annotated[str, String(max_length=50)]
 
 
 class Post(Model):
+    class Meta:
+        connect_name = "default"
+
     id: Annotated[Optional[int], Int(primary_key=True)] = None
     user_id: Annotated[int, ForeignKey("User", on_delete="CASCADE")]
     title: Annotated[str, String(max_length=200)]
 
 
-executor = ...  # 由 lesscode-database 创建
-db = Database(executor=executor, dialect=dialect_from_url("sqlite"))
+db_options.conn_list = [
+    ConnectionInfo(dialect="sqlite3", name="default", dsn="test.db", async_enable=False),
+]
+
+db = get_connection("default")
 create_all(db, [User, Post])
 
-u = User.objects.using(db).create(name="alice")
-Post.objects.using(db).create(user_id=u.id, title="hello")
+u = User.objects.create(name="alice")
+Post.objects.create(user_id=u.id, title="hello")
 
-posts = Post.objects.using(db).prefetch_related("user").all()
+posts = Post.objects.prefetch_related("user").all()
 print(posts[0].user.name)
+
+connect, _connect_info = getattr(db_options, "default")
+if not hasattr(connect, "cursor") and hasattr(connect, "connection"):
+    connect = connect.connection()
+
+qs = User.objects.filter(id=u.id)
+sql, params = qs._select_sql()
+prepared = db.dialect.prepare(sql, params)
+cursor = connect.cursor()
+cursor.execute(prepared.sql, prepared.params)
+row = cursor.fetchone()
+print(row)
 ```
 
 ## 快速开始（异步）
 
 ```python
-from ns_orm import AsyncDatabase, acreate_all
-from ns_orm.dialects import dialect_from_url
+import asyncio
+
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import acreate_all, get_connection
+
+
+async def main():
+    db_options.conn_list = [
+        ConnectionInfo(dialect="sqlite3", name="default_async", dsn="test_async.db", async_enable=True),
+    ]
+
+    db = get_connection("default_async")
+    await acreate_all(db, [User, Post])
+
+    u = await User.objects.using("default_async").acreate(name="alice")
+    posts = await (
+        Post.objects.using("default_async").filter(user_id=u.id).prefetch_related("user").all()
+    )
+    print(posts[0].user.name)
 
-executor = ...  # 由 lesscode-database 创建（异步执行器）
-db = AsyncDatabase(executor=executor, dialect=dialect_from_url("sqlite"))
-await acreate_all(db, [User, Post])
 
-u = await User.objects.using(db).acreate(name="alice")
-posts = await Post.objects.using(db).filter(user_id=u.id).prefetch_related("user").all()
+asyncio.run(main())
 ```
 
 ## 迁移命令

ns_orm-0.0.2/README.md

@@ -0,0 +1,108 @@
+# ns-orm
+
+一个参考 Django ORM 设计的轻量级 ORM（不依赖 SQLAlchemy），以 Pydantic 作为模型层，支持同步/异步、CRUD、关联预取与最小建表能力。
+
+数据库连接/连接池由 lesscode-database 负责，ns-orm 仅消费“执行器”来执行 SQL。
+
+更多功能与完整用法见 [doc/index.md](doc/index.md)。
+
+## 安装
+
+```bash
+pip install ns-orm
+```
+
+数据库驱动与连接方式由 lesscode-database 决定。
+
+## 快速开始（同步）
+
+```python
+from typing import Optional
+
+from typing_extensions import Annotated
+
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import ForeignKey, Int, Model, String, create_all, get_connection
+
+
+class User(Model):
+    class Meta:
+        connect_name = "default"
+
+    id: Annotated[Optional[int], Int(primary_key=True)] = None
+    name: Annotated[str, String(max_length=50)]
+
+
+class Post(Model):
+    class Meta:
+        connect_name = "default"
+
+    id: Annotated[Optional[int], Int(primary_key=True)] = None
+    user_id: Annotated[int, ForeignKey("User", on_delete="CASCADE")]
+    title: Annotated[str, String(max_length=200)]
+
+
+db_options.conn_list = [
+    ConnectionInfo(dialect="sqlite3", name="default", dsn="test.db", async_enable=False),
+]
+
+db = get_connection("default")
+create_all(db, [User, Post])
+
+u = User.objects.create(name="alice")
+Post.objects.create(user_id=u.id, title="hello")
+
+posts = Post.objects.prefetch_related("user").all()
+print(posts[0].user.name)
+
+connect, _connect_info = getattr(db_options, "default")
+if not hasattr(connect, "cursor") and hasattr(connect, "connection"):
+    connect = connect.connection()
+
+qs = User.objects.filter(id=u.id)
+sql, params = qs._select_sql()
+prepared = db.dialect.prepare(sql, params)
+cursor = connect.cursor()
+cursor.execute(prepared.sql, prepared.params)
+row = cursor.fetchone()
+print(row)
+```
+
+## 快速开始（异步）
+
+```python
+import asyncio
+
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import acreate_all, get_connection
+
+
+async def main():
+    db_options.conn_list = [
+        ConnectionInfo(dialect="sqlite3", name="default_async", dsn="test_async.db", async_enable=True),
+    ]
+
+    db = get_connection("default_async")
+    await acreate_all(db, [User, Post])
+
+    u = await User.objects.using("default_async").acreate(name="alice")
+    posts = await (
+        Post.objects.using("default_async").filter(user_id=u.id).prefetch_related("user").all()
+    )
+    print(posts[0].user.name)
+
+
+asyncio.run(main())
+```
+
+## 迁移命令
+
+见 [doc/migrations.md](doc/migrations.md)。
+
+## 打包与发布
+
+见 [doc/release.md](doc/release.md)。

ns_orm-0.0.2/doc/async.md

@@ -0,0 +1,45 @@
+# 异步用法
+
+## AsyncDatabase 与异步 CRUD
+
+```python
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import acreate_all, get_connection
+
+db_options.conn_list = [
+    ConnectionInfo(dialect="sqlite3", name="default_async", dsn="test_async.db", async_enable=True),
+]
+
+db = get_connection("default_async")
+await acreate_all(db, [User, Post])
+
+u = await User.objects.using("default_async").acreate(name="alice")
+posts = await Post.objects.using("default_async").filter(user_id=u.id).all()
+```
+
+## 异步 QuerySet
+
+当你通过 `Model.objects.using(async_db)` 绑定到 `AsyncDatabase` 后，使用以下方法：
+
+- `acreate(...)`
+- `aget(...)`
+- `aall()`
+
+QuerySet 本身的执行方法在异步模式下仍为协程：
+
+```python
+posts = await Post.objects.using(db).filter(title__contains="o").all()
+```
+
+## 事务
+
+```python
+async with db.transaction():
+    await User.objects.using(db).acreate(name="alice")
+```
+
+## 注意事项
+
+- 执行器实现由 lesscode-database 决定；ns-orm 仅做 SQL 生成与参数风格转换

ns_orm-0.0.2/doc/database.md

@@ -0,0 +1,126 @@
+# 数据库与执行器（lesscode-database）
+
+## 与 db_options 集成（connect_name）
+
+ns-orm 默认会从 `lesscode_database.db_options.db_options` 读取连接：
+
+- `connect, connect_info = getattr(db_options, connect_name)`
+- `connect_info.dialect` 用于选择 ns-orm dialect
+
+示例（SQLite）：
+
+```python
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import create_all, get_connection
+
+db_options.conn_list = [
+    ConnectionInfo(dialect="sqlite3", name="default", dsn="test.db", async_enable=False),
+]
+
+db = get_connection("default")
+create_all(db, [User, Post])
+```
+
+说明：
+
+- `sqlite3` 连接池在 lesscode-database 中依赖 `DBUtils`（未安装会报错）
+- 异步 `sqlite3` 连接依赖 `aiosqlite3`（未安装会报错）
+- 某些情况下 `connect` 可能是连接池对象而不是 DB-API 连接；如果你需要直接 `cursor()`，可使用 `connect.connection()` 获取真实连接
+
+使用 `connect.cursor()` 执行 ORM 生成的 SQL：
+
+```python
+connect_name = "default"
+connect, _connect_info = getattr(db_options, connect_name)
+if not hasattr(connect, "cursor") and hasattr(connect, "connection"):
+    connect = connect.connection()
+
+qs = User.objects.filter(id=1)
+sql, params = qs._select_sql()
+prepared = db.dialect.prepare(sql, params)
+
+cursor = connect.cursor()
+cursor.execute(prepared.sql, prepared.params)
+row = cursor.fetchone()
+print(row)
+```
+
+示例（SQLite 异步）：
+
+```python
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import acreate_all, get_connection
+
+db_options.conn_list = [
+    ConnectionInfo(dialect="sqlite3", name="default_async", dsn="test_async.db", async_enable=True),
+]
+
+db = get_connection("default_async")
+await acreate_all(db, [User, Post])
+
+u = await User.objects.using("default_async").acreate(name="alice")
+posts = await Post.objects.using("default_async").filter(user_id=u.id).prefetch_related("user").all()
+```
+
+## Database / AsyncDatabase（自定义 executor）
+
+当你希望绕开 `db_options`（例如在框架外自行管理连接/执行器）时，也可以直接构造：
+
+同步：
+
+```python
+from ns_orm import Database
+from ns_orm.dialects import dialect_from_url
+
+executor = ...  # 由 lesscode-database 创建
+db = Database(executor=executor, dialect=dialect_from_url("sqlite"))
+```
+
+异步：
+
+```python
+from ns_orm import AsyncDatabase
+from ns_orm.dialects import dialect_from_url
+
+executor = ...  # 由 lesscode-database 创建（异步执行器）
+db = AsyncDatabase(executor=executor, dialect=dialect_from_url("postgresql"))
+```
+
+## 事务
+
+同步：
+
+```python
+with db.transaction():
+    User.objects.using(db).create(name="alice")
+```
+
+异步：
+
+```python
+async with db.transaction():
+    await User.objects.using(db).acreate(name="alice")
+```
+
+## 方言（dialect）
+
+当前方言用于：
+
+- 标识符引用（引号）
+- DDL 类型映射
+- 参数风格转换（`:name` -> driver paramstyle）
+
+常用值（可直接使用 URL scheme 的前缀）：
+
+- `sqlite`
+- `clickhouse`
+- `postgres` / `postgresql`
+- `mysql`（也可传 `mariadb` / `tidb`）
+- `mssql` / `sqlserver`
+- `oracle`
+
+驱动安装与连接配置请参考 lesscode-database。

ns_orm-0.0.2/doc/index.md

@@ -0,0 +1,35 @@
+# ns-orm 文档
+
+## 目录
+
+- [模型与字段](models.md)
+- [查询与 CRUD](queryset.md)
+- [关联与预取](relations.md)
+- [数据库与 URL](database.md)
+- [建表（最小能力）](schema.md)
+- [异步用法](async.md)
+- [迁移命令（makemigrations/migrate）](migrations.md)
+- [打包与发布](release.md)
+
+## 设计概览
+
+ns-orm 的目标是提供接近 Django ORM 的开发体验：
+
+- 以 Pydantic 模型作为领域对象（数据校验、序列化、赋值校验）
+- 以 QuerySet 作为查询构造器（链式调用、延迟执行的 SQL 构造）
+- 以 Database/AsyncDatabase 作为数据库适配层（不同驱动、参数风格转换）
+
+如果你需要在框架未内置的数据库上使用，请优先选择该数据库的 DB-API 2.0 驱动（同步）或提供等价的异步驱动。
+
+## 开发与测试
+
+安装开发依赖：
+
+```bash
+pip install -e ".[dev]"
+```
+
+说明：
+
+- Python 3.7：`pytest<8`、较老版本的 `pytest-asyncio`，不安装 ruff
+- Python >=3.8：`pytest>=8`、`pytest-asyncio>=0.23`、`ruff>=0.5`

ns_orm-0.0.2/doc/migrations.md

@@ -0,0 +1,90 @@
+# 迁移命令（makemigrations / migrate）
+
+ns-orm 提供类似 Django 的迁移能力：
+
+- `makemigrations`：对比“上一次迁移快照”和当前 Model 定义，生成新的迁移文件
+- `migrate`：执行迁移文件中的 SQL，并记录已应用迁移
+
+## 前置：数据库连接由 lesscode-database 提供
+
+ns-orm 不负责创建连接/连接池。你需要在自己的项目中使用 `lesscode-database` 创建执行器，并包装为 `ns_orm.Database` 或 `ns_orm.AsyncDatabase`。
+
+迁移命令通过 `--db-factory` 调用你提供的工厂函数来获得 Database 对象。
+
+## 1) makemigrations
+
+```bash
+ns-orm makemigrations \
+  --models app.models \
+  --dialect postgresql \
+  --name add_user_email \
+  --migrations-dir ./migrations
+```
+
+参数说明：
+
+- `--models`：包含 Model 定义的模块路径（逗号分隔）
+- `--dialect`：方言（或 URL scheme），例如 `postgresql` / `mysql` / `sqlite`
+- `--name`：迁移名称后缀
+- `--migrations-dir`：迁移文件目录（默认 `./migrations`）
+
+输出：生成 `YYYYMMDDhhmmss_xxx.py` 迁移文件。
+
+## 2) migrate
+
+你需要提供 `db_factory(dialect)`：
+
+```python
+# project/db.py
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
+
+from ns_orm import get_connection
+
+
+def get_db(dialect):
+    _ = dialect
+    db_options.conn_list = [
+        ConnectionInfo(dialect="sqlite3", name="default", dsn="test.db", async_enable=False),
+    ]
+    return get_connection("default")
+```
+
+执行迁移：
+
+```bash
+ns-orm migrate \
+  --models app.models \
+  --dialect postgresql \
+  --db-factory project.db:get_db \
+  --migrations-dir ./migrations
+```
+
+只看计划（不执行）：
+
+```bash
+ns-orm migrate \
+  --models app.models \
+  --dialect postgresql \
+  --db-factory project.db:get_db \
+  --migrations-dir ./migrations \
+  --plan
+```
+
+异步执行（要求 `db_factory` 返回 `ns_orm.AsyncDatabase`）：
+
+```bash
+ns-orm migrate \
+  --models app.models \
+  --dialect postgresql \
+  --db-factory project.db:get_async_db \
+  --migrations-dir ./migrations \
+  --async
+```
+
+## 当前支持范围与限制
+
+- 支持：CreateTable、AddColumn、DropColumn（SQLite 的 DropColumn 不支持）
+- 暂不支持：字段类型变更、重命名、索引/约束的自动迁移（可扩展 operations）
+
+已应用迁移记录在数据库表 `ns_orm_migrations` 中。

ns_orm-0.0.2/doc/models.md

@@ -0,0 +1,70 @@
+# 模型与字段
+
+## 定义模型
+
+ns-orm 的模型继承自 `ns_orm.Model`，字段通过 `typing_extensions.Annotated` 绑定字段元数据：
+
+```python
+from typing import Optional
+
+from typing_extensions import Annotated
+from ns_orm import Int, Model, String
+
+
+class User(Model):
+    id: Annotated[Optional[int], Int(primary_key=True)] = None
+    name: Annotated[str, String(max_length=50)]
+```
+
+说明：
+
+- 类型注解用于 Pydantic 校验与序列化
+- `Annotated[..., FieldDef]` 中的 `FieldDef` 用于 ORM 元信息（列类型、主键、是否为空等）
+
+## 字段类型
+
+内置字段定义见 `ns_orm.fields`：
+
+- 数值：`TinyInt`、`SmallInt`、`Int`、`BigInt`、`UTinyInt`、`USmallInt`、`UInt`、`UBigInt`、`Float`、`Real`、`Double`、`Decimal`
+- 字符串：`Char(length=...)`、`String(max_length=...)`、`Text`、`FixedString(length=...)`
+- 时间：`Date`、`DateTime`
+- 其他：`Boolean`、`Binary`、`JSON`、`UUID`、`IPv4`、`IPv6`
+- ClickHouse 复合类型：`Array(item=...)`、`Map(key=..., value=...)`、`TupleType(items=[...])`、`Nullable(inner=...)`、`LowCardinality(inner=...)`、`Date32`、`DateTime64`
+
+通用字段选项：
+
+- `primary_key`：主键
+- `nullable`：是否可空（默认由数据库决定；建议显式设置）
+- `unique`：唯一约束（列级）
+- `index`：索引标记（当前仅保留元信息，不自动建索引）
+- `default`/`server_default`：默认值（当前用于模型侧与 DDL 侧的最小表达）
+
+## 模型元信息（Meta）
+
+可通过内部类 `Meta` 指定表名与 schema：
+
+```python
+class User(Model):
+    class Meta:
+        table_name = "app_user"
+        schema = "public"
+
+    id: Annotated[Optional[int], Int(primary_key=True)] = None
+    name: Annotated[str, String(max_length=50)]
+```
+
+默认表名为类名的 snake_case（例如 `BlogPost` -> `blog_post`）。
+
+## 主键约定
+
+- 如果字段中存在 `primary_key=True`，将使用该字段作为主键
+- 否则如果存在 `id` 字段，将使用 `id` 作为主键
+
+## 模型序列化
+
+模型仍然是 Pydantic 模型：
+
+```python
+u = User(id=1, name="alice")
+payload = u.model_dump()
+```

ns_orm-0.0.2/doc/queryset.md

@@ -0,0 +1,69 @@
+# 查询与 CRUD
+
+## 基本用法
+
+获取 Manager：
+
+```python
+m = User.objects.using(db)
+```
+
+获取 QuerySet：
+
+```python
+qs = User.objects.using(db).qs()
+```
+
+常用方法：
+
+- `all()`：返回列表
+- `first()`：返回首个或 None
+- `get(**lookups)`：返回单个对象，不存在抛 `DoesNotExist`，多条抛 `MultipleObjectsReturned`
+- `create(**data)`：插入并返回实例
+- `update(**data)`：批量更新，返回影响行数
+- `delete()`：批量删除，返回影响行数
+
+示例：
+
+```python
+u = User.objects.using(db).create(name="alice")
+u2 = User.objects.using(db).get(id=u.id)
+User.objects.using(db).filter(id=u.id).update(name="bob")
+User.objects.using(db).filter(id=u.id).delete()
+```
+
+## 链式查询
+
+```python
+users = (
+    User.objects.using(db)
+    .filter(name__icontains="al")
+    .order_by("-id")
+    .limit(10)
+    .offset(0)
+    .all()
+)
+```
+
+## lookups
+
+`filter/exclude` 支持 Django 风格的 `field__lookup=value`：
+
+- 精确：`field=value` 或 `field__exact=value`
+- 比较：`__gt` `__gte` `__lt` `__lte`
+- 集合：`__in=[...]`
+- 字符串匹配：`__contains` `__icontains` `__startswith` `__istartswith` `__endswith` `__iendswith`
+- 空值：`__isnull=True/False`
+
+示例：
+
+```python
+User.objects.using(db).filter(id__in=[1, 2, 3]).all()
+User.objects.using(db).exclude(name__startswith="test").all()
+```
+
+## Q 表达式
+
+`ns_orm.Q` 提供了 AND/OR/NOT 的条件树抽象，当前版本主要用于内部组合条件。
+
+当前 QuerySet API 暂不提供 `filter(Q(...))` 入口；日常查询建议使用 `filter/exclude` 的 lookups 组合表达业务条件。