typed-store 1.0.0__tar.gz

typed_store-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+__pycache__/
+*.pyc
+*.sqlite3
+dist/
+.DS_Store
+.worktrees/

typed_store-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ticoag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typed_store-1.0.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: typed-store
+Version: 1.0.0
+Summary: Type-first data access SDK built on top of SQLAlchemy
+Author: ticoag
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-access,orm,repository,sqlalchemy,typed
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: greenlet>=3.1.1
+Requires-Dist: sqlalchemy>=2.0.36
+Description-Content-Type: text/markdown
+
+# TypedStore
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.12-blue)](https://www.python.org/) [![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-%E2%89%A52.0.36-green)](https://www.sqlalchemy.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE) [![Status](https://img.shields.io/badge/status-stable-green)]()
+
+Type-first data access SDK built on top of SQLAlchemy 2.x.
+
+TypedStore 把项目中重复出现的 session 管理、CRUD facade、分页与事务样板收敛为一组类型安全的 API——不替代 SQLAlchemy，只做它上层的薄 facade。
+
+## Features
+
+- **Explicit sync / async** — `SyncTypedStore` 与 `AsyncTypedStore` 分离，无隐式双重语义
+- **One-line init** — `SyncTypedStore.from_url("sqlite:///app.db")` 即可开始使用
+- **Protocol-first queries** — `store.find_many(User, query=Query[User]().where(...))`
+- **Bind-first models** — `User.bind(store).find_many()` 让模型天然具备显式绑定能力
+- **Explicit request objects** — `Query`, `PageRequest`, `Patch`, `ProjectionQuery`
+- **Bulk mutation APIs** — `bulk_update` / `bulk_delete` 与 object mutation 语义分离
+- **UnitOfWork** — 明确的事务边界（sync / async）
+- **TypedStoreModel** — 为模型提供纯函数式 `bind(store)` 入口
+- **TypedStore composition root** — 通过 `.sync` / `.async_` 统一装配 sync / async store
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install typed-store
+```
+
+<details>
+<summary>本地开发</summary>
+
+```bash
+uv sync --group dev
+```
+
+</details>
+
+### Sync
+
+```python
+from typed_store import PageRequest, Query, SyncTypedStore
+
+store = SyncTypedStore.from_url("sqlite:///app.db")
+Base.metadata.create_all(store.engine)
+
+store.insert(User(name="alice"))
+query = Query[User]().where(User.role == "admin").order(User.id.asc())
+page = PageRequest(limit=10, offset=0)
+
+store.find_many(User, query=query)
+store.paginate(User, query=query, page=page)
+```
+
+### Async
+
+```python
+from typed_store import AsyncTypedStore, PageRequest, Query
+
+store = AsyncTypedStore.from_url("sqlite+aiosqlite:///app.db")
+
+await store.insert(User(name="alice"))
+query = Query[User]().where(User.role == "admin")
+await store.find_many(User, query=query)
+await store.paginate(User, query=query, page=PageRequest(limit=10, offset=0))
+```
+
+### TypedStore (sync + async)
+
+```python
+from typed_store import Query, TypedStore
+
+ts = TypedStore.from_url("sqlite:///app.db", async_url="sqlite+aiosqlite:///app.db")
+
+# 显式使用 sync store
+ts.sync.find_many(User, query=Query[User]())
+ts.sync.insert(User(name="alice"))
+
+# 异步明确走 .async_
+await ts.async_.find_many(User, query=Query[User]())
+```
+
+### Model Binding
+
+```python
+from typed_store import PageRequest, Query, SyncTypedStore, TypedStoreModel
+
+store = SyncTypedStore.from_url("sqlite:///app.db")
+
+class User(Base, TypedStoreModel):
+    ...
+
+users = User.bind(store)
+users.insert(User(name="alice"))
+users.find_many(query=Query[User]().where(User.role == "admin"))
+users.get(1)
+users.paginate(query=Query[User](), page=PageRequest(limit=10, offset=0))
+```
+
+### Request Objects
+
+```python
+from typed_store import PageRequest, Patch, Query
+
+query = Query[User]().where(User.role == "admin").order(User.id.asc())
+page = PageRequest(limit=10, offset=0)
+patch = Patch[User]({"role": "superadmin"})
+
+store.find_many(User, query=query)
+store.paginate(User, query=query, page=page)
+store.update(User, query=Query[User]().where(User.name == "alice"), patch=patch)
+```
+
+### Bulk Mutation
+
+```python
+from typed_store import Patch, Query
+
+store.bulk_update(
+    User,
+    query=Query[User]().where(User.role == "member"),
+    patch=Patch[User]({"role": "staff"}),
+)
+
+User.bind(store).bulk_delete(
+    query=Query[User]().where(User.role == "guest"),
+)
+```
+
+### Model Mixin
+
+```python
+from typed_store import Query, SyncTypedStore, TypedStoreModel
+
+store = SyncTypedStore.from_url("sqlite:///app.db")
+
+class User(Base, TypedStoreModel):
+    ...
+
+users = User.bind(store)
+users.insert(User(name="alice"))
+items = users.find_many(query=Query[User]())
+```
+
+### Repository Pattern
+
+```python
+store = SyncTypedStore.from_url("sqlite:///app.db")
+repo = UserRepository(store)
+service = UserService(store)
+service.register_admin("alice@example.com")
+```
+
+> 完整示例见 [`examples/`](examples/)，对应 smoke 测试见 [`tests/test_examples.py`](tests/test_examples.py)。
+
+## Requirements
+
+| Dependency | Version   |
+| ---------- | --------- |
+| Python     | >= 3.12   |
+| SQLAlchemy | >= 2.0.36 |
+
+## Documentation
+
+| Document                                     | Description   |
+| -------------------------------------------- | ------------- |
+| [`docs/api-surface.md`](docs/api-surface.md) | 完整 API 说明 |
+| [`docs/design-spec.md`](docs/design-spec.md) | 设计规格      |
+| [`docs/publishing.md`](docs/publishing.md)   | 发布配置清单  |
+| [`CHANGELOG.md`](CHANGELOG.md)               | 版本变更记录  |
+
+## Development
+
+```bash
+uv run pytest              # tests
+uv run ruff check .        # lint
+uv run ruff format --check .  # format check
+uv run ty check            # type check
+```
+
+## License
+
+[MIT](LICENSE)

typed_store-1.0.0/README.md

@@ -0,0 +1,182 @@
+# TypedStore
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.12-blue)](https://www.python.org/) [![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-%E2%89%A52.0.36-green)](https://www.sqlalchemy.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow)](LICENSE) [![Status](https://img.shields.io/badge/status-stable-green)]()
+
+Type-first data access SDK built on top of SQLAlchemy 2.x.
+
+TypedStore 把项目中重复出现的 session 管理、CRUD facade、分页与事务样板收敛为一组类型安全的 API——不替代 SQLAlchemy，只做它上层的薄 facade。
+
+## Features
+
+- **Explicit sync / async** — `SyncTypedStore` 与 `AsyncTypedStore` 分离，无隐式双重语义
+- **One-line init** — `SyncTypedStore.from_url("sqlite:///app.db")` 即可开始使用
+- **Protocol-first queries** — `store.find_many(User, query=Query[User]().where(...))`
+- **Bind-first models** — `User.bind(store).find_many()` 让模型天然具备显式绑定能力
+- **Explicit request objects** — `Query`, `PageRequest`, `Patch`, `ProjectionQuery`
+- **Bulk mutation APIs** — `bulk_update` / `bulk_delete` 与 object mutation 语义分离
+- **UnitOfWork** — 明确的事务边界（sync / async）
+- **TypedStoreModel** — 为模型提供纯函数式 `bind(store)` 入口
+- **TypedStore composition root** — 通过 `.sync` / `.async_` 统一装配 sync / async store
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install typed-store
+```
+
+<details>
+<summary>本地开发</summary>
+
+```bash
+uv sync --group dev
+```
+
+</details>
+
+### Sync
+
+```python
+from typed_store import PageRequest, Query, SyncTypedStore
+
+store = SyncTypedStore.from_url("sqlite:///app.db")
+Base.metadata.create_all(store.engine)
+
+store.insert(User(name="alice"))
+query = Query[User]().where(User.role == "admin").order(User.id.asc())
+page = PageRequest(limit=10, offset=0)
+
+store.find_many(User, query=query)
+store.paginate(User, query=query, page=page)
+```
+
+### Async
+
+```python
+from typed_store import AsyncTypedStore, PageRequest, Query
+
+store = AsyncTypedStore.from_url("sqlite+aiosqlite:///app.db")
+
+await store.insert(User(name="alice"))
+query = Query[User]().where(User.role == "admin")
+await store.find_many(User, query=query)
+await store.paginate(User, query=query, page=PageRequest(limit=10, offset=0))
+```
+
+### TypedStore (sync + async)
+
+```python
+from typed_store import Query, TypedStore
+
+ts = TypedStore.from_url("sqlite:///app.db", async_url="sqlite+aiosqlite:///app.db")
+
+# 显式使用 sync store
+ts.sync.find_many(User, query=Query[User]())
+ts.sync.insert(User(name="alice"))
+
+# 异步明确走 .async_
+await ts.async_.find_many(User, query=Query[User]())
+```
+
+### Model Binding
+
+```python
+from typed_store import PageRequest, Query, SyncTypedStore, TypedStoreModel
+
+store = SyncTypedStore.from_url("sqlite:///app.db")
+
+class User(Base, TypedStoreModel):
+    ...
+
+users = User.bind(store)
+users.insert(User(name="alice"))
+users.find_many(query=Query[User]().where(User.role == "admin"))
+users.get(1)
+users.paginate(query=Query[User](), page=PageRequest(limit=10, offset=0))
+```
+
+### Request Objects
+
+```python
+from typed_store import PageRequest, Patch, Query
+
+query = Query[User]().where(User.role == "admin").order(User.id.asc())
+page = PageRequest(limit=10, offset=0)
+patch = Patch[User]({"role": "superadmin"})
+
+store.find_many(User, query=query)
+store.paginate(User, query=query, page=page)
+store.update(User, query=Query[User]().where(User.name == "alice"), patch=patch)
+```
+
+### Bulk Mutation
+
+```python
+from typed_store import Patch, Query
+
+store.bulk_update(
+    User,
+    query=Query[User]().where(User.role == "member"),
+    patch=Patch[User]({"role": "staff"}),
+)
+
+User.bind(store).bulk_delete(
+    query=Query[User]().where(User.role == "guest"),
+)
+```
+
+### Model Mixin
+
+```python
+from typed_store import Query, SyncTypedStore, TypedStoreModel
+
+store = SyncTypedStore.from_url("sqlite:///app.db")
+
+class User(Base, TypedStoreModel):
+    ...
+
+users = User.bind(store)
+users.insert(User(name="alice"))
+items = users.find_many(query=Query[User]())
+```
+
+### Repository Pattern
+
+```python
+store = SyncTypedStore.from_url("sqlite:///app.db")
+repo = UserRepository(store)
+service = UserService(store)
+service.register_admin("alice@example.com")
+```
+
+> 完整示例见 [`examples/`](examples/)，对应 smoke 测试见 [`tests/test_examples.py`](tests/test_examples.py)。
+
+## Requirements
+
+| Dependency | Version   |
+| ---------- | --------- |
+| Python     | >= 3.12   |
+| SQLAlchemy | >= 2.0.36 |
+
+## Documentation
+
+| Document                                     | Description   |
+| -------------------------------------------- | ------------- |
+| [`docs/api-surface.md`](docs/api-surface.md) | 完整 API 说明 |
+| [`docs/design-spec.md`](docs/design-spec.md) | 设计规格      |
+| [`docs/publishing.md`](docs/publishing.md)   | 发布配置清单  |
+| [`CHANGELOG.md`](CHANGELOG.md)               | 版本变更记录  |
+
+## Development
+
+```bash
+uv run pytest              # tests
+uv run ruff check .        # lint
+uv run ruff format --check .  # format check
+uv run ty check            # type check
+```
+
+## License
+
+[MIT](LICENSE)

typed_store-1.0.0/docs/README.md

@@ -0,0 +1,17 @@
+# Documentation
+
+## User Guide
+
+| Document | Description |
+|---|---|
+| [api-surface.md](api-surface.md) | API reference — entry points, methods, usage scenarios |
+| [design-spec.md](design-spec.md) | Design specification — goals, architecture, core concepts |
+| [publishing.md](publishing.md) | Release & publishing guide for PyPI / TestPyPI |
+
+## Internal (Development)
+
+| Document | Description |
+|---|---|
+| [internal/workflow.md](internal/workflow.md) | Development workflow & task recovery procedure |
+| [internal/progress.md](internal/progress.md) | Current progress tracking for TypedStore |
+| [internal/templates/](internal/templates/) | Spec & progress document templates |

typed_store-1.0.0/docs/api-surface.md

@@ -0,0 +1,268 @@
+# API Surface
+
+本文档描述 `TypedStore` 当前对外推荐的 public API。目标是让使用者快速判断：
+
+- 从哪里进入
+- store capability protocol 和 concrete store 的关系
+- request objects 应该如何驱动查询、分页、更新和投影
+
+## 1. Primary Entry Points
+
+当前推荐的主入口只有四类：
+
+- `SyncTypedStore`：同步 SQLAlchemy 路径的正式实现
+- `AsyncTypedStore`：异步 SQLAlchemy 路径的正式实现
+- `TypedStoreModel.bind(store)`：模型一等能力的绑定入口
+- `TypedStore`：只负责组合 `.sync` / `.async_` 的 composition root
+
+## 2. Request Objects
+
+`TypedStore` 的查询与变更都由显式 request objects 驱动，而不是内联 filter 参数。
+
+### `Query[TModel]`
+
+用于实体查询：
+
+- `Query[TModel]()`：创建空查询
+- `.where(*filters)`：追加过滤条件
+- `.order(*clauses)`：追加排序
+- `.limit_to(limit)`：设置 limit
+- `.offset_by(offset)`：设置 offset
+- `.with_options(*options)`：追加 SQLAlchemy loader options
+
+### `PageRequest`
+
+用于分页请求：
+
+- `PageRequest(limit, offset=0)`
+
+### `Patch[TModel]`
+
+用于字段级更新：
+
+- `Patch[TModel](values={"field": value})`
+
+### `ProjectionQuery[TRow]`
+
+用于显式列投影：
+
+- `ProjectionQuery[TRow](*columns)`
+- `.where(*filters)`
+- `.order(*clauses)`
+- `.with_options(*options)`
+
+## 3. Sync Capability Protocols
+
+同步 capability protocol 定义 public contract：
+
+- `ReadableStoreProtocol[TModel]`
+- `WritableStoreProtocol[TModel]`
+- `PatchableStoreProtocol[TModel]`
+- `BulkPatchableStoreProtocol[TModel]`
+- `DeletableStoreProtocol[TModel]`
+- `BulkDeletableStoreProtocol[TModel]`
+- `StatementExecutorProtocol`
+- `TransactionalStoreProtocol`
+- `SyncModelBoundStoreProtocol[TModel]`
+
+这些协议的意义是定义“这个对象能做什么”，而不是要求使用者必须直接实例化协议本身。
+这些对象共同构成 `v1.0` 的稳定同步 public contract。
+
+## 4. Async Capability Protocols
+
+异步路径与同步路径保持明确分离，对应协议为：
+
+- `AsyncReadableStoreProtocol[TModel]`
+- `AsyncWritableStoreProtocol[TModel]`
+- `AsyncPatchableStoreProtocol[TModel]`
+- `AsyncBulkPatchableStoreProtocol[TModel]`
+- `AsyncDeletableStoreProtocol[TModel]`
+- `AsyncBulkDeletableStoreProtocol[TModel]`
+- `AsyncStatementExecutorProtocol`
+- `AsyncTransactionalStoreProtocol`
+- `AsyncModelBoundStoreProtocol[TModel]`
+
+这些对象共同构成 `v1.0` 的稳定异步 public contract。
+
+## 5. `SyncTypedStore`
+
+`SyncTypedStore` 是基于 SQLAlchemy `Session` 的同步实现。
+
+### Factory And Lifecycle
+
+- `SyncTypedStore.from_url(url, *, echo=False, **engine_options)`
+- `.engine`
+- `.close()`
+- `.dispose()`
+- `.unit_of_work(*, auto_commit=True)`
+
+### CRUD And Query Methods
+
+- `insert(entity, *, session=None, commit=True, refresh=False) -> TModel`
+- `insert_many(entities, *, session=None, commit=True) -> list[TModel]`
+- `get(model, ident, *, session=None) -> TModel | None`
+- `find_one(model, *, query, session=None) -> TModel | None`
+- `find_many(model, *, query, session=None) -> list[TModel]`
+- `exists(model, *, query, session=None) -> bool`
+- `count(model, *, query, session=None) -> int`
+- `paginate(model, *, query, page, session=None) -> Page[TModel]`
+- `update(model, *, query, patch, session=None, commit=True) -> int`
+- `bulk_update(model, *, query, patch, session=None, commit=True) -> int`
+- `delete(model, *, query, session=None, commit=True) -> int`
+- `bulk_delete(model, *, query, session=None, commit=True) -> int`
+- `select_rows(model, *, projection, session=None) -> list[TRow]`
+- `select_scalars(statement, *, session=None) -> list[TScalar]`
+
+### Example
+
+```python
+from typed_store import PageRequest, Query, SyncTypedStore
+
+store = SyncTypedStore.from_url("sqlite:///app.db")
+
+admins = store.find_many(
+    User,
+    query=Query[User]().where(User.role == "admin").order(User.id.asc()),
+)
+
+page = store.paginate(
+    User,
+    query=Query[User]().where(User.role == "admin").order(User.id.asc()),
+    page=PageRequest(limit=20, offset=0),
+)
+```
+
+## 6. `AsyncTypedStore`
+
+`AsyncTypedStore` 是基于 SQLAlchemy `AsyncSession` 的异步实现。
+
+### Factory And Lifecycle
+
+- `AsyncTypedStore.from_url(url, *, echo=False, **engine_options)`
+- `.engine`
+- `.aclose()`
+- `.dispose()`
+- `.unit_of_work(*, auto_commit=True)`
+
+### CRUD And Query Methods
+
+签名与 `SyncTypedStore` 对称，但所有行为都是 `async def`。
+
+### Example
+
+```python
+from typed_store import AsyncTypedStore, PageRequest, Query
+
+store = AsyncTypedStore.from_url("sqlite+aiosqlite:///app.db")
+
+items = await store.find_many(
+    User,
+    query=Query[User]().where(User.role == "admin"),
+)
+
+page = await store.paginate(
+    User,
+    query=Query[User]().where(User.role == "admin").order(User.id.asc()),
+    page=PageRequest(limit=20, offset=0),
+)
+```
+
+## 7. `TypedStore`
+
+`TypedStore` 是 composition root，不是直接 CRUD facade。
+
+### Surface
+
+- `TypedStore.from_url(url=None, *, async_url=None, echo=False, **engine_options)`
+- `.engine`
+- `.async_engine`
+- `.sync`
+- `.async_`
+- `.close()`
+- `.dispose()`
+- `.aclose()`
+- `.unit_of_work(*, auto_commit=True)`
+- `.async_unit_of_work(*, auto_commit=True)`
+
+### Example
+
+```python
+from typed_store import Query, TypedStore
+
+ts = TypedStore.from_url("sqlite:///app.db", async_url="sqlite+aiosqlite:///app.db")
+
+ts.sync.find_many(User, query=Query[User]())
+await ts.async_.find_many(User, query=Query[User]())
+```
+
+## 8. `TypedStoreModel.bind(store)`
+
+模型能力是一等 public API，但只有绑定后才可操作。
+
+### Rules
+
+- 只有 `bind(store)`，没有隐式默认 store
+- `bind()` 是纯函数式绑定，不会把 store 写回模型类
+- sync model view 依赖 sync capability protocols
+- async model view 依赖 async capability protocols
+
+### Bound Model Methods
+
+`Model.bind(store)` 返回的 bound model view 提供：
+
+- `insert`
+- `insert_many`
+- `get`
+- `find_one`
+- `find_many`
+- `exists`
+- `count`
+- `paginate`
+- `update`
+- `bulk_update`
+- `delete`
+- `bulk_delete`
+
+### Example
+
+```python
+from typed_store import PageRequest, Patch, Query
+
+users = User.bind(store)
+
+items = users.find_many(
+    query=Query[User]().where(User.role == "admin").order(User.id.asc()),
+)
+
+updated = users.update(
+    query=Query[User]().where(User.email == "alice@example.com"),
+    patch=Patch[User]({"role": "staff"}),
+)
+
+page = users.paginate(
+    query=Query[User]().where(User.role == "staff"),
+    page=PageRequest(limit=10, offset=0),
+)
+```
+
+## 9. Error Boundary
+
+当前 public API 的运行时保护只保留 contract/configuration 级错误：
+
+- 缺失 sync / async session factory
+- `bind()` 传入不满足协议的 store
+- bulk mutation 使用了不支持的 `Query` 形态
+- 调用签名明显错误，例如遗漏 `projection=` 这样的关键字参数
+
+数据本身的业务校验不由 `TypedStore` 重复承担，默认依赖边界层与静态类型系统。
+
+## 10. Stable v1.0 Surface
+
+以下对象属于 `v1.0` 稳定 public API：
+
+- stores: `SyncTypedStore`, `AsyncTypedStore`, `TypedStore`
+- models: `TypedStoreModel`, `SyncBoundModelView`, `AsyncBoundModelView`
+- request objects: `Query`, `PageRequest`, `Patch`, `ProjectionQuery`
+- results: `Page`
+- protocols: readable / writable / patchable / bulk / deletable / statement / transactional variants
+- support objects: `UnitOfWork`, `AsyncUnitOfWork`, `SessionProvider`