terp-cli 0.36.1__tar.gz → 0.37.0__tar.gz

{terp_cli-0.36.1 → terp_cli-0.37.0}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.5
 Name: terp-cli
-Version: 0.36.1
+Version: 0.37.0
 Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
 Project-URL: Repository, https://github.com/AITT-NL/terp-framework
 Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
 License-Expression: Apache-2.0
 Requires-Python: >=3.13
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: terp-arch==0.36.1
-Requires-Dist: terp-core==0.36.1
-Requires-Dist: terp-migrations==0.36.1
+Requires-Dist: terp-arch==0.37.0
+Requires-Dist: terp-core==0.37.0
+Requires-Dist: terp-migrations==0.37.0
 Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.36.1; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.36.1; extra == 'jobs'
+Requires-Dist: terp-cap-outbox==0.37.0; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.37.0; extra == 'jobs'
 Provides-Extra: release
 Requires-Dist: cryptography>=46; extra == 'release'
 Requires-Dist: packaging>=24; extra == 'release'
-Requires-Dist: terp-cap-egress==0.36.1; extra == 'release'
+Requires-Dist: terp-cap-egress==0.37.0; extra == 'release'
 Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.36.1; extra == 'scheduler'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.37.0; extra == 'scheduler'
 Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.36.1; extra == 'worker'
+Requires-Dist: terp-cap-outbox==0.37.0; extra == 'worker'

{terp_cli-0.36.1 → terp_cli-0.37.0}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.36.1"
+version = "0.37.0"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.36.1",
+    "terp-core==0.37.0",
     # `terp migrate` delegates to terp-migrations (lazily imported), keeping Alembic
     # off the path for `terp inspect` / `terp guide` while making migrations work.
-    "terp-migrations==0.36.1",
+    "terp-migrations==0.37.0",
     # `terp guide rules` projects the live rule registry; terp-arch is imported lazily
     # (only when that topic is rendered), so it stays off the common `terp guide` path.
-    "terp-arch==0.36.1",
+    "terp-arch==0.37.0",
     # `terp verify --only env-seams` and `terp smoke` read the compose profiles as data
     # (anchors and `<<:` merge keys resolved), so both answer without a Docker daemon or
     # even the `docker` binary. Declared explicitly rather than leant on: every app
@@ -29,11 +29,11 @@ dependencies = [
 # or a scheduler engine into apps that only use inspect/check/migrate. Deployments can select
 # one process role, while `jobs` is the convenient complete jobs-process bundle.
 [project.optional-dependencies]
-worker = ["terp-cap-outbox==0.36.1"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.36.1"]
+worker = ["terp-cap-outbox==0.37.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.37.0"]
 jobs = [
-    "terp-cap-outbox==0.36.1",
-    "terp-cap-scheduler-apscheduler==0.36.1",
+    "terp-cap-outbox==0.37.0",
+    "terp-cap-scheduler-apscheduler==0.37.0",
 ]
 # `terp release` and `terp promote` (ADR 0187): the DSSE signature (cryptography), the lock's
 # markers (packaging), and the one declared way to a registry, an index and the vulnerability
@@ -42,7 +42,7 @@ jobs = [
 release = [
     "cryptography>=46",
     "packaging>=24",
-    "terp-cap-egress==0.36.1",
+    "terp-cap-egress==0.37.0",
 ]
 
 [project.scripts]

{terp_cli-0.36.1 → terp_cli-0.37.0}/src/terp/cli/__init__.py

@@ -82,21 +82,24 @@ _GUIDE_TOPICS: dict[str, str] = {
 Add a module (the "10-minute module")
 
 1) models.py   table model (inherit BaseTable; never redeclare id/created_at/version)
-     from terp.core import BaseTable
+     from datetime import datetime
+     from terp.core import BaseTable, UtcDateTime
      from sqlmodel import Field
      class Invoice(BaseTable, table=True):
          number: str = Field(max_length=50, index=True, unique=True)
          amount_cents: int
+         issued_at: datetime = Field(sa_type=UtcDateTime())   # an instant, stored as UTC
 
 2) schemas.py  DTOs (cap every input string; the Read DTO is what the API returns)
      from terp.core import BaseSchema, BaseUpdateSchema
      class InvoiceCreate(BaseSchema):
          number: str = Field(max_length=50)
          amount_cents: int
+         issued_at: datetime
      class InvoiceUpdate(BaseUpdateSchema):   # `version` is required (optimistic concurrency)
          amount_cents: int | None = None
      class InvoiceRead(BaseSchema):           # NOT the table model
-         id: uuid.UUID; number: str; amount_cents: int; version: int
+         id: uuid.UUID; number: str; amount_cents: int; issued_at: datetime; version: int
 
 3) service.py  business logic (CRUD is inherited and audited)
      from terp.core import BaseService
@@ -998,6 +1001,58 @@ Object-level (per-row) authorization (OwnedMixin)
   apply_object_authz does not restrict a row with no ownership trait, so the job body
   itself would run fine. The clause is a judgement about the DESIGN, enforced before the
   app serves anything -- not a description of what the write boundary would do.
+""",
+    "aggregates": """\
+Aggregates: counts and sums declared on the service, like filters (ADR 0204)
+
+- The problem: a statistics screen counts and sums the rows its lists read. A hand-built
+  select(func.count(...)).group_by(...) over a soft-delete or tenant model is what
+  reads_use_base_query refuses, and the workaround (an aggregate over a subquery of
+  base_query()) makes every module solve calendar days, bounds and grouping on its own.
+- Declare what may be counted and summed, and by what, beside filterable and sortable:
+      from terp.core import Dimension, FilterField, Measure, TimeBucket
+      class InvoiceService(BaseService[Invoice, InvoiceCreate, InvoiceUpdate]):
+          model = Invoice
+          filterable = (FilterField("customer_id", Invoice.customer_id),)
+          measures = (Measure("invoices"), Measure("revenue", Invoice.amount, op="sum"))
+          dimensions = (Dimension("status", Invoice.status),)
+          time_buckets = (TimeBucket("issued", Invoice.issued_at, steps=("day", "month")),)
+  op is one of count, count_distinct, sum, avg, min, max. A dimension groups by a
+  column's own values; an expression is a column the model declares, or a database view.
+- The route takes the capped query and returns a page typed by the declarations:
+      from terp.core import Page, SessionDep, StatisticsQueryDep
+      @router.get("/statistics", response_model=Page[InvoiceService.statistics_model()])
+      def invoice_statistics(query: StatisticsQueryDep, session: SessionDep, customer_id: uuid.UUID | None = None):
+          return InvoiceService().aggregate_page(session, query, filters={"customer_id": customer_id})
+  The caller asks ?measures=invoices&measures=revenue&by=status&sort=-revenue, and for a
+  series &bucket=issued&start=2026-01-01&end=2026-12-31&zone=Europe/Amsterdam&step=month.
+- Each group carries its dimensions, its measures and, with a step, its series: one point
+  per calendar step of the zone, empty steps counting zero, each with its local date (label
+  a step by date, not by re-zoning start). total counts the groups, so "the top eight" is
+  limit=8 and the rest are still counted. A Numeric sum arrives as a decimal string.
+- A day is the zone's own, so a day that daylight saving shortens keeps its real length. A
+  week starts on Monday; a series may start or end part way through a week or month.
+- Everything undeclared is refused with a 400 that lists what is declared: a measure, a
+  dimension, a time bucket, a step, a sort key, a filter. A page holds at most max_groups
+  (100); a series at most the bucket's max_buckets (366); a page at most max_points (10,000)
+  groups times steps. Each cap refuses, never clamps, and names what would fit.
+- Personal data stays personal. A Dimension or a TimeBucket over a field declared
+  Personal(...), and a sum, avg, min or max over one, is refused when the class is defined:
+  over a group of one each is that person's value. count and count_distinct may run over
+  personal data. A statistic is never narrowed by a filter over a personal field (counts
+  under a contains filter would spell out an address); the list keeps its filter.
+- A read that is not a service's (a capability's own table) uses the same seam directly:
+      from terp.core import Statistics, aggregate, group_model
+      STATS = Statistics(measures=(Measure("events"),), dimensions=(...,), time_buckets=(...,))
+      groups, total = aggregate(session, select(AuditEvent), STATS, measures=["events"], ...)
+- The runtime half: the request session scopes every ORM read, aggregates included, and
+  refuses with UnscopedReadError (a 500) a SELECT that reads a row-scoped table through Core
+  - Model.__table__.c.x, a Core join or subquery over it, a Core alias, table("name"),
+  literal SQL in a FROM - because there is no mapped entity in that SELECT to attach the
+  scope to. A many-to-many whose link table is row-scoped is refused the same way: map the
+  link as an association object.
+- On SQLite a timestamp is stored as its wall time without its offset: write instants in UTC
+  (every timestamp the framework stamps already is) and the steps are exact on both dialects.
 """,
     "leases": """\
 Leases: expiring, fenced custody of work (leases capability)

{terp_cli-0.36.1 → terp_cli-0.37.0}/src/terp/cli/service_accounts.py

@@ -97,12 +97,12 @@ def create_service_account_command(
 
 
 def _as_utc(moment: datetime.datetime) -> datetime.datetime:
-    """A stored timestamp as aware UTC.
+    """A timestamp as aware UTC; a naive one is taken as UTC.
 
-    PostgreSQL round-trips a timezone-aware column aware; SQLite returns it NAIVE, and a
-    naive/aware comparison raises rather than answers. The service resolves the same
-    ambiguity the same way for its expiry check — a naive stamp is UTC, because UTC is
-    the only thing this capability ever writes.
+    A naive/aware comparison raises rather than answers. The account's timestamps are
+    ``UtcDateTime`` columns (ADR 0205), so a value read back from them is aware already
+    and this changes nothing for it; it keeps a naive value from anywhere else from
+    raising.
     """
     return moment if moment.tzinfo is not None else moment.replace(tzinfo=datetime.UTC)