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

{ns_orm-0.0.0 → ns_orm-0.0.1}/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ns-orm
-Version: 0.0.0
+Version: 0.0.1
 Summary: A ORM built on Pydantic models.
 Author: ns-orm contributors
 License:                                  Apache License

ns_orm-0.0.1/doc/async.md

@@ -0,0 +1,40 @@
+# 异步用法
+
+## AsyncDatabase 与异步 CRUD
+
+```python
+from ns_orm import AsyncDatabase, acreate_all
+from ns_orm.dialects import dialect_from_url
+
+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).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.1/doc/database.md

@@ -0,0 +1,60 @@
+# 数据库与执行器（lesscode-database）
+
+## Database / AsyncDatabase
+
+ns-orm 不负责连接创建，外部（lesscode-database）需要提供执行器 executor。
+
+同步：
+
+```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.1/doc/index.md

@@ -0,0 +1,22 @@
+# 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 驱动（同步）或提供等价的异步驱动。

ns_orm-0.0.1/doc/migrations.md

@@ -0,0 +1,87 @@
+# 迁移命令（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 ns_orm import Database
+from ns_orm.dialects import dialect_from_url
+
+
+def get_db(dialect):
+    # 这里应使用 lesscode-database 创建执行器（示意）
+    # executor = lesscode_database.get_executor(...)
+    executor = ...
+    return Database(executor=executor, dialect=dialect)
+```
+
+执行迁移：
+
+```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.1/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.1/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 组合表达业务条件。

ns_orm-0.0.1/doc/relations.md

@@ -0,0 +1,92 @@
+# 关联与预取
+
+## ForeignKey / OneToOne
+
+定义外键字段：
+
+```python
+from typing import List, Optional
+
+from typing_extensions import Annotated
+from ns_orm import ForeignKey, Int, Model, String
+
+
+class User(Model):
+    id: Annotated[Optional[int], Int(primary_key=True)] = None
+    name: Annotated[str, String(max_length=50)]
+
+
+class Post(Model):
+    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)]
+```
+
+约定：
+
+- 外键列一般命名为 `xxx_id`
+- 预取关系名默认为 `xxx`（例如 `user_id` -> `user`）
+
+使用预取：
+
+```python
+posts = Post.objects.using(db).prefetch_related("user").all()
+print(posts[0].user.name)
+```
+
+`OneToOne` 与 `ForeignKey` 的区别在于默认 `unique=True`。
+
+## ManyToMany
+
+定义多对多字段：
+
+```python
+from typing import Optional
+
+from typing_extensions import Annotated
+from ns_orm import Int, ManyToMany, Model, String
+
+
+class Role(Model):
+    id: Annotated[Optional[int], Int(primary_key=True)] = None
+    name: Annotated[str, String(max_length=50)]
+
+
+class User(Model):
+    id: Annotated[Optional[int], Int(primary_key=True)] = None
+    name: Annotated[str, String(max_length=50)]
+    roles: Annotated[List[Role], ManyToMany("Role")]
+```
+
+中间表约定：
+
+- 默认表名：`{from_table}_{to_table}`
+- 默认列名：
+  - from 侧：`{from_table}_{from_pk}`
+  - to 侧：`{to_table}_{to_pk}`
+
+你也可以显式指定：
+
+```python
+roles: Annotated[
+    List[Role],
+    ManyToMany(
+        "Role",
+        through="user_role",
+        from_field="user_id",
+        to_field="role_id",
+    ),
+]
+```
+
+预取多对多：
+
+```python
+users = User.objects.using(db).prefetch_related("roles").all()
+print([r.name for r in users[0].roles])
+```
+
+说明：
+
+- 当前版本仅提供读取侧预取（prefetch），暂不提供 `add/remove/clear` 等写入 API
+- 中间表的建表由 `create_all/acreate_all` 自动创建（最小能力）

ns_orm-0.0.1/doc/release.md

@@ -0,0 +1,45 @@
+# 打包与发布
+
+本文档描述发布流程与相关文件约定。发布流程相关文件不参与打包发布（见仓库根目录的 `MANIFEST.in`）。
+
+## 1. 版本号
+
+在 `pyproject.toml` 中修改：
+
+- `[project].version`
+
+## 2. 构建产物
+
+推荐在干净环境中构建：
+
+```bash
+python -m pip install -U build twine
+python -m build
+```
+
+构建产物：
+
+- `dist/*.whl`
+- `dist/*.tar.gz`
+
+## 3. 校验
+
+```bash
+python -m twine check dist/*
+```
+
+## 4. 发布到 PyPI
+
+```bash
+python -m twine upload dist/*
+```
+
+## 5. 发布文件不参与打包
+
+当前通过 `MANIFEST.in` 排除以下目录/文件进入 sdist：
+
+- `doc/`
+- `tests/`
+- `.gitee/`
+
+wheel 包默认只包含 `src/` 下的 Python 包代码。

ns_orm-0.0.1/doc/schema.md

@@ -0,0 +1,32 @@
+# 建表（最小能力）
+
+ns-orm 提供最小可用的建表能力，便于本地开发、快速验证与测试。
+
+## create_all / acreate_all
+
+同步建表：
+
+```python
+from ns_orm import create_all
+
+create_all(db, [User, Post])
+```
+
+异步建表：
+
+```python
+from ns_orm import acreate_all
+
+await acreate_all(db, [User, Post])
+```
+
+行为：
+
+- 为每个模型生成 `CREATE TABLE IF NOT EXISTS ...`
+- 为 ManyToMany 关系生成中间表（表名/列名遵循默认约定，或按 ManyToMany 显式配置）
+
+## 当前限制
+
+- 不提供 schema 迁移（migrations）
+- 索引与复杂约束的自动生成尚未实现
+- 不同数据库的 DDL 差异较大，当前 DDL 以通用 SQL 为主，复杂类型与高级特性需自行扩展

{ns_orm-0.0.0 → ns_orm-0.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ns-orm"
-version = "0.0.0"
+version = "0.0.1"
 description = "A ORM built on Pydantic models."
 readme = "README.md"
 requires-python = ">=3.7"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ns-orm
-Version: 0.0.0
+Version: 0.0.1
 Summary: A ORM built on Pydantic models.
 Author: ns-orm contributors
 License:                                  Apache License

{ns_orm-0.0.0 → ns_orm-0.0.1}/src/ns_orm.egg-info/SOURCES.txt

@@ -2,6 +2,15 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
+doc/async.md
+doc/database.md
+doc/index.md
+doc/migrations.md
+doc/models.md
+doc/queryset.md
+doc/relations.md
+doc/release.md
+doc/schema.md
 src/ns_orm/__init__.py
 src/ns_orm/cli.py
 src/ns_orm/database.py