cliver-playbook-app-basic 0.1.0__py3-none-any.whl

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.
Files changed (29) hide show
  1. cliver_playbook/app/basic/__init__.py +12 -0
  2. cliver_playbook/app/basic/__main__.py +33 -0
  3. cliver_playbook/app/basic/alembic/__init__.py +57 -0
  4. cliver_playbook/app/basic/alembic/env.py +91 -0
  5. cliver_playbook/app/basic/alembic/script.py.mako +26 -0
  6. cliver_playbook/app/basic/alembic/versions/0001_basic_items.py +54 -0
  7. cliver_playbook/app/basic/alembic/versions/0002_app_settings.py +47 -0
  8. cliver_playbook/app/basic/api/__init__.py +0 -0
  9. cliver_playbook/app/basic/api/items.py +58 -0
  10. cliver_playbook/app/basic/api/meta.py +27 -0
  11. cliver_playbook/app/basic/api/routes.py +20 -0
  12. cliver_playbook/app/basic/app.py +48 -0
  13. cliver_playbook/app/basic/config_yaml.py +220 -0
  14. cliver_playbook/app/basic/db/__init__.py +0 -0
  15. cliver_playbook/app/basic/db/base.py +7 -0
  16. cliver_playbook/app/basic/db/session.py +31 -0
  17. cliver_playbook/app/basic/models/__init__.py +0 -0
  18. cliver_playbook/app/basic/models/entities.py +83 -0
  19. cliver_playbook/app/basic/runtime.py +160 -0
  20. cliver_playbook/app/basic/runtime_settings.py +557 -0
  21. cliver_playbook/app/basic/schemas/__init__.py +0 -0
  22. cliver_playbook/app/basic/schemas/item.py +31 -0
  23. cliver_playbook/app/basic/services/__init__.py +0 -0
  24. cliver_playbook/app/basic/services/items.py +50 -0
  25. cliver_playbook/app/basic/settings.py +162 -0
  26. cliver_playbook_app_basic-0.1.0.dist-info/METADATA +79 -0
  27. cliver_playbook_app_basic-0.1.0.dist-info/RECORD +29 -0
  28. cliver_playbook_app_basic-0.1.0.dist-info/WHEEL +4 -0
  29. cliver_playbook_app_basic-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,557 @@
1
+ """Module-owned runtime settings: registry, validation, persistence, overlay.
2
+
3
+ ADR-0021. Configuration has four layers, highest precedence first:
4
+
5
+ environment > .env > persisted runtime overrides > app.yaml > defaults
6
+
7
+ The first two and ``app.yaml`` are resolved by pydantic-settings when the
8
+ process starts; this module owns the middle layer. A package registers a
9
+ ``SettingsSection`` at import time — its fields, labels, allowed values, and
10
+ the functions that read/apply the section on a Settings instance. The central
11
+ admin API (in the identity package) never interprets those fields itself; it
12
+ asks each section to describe itself, validates the request, and calls the
13
+ owner's ``apply``. That is how RAG settings stay owned by RAG while the
14
+ administrator sees one settings surface.
15
+
16
+ Boundaries (deliberate, see the ADR):
17
+
18
+ - Environment-managed fields are read-only. An explicit ``env_var`` is checked
19
+ against the process environment and the project ``.env``; a persisted
20
+ override for such a field is ignored on load and rejected on write, because
21
+ the environment would win at the next restart anyway.
22
+ - Secrets are write-only. The API accepts a new value, persists it with the
23
+ section, and never returns it — the description reports only configured /
24
+ not configured. An environment variable or ``.env`` entry with the declared
25
+ ``env_var`` still wins and makes the field read-only, so a deployment can
26
+ keep credentials out of the database entirely.
27
+ - ``apply`` must validate fully before mutating the bound Settings instance.
28
+ The live instance is mutated in place so a change takes effect on the next
29
+ request without rebuilding the engine.
30
+ - A missing ``app_settings`` table is not fatal. Apps are constructed before
31
+ migrations in several test/bootstrap paths, and a deployment that has not
32
+ run the basic chain yet should still serve requests with static config.
33
+ """
34
+
35
+ from __future__ import annotations
36
+
37
+ import logging
38
+ import os
39
+ import re
40
+ from collections.abc import Callable, Mapping, Sequence
41
+ from contextlib import asynccontextmanager
42
+ from dataclasses import dataclass
43
+ from typing import Any
44
+
45
+ from dotenv import dotenv_values
46
+ from sqlalchemy import delete, select
47
+ from sqlalchemy.exc import SQLAlchemyError
48
+ from sqlalchemy.ext.asyncio import AsyncSession
49
+
50
+ from cliver_playbook.app.basic import runtime
51
+ from cliver_playbook.app.basic.config_yaml import resolve_env_file
52
+ from cliver_playbook.app.basic.db.session import open_session
53
+ from cliver_playbook.app.basic.models.entities import AppSetting
54
+
55
+ logger = logging.getLogger("cliver_playbook.app.basic.runtime_settings")
56
+
57
+ _FIELD_TYPES = frozenset({"string", "integer", "number", "boolean", "enum", "json"})
58
+ _SECTION_KEY_PATTERN = r"^[a-z][a-z0-9_-]{0,63}$"
59
+
60
+
61
+ class SettingsError(RuntimeError):
62
+ """Base class for runtime-settings failures (reported as a 400 by the API)."""
63
+
64
+
65
+ class UnknownSectionError(SettingsError):
66
+ """No package registered the requested section key."""
67
+
68
+
69
+ class SettingsValidationError(SettingsError):
70
+ """A requested value is unknown, read-only, or fails the section's rules."""
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class SettingsField:
75
+ """One editable value in a module-owned settings section.
76
+
77
+ ``env_var`` is the canonical environment variable that overrides the
78
+ field (``CLIVER_RAG__EMBEDDER``). For a secret it names the variable a
79
+ deployment can use to keep the credential out of the database: when set,
80
+ the environment wins and the field becomes read-only. Otherwise the
81
+ secret is write-only — accepted on update, persisted with the section,
82
+ never returned.
83
+ """
84
+
85
+ name: str
86
+ label: str
87
+ type: str = "string"
88
+ description: str = ""
89
+ enum: tuple[str, ...] | None = None
90
+ minimum: float | None = None
91
+ maximum: float | None = None
92
+ env_var: str | None = None
93
+ secret: bool = False
94
+ # Optional presentation grouping. Fields sharing a key render together
95
+ # under one heading; ``group_title`` is the English label a UI falls back
96
+ # to when it has no translation. ``subgroup`` adds a nested heading inside
97
+ # that group (for a large configuration with distinct purposes). Purely
98
+ # presentational — persistence and validation remain per field.
99
+ group: str | None = None
100
+ group_title: str = ""
101
+ subgroup: str | None = None
102
+ subgroup_title: str = ""
103
+
104
+ def __post_init__(self) -> None:
105
+ if (
106
+ not self.name
107
+ or "." in self.name
108
+ and not all(part.isidentifier() for part in self.name.split("."))
109
+ ):
110
+ raise ValueError(f"invalid settings field name: {self.name!r}")
111
+ if not self.name[0].islower():
112
+ raise ValueError(f"settings field name must start lowercase: {self.name!r}")
113
+ if self.type not in _FIELD_TYPES:
114
+ raise ValueError(f"{self.name}: unknown field type {self.type!r}")
115
+ if self.type == "enum" and not self.enum:
116
+ raise ValueError(f"{self.name}: an enum field needs at least one choice")
117
+ if self.enum is not None:
118
+ if self.type != "enum":
119
+ raise ValueError(f"{self.name}: only an enum field may declare choices")
120
+ if len(set(self.enum)) != len(self.enum):
121
+ raise ValueError(f"{self.name}: duplicate enum choices")
122
+ if self.minimum is not None and self.maximum is not None and self.minimum > self.maximum:
123
+ raise ValueError(f"{self.name}: minimum exceeds maximum")
124
+ if self.group is not None:
125
+ if not re.match(_SECTION_KEY_PATTERN, self.group):
126
+ raise ValueError(f"{self.name}: invalid group key {self.group!r}")
127
+ if not self.group_title:
128
+ raise ValueError(
129
+ f"{self.name}: a grouped field must declare group_title "
130
+ "(the untranslated UI fallback)"
131
+ )
132
+ elif self.group_title:
133
+ raise ValueError(f"{self.name}: group_title requires a group key")
134
+ if self.subgroup is not None:
135
+ if self.group is None:
136
+ raise ValueError(f"{self.name}: a subgroup requires a group key")
137
+ if not re.match(_SECTION_KEY_PATTERN, self.subgroup):
138
+ raise ValueError(f"{self.name}: invalid subgroup key {self.subgroup!r}")
139
+ if not self.subgroup_title:
140
+ raise ValueError(
141
+ f"{self.name}: a subgrouped field must declare subgroup_title "
142
+ "(the untranslated UI fallback)"
143
+ )
144
+ elif self.subgroup_title:
145
+ raise ValueError(f"{self.name}: subgroup_title requires a subgroup key")
146
+
147
+
148
+ @dataclass(frozen=True)
149
+ class SettingsSection:
150
+ """A package-owned slice of the settings surface.
151
+
152
+ ``read`` returns the section's current values keyed by field name (raw —
153
+ including secrets, for the configured/not-configured check). ``apply``
154
+ receives a partial mapping and must validate the resulting full state
155
+ before mutating the Settings instance.
156
+ """
157
+
158
+ key: str
159
+ title: str
160
+ description: str
161
+ fields: Callable[[], Sequence[SettingsField]]
162
+ read: Callable[[Any], Mapping[str, Any]]
163
+ apply: Callable[[Any, Mapping[str, Any]], None]
164
+
165
+ def __post_init__(self) -> None:
166
+ if not re.match(_SECTION_KEY_PATTERN, self.key):
167
+ raise ValueError(f"invalid settings section key: {self.key!r}")
168
+ if not self.title:
169
+ raise ValueError(f"settings section {self.key!r} needs a title")
170
+ _validated_fields(self)
171
+
172
+
173
+ def _validated_fields(section: SettingsSection) -> tuple[SettingsField, ...]:
174
+ """Materialise and structurally validate a section's field list."""
175
+ fields = tuple(section.fields())
176
+ if not fields:
177
+ raise ValueError(f"settings section {section.key!r} has no fields")
178
+ names = [field.name for field in fields]
179
+ if len(set(names)) != len(names):
180
+ raise ValueError(f"settings section {section.key!r} has duplicate field names")
181
+ return fields
182
+
183
+
184
+ _sections: dict[str, SettingsSection] = {}
185
+
186
+
187
+ def register_settings_section(section: SettingsSection) -> None:
188
+ """Register a module-owned settings section (idempotent for re-imports)."""
189
+ existing = _sections.get(section.key)
190
+ if existing is not None:
191
+ if existing == section:
192
+ return
193
+ raise ValueError(
194
+ f"settings section {section.key!r} is already registered by another "
195
+ "package — section keys are process-wide"
196
+ )
197
+ _sections[section.key] = section
198
+
199
+
200
+ def settings_sections() -> tuple[SettingsSection, ...]:
201
+ """Every registered section, in registration order."""
202
+ return tuple(_sections.values())
203
+
204
+
205
+ def get_settings_section(key: str) -> SettingsSection | None:
206
+ return _sections.get(key)
207
+
208
+
209
+ def env_snapshot(settings: Any | None = None) -> dict[str, str]:
210
+ """Process environment plus the project .env, for env-managed detection.
211
+
212
+ The process environment wins, matching the settings precedence. Empty
213
+ values still count as "set" — an explicitly empty environment variable is
214
+ an operator decision, not an absence.
215
+
216
+ The dotenv layer follows the bound Settings instance's ``_env_file``:
217
+ ``None`` means the instance deliberately disabled that layer (tests do
218
+ this), so the project .env must not leak into the description either.
219
+ """
220
+ snapshot: dict[str, str] = dict(os.environ)
221
+ resolved = settings if settings is not None else runtime.configured_settings()
222
+ env_file: Any
223
+ if resolved is not None and hasattr(resolved, "_env_file"):
224
+ env_file = resolved._env_file
225
+ else:
226
+ env_file = resolve_env_file()
227
+ if env_file is not None:
228
+ try:
229
+ for key, value in dotenv_values(env_file).items():
230
+ if value is not None:
231
+ snapshot.setdefault(key, value)
232
+ except OSError: # pragma: no cover - resolve_env_file already checked
233
+ logger.warning("could not read %s while describing runtime settings", env_file)
234
+ return snapshot
235
+
236
+
237
+ def is_env_managed(field: SettingsField, env: Mapping[str, str]) -> bool:
238
+ """True when the environment (or .env) explicitly sets this field."""
239
+ if not field.env_var:
240
+ return False
241
+ return field.env_var in env or field.env_var.upper() in env
242
+
243
+
244
+ def _env_value(field: SettingsField, env: Mapping[str, str]) -> str | None:
245
+ if not field.env_var:
246
+ return None
247
+ return env.get(field.env_var) or env.get(field.env_var.upper())
248
+
249
+
250
+ def _describe_field(
251
+ field: SettingsField,
252
+ raw: Mapping[str, Any],
253
+ *,
254
+ env: Mapping[str, str],
255
+ persisted: Mapping[str, Any],
256
+ ) -> dict[str, Any]:
257
+ value = raw.get(field.name)
258
+ managed = is_env_managed(field, env)
259
+ # A secret is writable unless the environment supplies it: the UI accepts
260
+ # a replacement and never receives the stored value back.
261
+ read_only = managed
262
+ if managed:
263
+ source = "environment"
264
+ elif field.name in persisted:
265
+ source = "runtime"
266
+ else:
267
+ source = "config"
268
+ return {
269
+ "name": field.name,
270
+ "label": field.label,
271
+ "type": field.type,
272
+ "description": field.description,
273
+ "enum": list(field.enum) if field.enum else None,
274
+ "minimum": field.minimum,
275
+ "maximum": field.maximum,
276
+ "env_var": field.env_var,
277
+ "secret": field.secret,
278
+ "group": field.group,
279
+ "group_title": field.group_title,
280
+ "subgroup": field.subgroup,
281
+ "subgroup_title": field.subgroup_title,
282
+ "read_only": read_only,
283
+ "source": source,
284
+ # A secret never leaves the process; its presence is the useful fact.
285
+ # An environment value counts even when the running instance predates
286
+ # it (the environment is authoritative at the next restart).
287
+ "value": None if field.secret else value,
288
+ "configured": (bool(_env_value(field, env) or value) if field.secret else None),
289
+ }
290
+
291
+
292
+ def describe_section(
293
+ section: SettingsSection,
294
+ *,
295
+ env: Mapping[str, str] | None = None,
296
+ persisted: Mapping[str, Any] | None = None,
297
+ ) -> dict[str, Any]:
298
+ """Public, secret-free representation of one section for the admin UI."""
299
+ settings = runtime.configured_settings()
300
+ if settings is None:
301
+ raise RuntimeError("describe_section() requires a configured runtime")
302
+ env = env_snapshot(settings) if env is None else env
303
+ persisted = persisted or {}
304
+ raw = section.read(settings)
305
+ return {
306
+ "key": section.key,
307
+ "title": section.title,
308
+ "description": section.description,
309
+ "fields": [
310
+ _describe_field(field, raw, env=env, persisted=persisted)
311
+ for field in _validated_fields(section)
312
+ ],
313
+ }
314
+
315
+
316
+ def describe_sections(
317
+ *,
318
+ env: Mapping[str, str] | None = None,
319
+ overrides: Mapping[str, Mapping[str, Any]] | None = None,
320
+ ) -> list[dict[str, Any]]:
321
+ settings = _require_settings()
322
+ env = env_snapshot(settings) if env is None else env
323
+ overrides = overrides or {}
324
+ return [
325
+ describe_section(section, env=env, persisted=overrides.get(section.key, {}))
326
+ for section in settings_sections()
327
+ ]
328
+
329
+
330
+ def _validate_value(field: SettingsField, value: Any) -> None:
331
+ """Type/range check before the owning section's model validation runs."""
332
+ if field.type == "boolean":
333
+ ok = isinstance(value, bool)
334
+ elif field.type == "integer":
335
+ ok = isinstance(value, int) and not isinstance(value, bool)
336
+ elif field.type == "number":
337
+ ok = isinstance(value, (int, float)) and not isinstance(value, bool)
338
+ elif field.type == "string":
339
+ ok = isinstance(value, str)
340
+ elif field.type == "enum":
341
+ ok = isinstance(value, str) and value in (field.enum or ())
342
+ else: # json
343
+ ok = isinstance(value, (dict, list, str, int, float, bool)) or value is None
344
+ if not ok:
345
+ expected = " or ".join(field.enum) if field.type == "enum" else field.type
346
+ raise SettingsValidationError(
347
+ f"{field.label} ({field.name}) must be {expected}, got {type(value).__name__}"
348
+ )
349
+ if field.type in {"integer", "number"}:
350
+ if field.minimum is not None and value < field.minimum:
351
+ raise SettingsValidationError(f"{field.label} must be at least {field.minimum:g}")
352
+ if field.maximum is not None and value > field.maximum:
353
+ raise SettingsValidationError(f"{field.label} must be at most {field.maximum:g}")
354
+
355
+
356
+ def _field_map(section: SettingsSection) -> dict[str, SettingsField]:
357
+ return {field.name: field for field in _validated_fields(section)}
358
+
359
+
360
+ def redact_values(section: SettingsSection, values: Mapping[str, Any]) -> dict[str, Any]:
361
+ """A copy safe to persist in the audit trail: secret values are masked.
362
+
363
+ Section values are otherwise recorded verbatim so an operator can see
364
+ what changed. ``api_key``-style fields must not end up in the audit log,
365
+ whose readers and retention differ from the settings row's.
366
+ """
367
+ fields = _field_map(section)
368
+ redacted: dict[str, Any] = {}
369
+ for name, value in values.items():
370
+ field = fields.get(name)
371
+ if field is not None and field.secret:
372
+ redacted[name] = "<redacted>" if value else ""
373
+ else:
374
+ redacted[name] = value
375
+ return redacted
376
+
377
+
378
+ def _clean_values(
379
+ section: SettingsSection,
380
+ values: Mapping[str, Any],
381
+ *,
382
+ env: Mapping[str, str],
383
+ for_write: bool,
384
+ ) -> dict[str, Any]:
385
+ """Filter a stored/proposed mapping to fields the runtime may apply.
386
+
387
+ Unknown keys are ignored on load (a section may have dropped a field) but
388
+ rejected on write. Env-managed fields — secrets included — are always
389
+ dropped: the environment is authoritative for them. A persisted secret
390
+ that the environment does not manage survives the load so the startup
391
+ overlay can apply it.
392
+ """
393
+ fields = _field_map(section)
394
+ clean: dict[str, Any] = {}
395
+ for name, value in values.items():
396
+ field = fields.get(name)
397
+ if field is None:
398
+ if for_write:
399
+ raise SettingsValidationError(f"unknown setting: {name!r}")
400
+ continue
401
+ if is_env_managed(field, env):
402
+ if for_write:
403
+ raise SettingsValidationError(
404
+ f"{field.label} is managed by {field.env_var} and cannot be changed at runtime"
405
+ )
406
+ continue
407
+ if for_write:
408
+ _validate_value(field, value)
409
+ clean[name] = value
410
+ return clean
411
+
412
+
413
+ def _require_settings() -> Any:
414
+ settings = runtime.configured_settings()
415
+ if settings is None:
416
+ raise RuntimeError("runtime settings require a configured runtime")
417
+ return settings
418
+
419
+
420
+ async def load_overrides(db: AsyncSession | None = None) -> dict[str, dict[str, Any]]:
421
+ """Read every persisted section row (empty when the table is absent)."""
422
+ owns_session = db is None
423
+ session = open_session() if db is None else db
424
+ try:
425
+ rows = (await session.execute(select(AppSetting))).scalars().all()
426
+ return {row.section: dict(row.values or {}) for row in rows}
427
+ finally:
428
+ if owns_session:
429
+ # Startup overlays must never fail on teardown: a session whose
430
+ # connection could not be acquired (or belongs to another event
431
+ # loop) may also fail to close, and that error must not replace
432
+ # the read error the caller is about to handle.
433
+ try:
434
+ await session.close()
435
+ except Exception: # pragma: no cover - defensive teardown
436
+ logger.warning("could not close the runtime-settings session", exc_info=True)
437
+
438
+
439
+ def is_missing_table(exc: SQLAlchemyError) -> bool:
440
+ original = getattr(exc, "orig", None)
441
+ pgcode = getattr(original, "pgcode", None)
442
+ text = str(original or exc).lower()
443
+ return (
444
+ pgcode == "42P01"
445
+ or "undefinedtable" in text
446
+ or "no such table" in text
447
+ or "does not exist" in text
448
+ )
449
+
450
+
451
+ async def update_section(
452
+ db: AsyncSession,
453
+ section: SettingsSection,
454
+ values: Mapping[str, Any],
455
+ *,
456
+ actor_id: int | None,
457
+ ) -> dict[str, Any]:
458
+ """Validate, apply live, and persist a partial section update.
459
+
460
+ The caller owns the transaction (the admin API writes its audit row and
461
+ commits both changes together). On a validation failure nothing is
462
+ persisted and — because sections validate before mutating — the live
463
+ settings are unchanged.
464
+ """
465
+ if not isinstance(values, Mapping):
466
+ raise SettingsValidationError("values must be an object")
467
+ settings = _require_settings()
468
+ env = env_snapshot(settings)
469
+ clean = _clean_values(section, values, env=env, for_write=True)
470
+
471
+ row = await db.get(AppSetting, section.key)
472
+ stored = dict(row.values or {}) if row is not None else {}
473
+ merged = {**stored, **clean}
474
+ # A value stored before its field became environment-managed must not
475
+ # override the environment in-process.
476
+ merged = _clean_values(section, merged, env=env, for_write=False)
477
+
478
+ section.apply(settings, merged)
479
+
480
+ if row is None:
481
+ row = AppSetting(section=section.key, values=merged, updated_by=actor_id)
482
+ db.add(row)
483
+ else:
484
+ row.values = merged
485
+ row.updated_by = actor_id
486
+ await db.flush()
487
+ return merged
488
+
489
+
490
+ async def reset_section(
491
+ db: AsyncSession, section: SettingsSection, *, actor_id: int | None
492
+ ) -> None:
493
+ """Delete the section's persisted row and restore the startup baseline."""
494
+ settings = _require_settings()
495
+ baseline = runtime.baseline_settings()
496
+ if baseline is None: # pragma: no cover - configure always stores one
497
+ raise RuntimeError("runtime baseline is unavailable")
498
+ env = env_snapshot(settings)
499
+ baseline_values = dict(section.read(baseline))
500
+ restore = _clean_values(section, baseline_values, env=env, for_write=False)
501
+ section.apply(settings, restore)
502
+ await db.execute(delete(AppSetting).where(AppSetting.section == section.key))
503
+ await db.flush()
504
+
505
+
506
+ async def load_persisted_settings() -> None:
507
+ """Apply every persisted override at startup (best effort).
508
+
509
+ Called by each package's lifespan. A missing table (migrations not yet
510
+ applied) is a warning, not a crash: the application still serves static
511
+ configuration. Any other read failure is handled the same way — the
512
+ overlay is an optimization, and no database condition at startup may
513
+ prevent the process from serving. A bad row is logged and skipped for the
514
+ same reason — one malformed section must not take the process down.
515
+ """
516
+ if not runtime.is_configured():
517
+ return
518
+ settings = runtime.configured_settings()
519
+ try:
520
+ overrides = await load_overrides()
521
+ except Exception as exc:
522
+ if isinstance(exc, SQLAlchemyError) and is_missing_table(exc):
523
+ logger.warning(
524
+ "app_settings table is missing; runtime settings overrides are disabled "
525
+ "until the basic migration chain is applied"
526
+ )
527
+ else:
528
+ logger.exception("could not read app_settings; continuing with static configuration")
529
+ return
530
+
531
+ env = env_snapshot(settings)
532
+ for key, values in overrides.items():
533
+ section = get_settings_section(key)
534
+ if section is None:
535
+ logger.warning(
536
+ "app_settings row for unknown section %r ignored (owning package not installed?)",
537
+ key,
538
+ )
539
+ continue
540
+ try:
541
+ clean = _clean_values(section, values, env=env, for_write=False)
542
+ section.apply(settings, clean)
543
+ except Exception:
544
+ logger.exception(
545
+ "could not apply persisted settings for section %r; using static configuration",
546
+ key,
547
+ )
548
+
549
+
550
+ @asynccontextmanager
551
+ async def settings_lifespan(_app: Any):
552
+ """Lifespan wrapper: overlay persisted settings, then release the engine."""
553
+ await load_persisted_settings()
554
+ try:
555
+ yield
556
+ finally:
557
+ await runtime.dispose()
File without changes
@@ -0,0 +1,31 @@
1
+ """Pydantic schemas for the Item demo entity (request/response contracts)."""
2
+
3
+ from datetime import datetime
4
+
5
+ from pydantic import BaseModel, ConfigDict, Field
6
+
7
+
8
+ class ItemBase(BaseModel):
9
+ name: str = Field(min_length=1, max_length=200)
10
+ description: str = Field(default="", max_length=10_000)
11
+ quantity: int = Field(default=0, ge=0)
12
+
13
+
14
+ class ItemCreate(ItemBase):
15
+ """Payload for POST /api/v1/items."""
16
+
17
+
18
+ class ItemUpdate(BaseModel):
19
+ """Payload for PATCH /api/v1/items/{id} — all fields optional."""
20
+
21
+ name: str | None = Field(default=None, min_length=1, max_length=200)
22
+ description: str | None = Field(default=None, max_length=10_000)
23
+ quantity: int | None = Field(default=None, ge=0)
24
+
25
+
26
+ class ItemRead(ItemBase):
27
+ model_config = ConfigDict(from_attributes=True)
28
+
29
+ id: int
30
+ created_at: datetime
31
+ updated_at: datetime
File without changes
@@ -0,0 +1,50 @@
1
+ """Item CRUD service.
2
+
3
+ Functions take an `AsyncSession` and stay transport-agnostic: routers own
4
+ HTTP concerns, services own persistence rules. This layer is the seam a
5
+ consuming project (or a real domain) extends.
6
+ """
7
+
8
+ from sqlalchemy import func, select
9
+ from sqlalchemy.ext.asyncio import AsyncSession
10
+
11
+ from cliver_playbook.app.basic.models.entities import Item
12
+ from cliver_playbook.app.basic.schemas.item import ItemCreate, ItemUpdate
13
+
14
+
15
+ async def list_items(
16
+ db: AsyncSession, *, limit: int = 50, offset: int = 0
17
+ ) -> tuple[list[Item], int]:
18
+ """Return (items, total_count) ordered by newest first."""
19
+ rows = await db.execute(
20
+ select(Item).order_by(Item.created_at.desc(), Item.id.desc()).limit(limit).offset(offset)
21
+ )
22
+ total = await db.scalar(select(func.count()).select_from(Item))
23
+ return list(rows.scalars().all()), int(total or 0)
24
+
25
+
26
+ async def get_item(db: AsyncSession, item_id: int) -> Item | None:
27
+ return await db.get(Item, item_id)
28
+
29
+
30
+ async def create_item(db: AsyncSession, payload: ItemCreate) -> Item:
31
+ item = Item(**payload.model_dump())
32
+ db.add(item)
33
+ await db.commit()
34
+ await db.refresh(item)
35
+ return item
36
+
37
+
38
+ async def update_item(db: AsyncSession, item: Item, payload: ItemUpdate) -> Item:
39
+ changes = payload.model_dump(exclude_unset=True)
40
+ for field, value in changes.items():
41
+ setattr(item, field, value)
42
+ if changes:
43
+ await db.commit()
44
+ await db.refresh(item)
45
+ return item
46
+
47
+
48
+ async def delete_item(db: AsyncSession, item: Item) -> None:
49
+ await db.delete(item)
50
+ await db.commit()