cliver-playbook-app-basic 0.1.0__tar.gz → 0.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/.gitignore +3 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/PKG-INFO +32 -1
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/README.md +31 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/pyproject.toml +1 -1
- cliver_playbook_app_basic-0.2.1/src/cliver_playbook/app/basic/api/pagination.py +41 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/app.py +6 -1
- cliver_playbook_app_basic-0.2.1/src/cliver_playbook/app/basic/schemas/pagination.py +23 -0
- cliver_playbook_app_basic-0.2.1/src/cliver_playbook/app/basic/version.py +19 -0
- cliver_playbook_app_basic-0.2.1/tests/test_pagination.py +69 -0
- cliver_playbook_app_basic-0.2.1/tests/test_version.py +11 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/LICENSE +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/alembic.ini +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/__main__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/alembic/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/alembic/env.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/alembic/script.py.mako +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/alembic/versions/0001_basic_items.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/alembic/versions/0002_app_settings.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/api/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/api/items.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/api/meta.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/api/routes.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/config_yaml.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/db/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/db/base.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/db/session.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/models/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/models/entities.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/runtime.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/runtime_settings.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/schemas/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/schemas/item.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/services/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/services/items.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/src/cliver_playbook/app/basic/settings.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/__init__.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/conftest.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/dsn.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/test_config.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/test_items.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/test_lifespan.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/test_meta.py +0 -0
- {cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/test_runtime_settings.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: cliver-playbook-app-basic
|
|
3
|
-
Version: 0.1
|
|
3
|
+
Version: 0.2.1
|
|
4
4
|
Summary: cliver-playbook foundations: layered settings, process runtime, meta + demo Items API, own Alembic chain
|
|
5
5
|
Project-URL: Repository, https://github.com/cliver-project/cliver-playbook
|
|
6
6
|
Author: Lin Gao
|
|
@@ -36,10 +36,41 @@ runnable API slice.
|
|
|
36
36
|
| Runtime | `runtime.py` | `configure(settings)` binds settings + async engine once per process; nothing is built at import time. |
|
|
37
37
|
| Runtime settings | `runtime_settings.py` | Package-owned settings sections: field description, validation, live apply, `app_settings` persistence and the lifespan overlay (ADR-0021). |
|
|
38
38
|
| Routers | `api/routes.py` | `ROUTERS: list[APIRouter]` — a composed app includes them (ADR-0015). |
|
|
39
|
+
| Pagination | `schemas/pagination.py`, `api/pagination.py` | The shared `Page[T]` response envelope and the `page_params()` limit/offset dependency, with per-route bounds. |
|
|
39
40
|
| Demo slice | `api/items.py`, `services/`, `schemas/`, `models/entities.py` | Full CRUD example: the `items` table and `/api/v1/items`. Optional — delete together with its migration and tests. |
|
|
40
41
|
| Migrations | `alembic/` | Own chain, version table `alembic_version_basic`; creates `items` and `app_settings`. |
|
|
41
42
|
| Application | `app.py`, `__main__.py` | `create_app()` and `python -m cliver_playbook.app.basic`. |
|
|
42
43
|
|
|
44
|
+
## Pagination
|
|
45
|
+
|
|
46
|
+
Paginated endpoints return the shared `Page[T]` envelope and parse their
|
|
47
|
+
window with `page_params()`. The factory's bounds are per endpoint; an
|
|
48
|
+
out-of-range `limit` or `offset` is a 422, never a silently clamped request.
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
from fastapi import Depends
|
|
52
|
+
|
|
53
|
+
from cliver_playbook.app.basic.api.pagination import PageParams, page_params
|
|
54
|
+
from cliver_playbook.app.basic.schemas.pagination import Page
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@router.get("", response_model=Page[OrderRead])
|
|
58
|
+
async def list_orders(
|
|
59
|
+
params: PageParams = Depends(page_params(default_limit=50, max_limit=200)),
|
|
60
|
+
db: AsyncSession = Depends(get_db),
|
|
61
|
+
) -> Page[OrderRead]:
|
|
62
|
+
rows, total = await service.list_orders(db, limit=params.limit, offset=params.offset)
|
|
63
|
+
return Page[OrderRead](
|
|
64
|
+
items=[OrderRead.model_validate(row) for row in rows],
|
|
65
|
+
total=total,
|
|
66
|
+
limit=params.limit,
|
|
67
|
+
offset=params.offset,
|
|
68
|
+
)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`total` counts the full filtered set, not the rows in `items`. The identity
|
|
72
|
+
package's audit listing and the MCP activity feed are the worked examples.
|
|
73
|
+
|
|
43
74
|
## Install
|
|
44
75
|
|
|
45
76
|
```bash
|
|
@@ -12,10 +12,41 @@ runnable API slice.
|
|
|
12
12
|
| Runtime | `runtime.py` | `configure(settings)` binds settings + async engine once per process; nothing is built at import time. |
|
|
13
13
|
| Runtime settings | `runtime_settings.py` | Package-owned settings sections: field description, validation, live apply, `app_settings` persistence and the lifespan overlay (ADR-0021). |
|
|
14
14
|
| Routers | `api/routes.py` | `ROUTERS: list[APIRouter]` — a composed app includes them (ADR-0015). |
|
|
15
|
+
| Pagination | `schemas/pagination.py`, `api/pagination.py` | The shared `Page[T]` response envelope and the `page_params()` limit/offset dependency, with per-route bounds. |
|
|
15
16
|
| Demo slice | `api/items.py`, `services/`, `schemas/`, `models/entities.py` | Full CRUD example: the `items` table and `/api/v1/items`. Optional — delete together with its migration and tests. |
|
|
16
17
|
| Migrations | `alembic/` | Own chain, version table `alembic_version_basic`; creates `items` and `app_settings`. |
|
|
17
18
|
| Application | `app.py`, `__main__.py` | `create_app()` and `python -m cliver_playbook.app.basic`. |
|
|
18
19
|
|
|
20
|
+
## Pagination
|
|
21
|
+
|
|
22
|
+
Paginated endpoints return the shared `Page[T]` envelope and parse their
|
|
23
|
+
window with `page_params()`. The factory's bounds are per endpoint; an
|
|
24
|
+
out-of-range `limit` or `offset` is a 422, never a silently clamped request.
|
|
25
|
+
|
|
26
|
+
```python
|
|
27
|
+
from fastapi import Depends
|
|
28
|
+
|
|
29
|
+
from cliver_playbook.app.basic.api.pagination import PageParams, page_params
|
|
30
|
+
from cliver_playbook.app.basic.schemas.pagination import Page
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
@router.get("", response_model=Page[OrderRead])
|
|
34
|
+
async def list_orders(
|
|
35
|
+
params: PageParams = Depends(page_params(default_limit=50, max_limit=200)),
|
|
36
|
+
db: AsyncSession = Depends(get_db),
|
|
37
|
+
) -> Page[OrderRead]:
|
|
38
|
+
rows, total = await service.list_orders(db, limit=params.limit, offset=params.offset)
|
|
39
|
+
return Page[OrderRead](
|
|
40
|
+
items=[OrderRead.model_validate(row) for row in rows],
|
|
41
|
+
total=total,
|
|
42
|
+
limit=params.limit,
|
|
43
|
+
offset=params.offset,
|
|
44
|
+
)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`total` counts the full filtered set, not the rows in `items`. The identity
|
|
48
|
+
package's audit listing and the MCP activity feed are the worked examples.
|
|
49
|
+
|
|
19
50
|
## Install
|
|
20
51
|
|
|
21
52
|
```bash
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""FastAPI dependency for the shared limit/offset window.
|
|
2
|
+
|
|
3
|
+
The bounds are per endpoint (an audit trail and an agent-activity feed do not
|
|
4
|
+
need the same maximum), so the dependency is a small factory. Validation
|
|
5
|
+
belongs to FastAPI's query parsing: an out-of-range value is a 422, never a
|
|
6
|
+
silently clamped request.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from collections.abc import Callable
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
|
|
12
|
+
from fastapi import Query
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True, slots=True)
|
|
16
|
+
class PageParams:
|
|
17
|
+
"""A validated limit/offset window, independent of any endpoint."""
|
|
18
|
+
|
|
19
|
+
limit: int
|
|
20
|
+
offset: int
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def page_params(*, default_limit: int = 50, max_limit: int = 200) -> Callable[..., PageParams]:
|
|
24
|
+
"""Return a ``Depends``-able parser for ``?limit=`` and ``?offset=``.
|
|
25
|
+
|
|
26
|
+
``default_limit`` applies when the client omits ``limit``; ``max_limit``
|
|
27
|
+
is the largest window the endpoint accepts. Both are validated here so a
|
|
28
|
+
misconfigured route fails at import time, not on the first request.
|
|
29
|
+
"""
|
|
30
|
+
if default_limit < 1:
|
|
31
|
+
raise ValueError("default_limit must be at least 1")
|
|
32
|
+
if max_limit < default_limit:
|
|
33
|
+
raise ValueError("max_limit must be at least default_limit")
|
|
34
|
+
|
|
35
|
+
def dependency(
|
|
36
|
+
limit: int = Query(default=default_limit, ge=1, le=max_limit),
|
|
37
|
+
offset: int = Query(default=0, ge=0),
|
|
38
|
+
) -> PageParams:
|
|
39
|
+
return PageParams(limit=limit, offset=offset)
|
|
40
|
+
|
|
41
|
+
return dependency
|
|
@@ -19,6 +19,7 @@ from cliver_playbook.app.basic import runtime
|
|
|
19
19
|
from cliver_playbook.app.basic.api.routes import ROUTERS
|
|
20
20
|
from cliver_playbook.app.basic.runtime_settings import settings_lifespan
|
|
21
21
|
from cliver_playbook.app.basic.settings import Settings
|
|
22
|
+
from cliver_playbook.app.basic.version import package_version
|
|
22
23
|
|
|
23
24
|
logger = logging.getLogger("cliver_playbook.app.basic")
|
|
24
25
|
|
|
@@ -40,7 +41,11 @@ def create_app(settings: Settings | None = None) -> FastAPI:
|
|
|
40
41
|
runtime.configure(resolved)
|
|
41
42
|
|
|
42
43
|
logging.basicConfig(level=resolved.log_level.upper())
|
|
43
|
-
app = FastAPI(
|
|
44
|
+
app = FastAPI(
|
|
45
|
+
title=resolved.app_name,
|
|
46
|
+
version=package_version("cliver-playbook-app-basic"),
|
|
47
|
+
lifespan=settings_lifespan,
|
|
48
|
+
)
|
|
44
49
|
for router in ROUTERS:
|
|
45
50
|
app.include_router(router)
|
|
46
51
|
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""The shared pagination envelope.
|
|
2
|
+
|
|
3
|
+
Every paginated endpoint returns the same four fields, so a client can write
|
|
4
|
+
one pager and one typed decoder instead of reverse-engineering each route:
|
|
5
|
+
``items`` is this window, ``total`` is the size of the full filtered set,
|
|
6
|
+
and ``limit``/``offset`` echo the window the server actually applied.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from pydantic import BaseModel, Field
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Page[T](BaseModel):
|
|
13
|
+
"""One window of a larger, ordered result set.
|
|
14
|
+
|
|
15
|
+
``total`` counts the full filtered set, not the rows in ``items`` — it is
|
|
16
|
+
what makes "next page" decidable. The row order is the endpoint's
|
|
17
|
+
contract; pagination itself only slices it.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
items: list[T]
|
|
21
|
+
total: int = Field(ge=0)
|
|
22
|
+
limit: int = Field(ge=1)
|
|
23
|
+
offset: int = Field(ge=0)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Application version metadata.
|
|
2
|
+
|
|
3
|
+
The release tooling keeps every distribution on one version; reading it from
|
|
4
|
+
installed metadata means an app factory never carries a version string that
|
|
5
|
+
drifts from its manifest. A source copy that has no distribution metadata
|
|
6
|
+
still boots, reporting ``0.0.0``.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def package_version(distribution: str) -> str:
|
|
15
|
+
"""Return ``distribution``'s installed version, or ``0.0.0`` if absent."""
|
|
16
|
+
try:
|
|
17
|
+
return version(distribution)
|
|
18
|
+
except PackageNotFoundError:
|
|
19
|
+
return "0.0.0"
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""Shared pagination contract: the Page envelope and the query dependency.
|
|
2
|
+
|
|
3
|
+
The envelope is transport-agnostic; the dependency only parses and validates
|
|
4
|
+
limit/offset. Endpoints that page a query use both together, so the response
|
|
5
|
+
shape and the accepted window never drift between packages.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import httpx
|
|
9
|
+
import pytest
|
|
10
|
+
from fastapi import Depends, FastAPI
|
|
11
|
+
from pydantic import ValidationError
|
|
12
|
+
|
|
13
|
+
from cliver_playbook.app.basic.api.pagination import PageParams, page_params
|
|
14
|
+
from cliver_playbook.app.basic.schemas.pagination import Page
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _app(**options) -> FastAPI:
|
|
18
|
+
app = FastAPI()
|
|
19
|
+
dependency = page_params(**options)
|
|
20
|
+
|
|
21
|
+
@app.get("/page")
|
|
22
|
+
async def route(params: PageParams = Depends(dependency)) -> dict:
|
|
23
|
+
return {"limit": params.limit, "offset": params.offset}
|
|
24
|
+
|
|
25
|
+
return app
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
async def _get(app: FastAPI, path: str) -> httpx.Response:
|
|
29
|
+
transport = httpx.ASGITransport(app=app)
|
|
30
|
+
async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
|
|
31
|
+
return await client.get(path)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
async def test_page_carries_items_total_and_window():
|
|
35
|
+
page = Page[int](items=[1, 2], total=5, limit=2, offset=2)
|
|
36
|
+
assert page.model_dump() == {
|
|
37
|
+
"items": [1, 2],
|
|
38
|
+
"total": 5,
|
|
39
|
+
"limit": 2,
|
|
40
|
+
"offset": 2,
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def test_page_rejects_impossible_bookkeeping():
|
|
45
|
+
with pytest.raises(ValidationError):
|
|
46
|
+
Page[int](items=[], total=-1, limit=10, offset=0)
|
|
47
|
+
with pytest.raises(ValidationError):
|
|
48
|
+
Page[int](items=[], total=0, limit=0, offset=0)
|
|
49
|
+
with pytest.raises(ValidationError):
|
|
50
|
+
Page[int](items=[], total=0, limit=10, offset=-1)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
async def test_page_params_defaults_and_overrides():
|
|
54
|
+
app = _app(default_limit=20, max_limit=50)
|
|
55
|
+
assert (await _get(app, "/page")).json() == {"limit": 20, "offset": 0}
|
|
56
|
+
assert (await _get(app, "/page?limit=5&offset=10")).json() == {"limit": 5, "offset": 10}
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
async def test_page_params_rejects_out_of_range_values():
|
|
60
|
+
app = _app(default_limit=20, max_limit=50)
|
|
61
|
+
for path in ("/page?limit=0", "/page?limit=51", "/page?offset=-1"):
|
|
62
|
+
assert (await _get(app, path)).status_code == 422
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def test_page_params_factory_validates_its_bounds():
|
|
66
|
+
with pytest.raises(ValueError):
|
|
67
|
+
page_params(default_limit=0)
|
|
68
|
+
with pytest.raises(ValueError):
|
|
69
|
+
page_params(default_limit=51, max_limit=50)
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
from importlib.metadata import version
|
|
2
|
+
|
|
3
|
+
from cliver_playbook.app.basic.version import package_version
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def test_package_version_reads_the_installed_distribution():
|
|
7
|
+
assert package_version("cliver-playbook-app-basic") == version("cliver-playbook-app-basic")
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def test_package_version_falls_back_for_an_uninstalled_distribution():
|
|
11
|
+
assert package_version("cliver-playbook-app-not-installed") == "0.0.0"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{cliver_playbook_app_basic-0.1.0 → cliver_playbook_app_basic-0.2.1}/tests/test_runtime_settings.py
RENAMED
|
File without changes
|