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

{ns_orm-0.0.1/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.1
+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.1 → ns_orm-0.0.2}/doc/async.md

@@ -3,15 +3,20 @@
 ## AsyncDatabase 与异步 CRUD
 
 ```python
-from ns_orm import AsyncDatabase, acreate_all
-from ns_orm.dialects import dialect_from_url
+from lesscode_database.connection_info import ConnectionInfo
+from lesscode_database.db_options import db_options
 
-executor = ...  # 由 lesscode-database 创建（异步执行器）
-db = AsyncDatabase(executor=executor, dialect=dialect_from_url("sqlite"))
+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(db).acreate(name="alice")
-posts = await Post.objects.using(db).filter(user_id=u.id).all()
+u = await User.objects.using("default_async").acreate(name="alice")
+posts = await Post.objects.using("default_async").filter(user_id=u.id).all()
 ```
 
 ## 异步 QuerySet

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.1 → ns_orm-0.0.2}/doc/index.md

@@ -20,3 +20,16 @@ ns-orm 的目标是提供接近 Django ORM 的开发体验：
 - 以 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.1 → ns_orm-0.0.2}/doc/migrations.md

@@ -36,15 +36,18 @@ ns-orm makemigrations \
 
 ```python
 # project/db.py
-from ns_orm import Database
-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 get_connection
 
 
 def get_db(dialect):
-    # 这里应使用 lesscode-database 创建执行器（示意）
-    # executor = lesscode_database.get_executor(...)
-    executor = ...
-    return Database(executor=executor, dialect=dialect)
+    _ = dialect
+    db_options.conn_list = [
+        ConnectionInfo(dialect="sqlite3", name="default", dsn="test.db", async_enable=False),
+    ]
+    return get_connection("default")
 ```
 
 执行迁移：

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ns-orm"
-version = "0.0.1"
+version = "0.0.2"
 description = "A ORM built on Pydantic models."
 readme = "README.md"
 requires-python = ">=3.7"
@@ -13,11 +13,17 @@ authors = [{ name = "ns-orm contributors" }]
 dependencies = [
   "pydantic",
   "lesscode-database",
-  "typing-extensions>=4.0",
+  "typing-extensions",
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.5"]
+dev = [
+  "pytest>=7,<8; python_version<'3.8'",
+  "pytest>=8; python_version>='3.8'",
+  "pytest-asyncio>=0.20,<0.21.2; python_version<'3.8'",
+  "pytest-asyncio>=0.23; python_version>='3.8'",
+  "ruff>=0.5; python_version>='3.8'",
+]
 
 [project.scripts]
 ns-orm = "ns_orm.cli:main"