teaql 0.2.2__tar.gz → 0.2.4__tar.gz

{teaql-0.2.2 → teaql-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teaql
-Version: 0.2.2
+Version: 0.2.4
 Summary: TeaQL Runtime and Data Service for Python
 Author: TeaQL
 License-Expression: Apache-2.0

{teaql-0.2.2 → teaql-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "teaql"
-version = "0.2.2"
+version = "0.2.4"
 description = "TeaQL Runtime and Data Service for Python"
 readme = "README.md"
 requires-python = ">=3.10"

{teaql-0.2.2 → teaql-0.2.4}/src/teaql/core/mutation.py

@@ -8,6 +8,8 @@ class TraceNode:
     entity_type: str = ""
     entity_id: Optional[int] = None
     comment: str = ""
+    kind: str = "entity"
+    name: str = ""
 
 @dataclass
 class InsertCommand:
@@ -146,4 +148,3 @@ class MutationRequest:
     @classmethod
     def Batch(cls, cmds: List['MutationRequest']) -> 'MutationRequest':
         return cls(cmds)
-

{teaql-0.2.2 → teaql-0.2.4}/src/teaql/data_service/__init__.py

@@ -67,6 +67,8 @@ class ExecutionMetadata:
     result_count: Optional[int] = None
     trace_chain: List[TraceNode] = field(default_factory=list)
     comment: Optional[str] = None
+    purpose: Optional[str] = None
+    audit_reason: Optional[str] = None
     backend_request_id: Optional[str] = None
     debug_query: Optional[str] = None
 

{teaql-0.2.2 → teaql-0.2.4}/src/teaql/runtime/audit.py

@@ -25,6 +25,8 @@ class RawAuditEvent:
     entity_id: Any
     changes: tuple[AuditFieldChange, ...]
     trace_chain: tuple[Any, ...] = field(default_factory=tuple)
+    actor: Optional[str] = None
+    category: Optional[str] = None
 
     def safe(self, mask_fields: List[str], max_length: Optional[int]) -> "SafeAuditEvent":
         fields = []
@@ -37,7 +39,10 @@ class RawAuditEvent:
             if truncated:
                 value = "*" * max_length if max_length <= 3 else value[:max_length - 3] + "..."
             fields.append(SafeAuditField(change.field, value, masked, truncated))
-        return SafeAuditEvent(self.kind, self.entity, self.entity_id, tuple(fields), self.trace_chain)
+        return SafeAuditEvent(
+            self.kind, self.entity, self.entity_id, tuple(fields), self.trace_chain,
+            self.actor, self.category,
+        )
 
 
 @dataclass(frozen=True)
@@ -55,6 +60,8 @@ class SafeAuditEvent:
     entity_id: Any
     fields: tuple[SafeAuditField, ...]
     trace_chain: tuple[Any, ...] = field(default_factory=tuple)
+    actor: Optional[str] = None
+    category: Optional[str] = None
 
 
 def _mask(value: str) -> str:

{teaql-0.2.2 → teaql-0.2.4}/src/teaql/runtime/context.py

@@ -78,6 +78,8 @@ _default_id_set_store = InMemoryIdSetStore()
 class UserContext:
     def __init__(self):
         self._resources: Dict[str, Any] = {}
+        self._resources["sql_log_options"] = SqlLogOptions.all()
+        self._resources["diagnostic_sql_log_sink"] = TextDiagnosticSqlLogSink()
         self._metadata: Optional[Any] = None
         self._user_identifier: str = ""
         self._entities: List[Any] = []
@@ -437,6 +439,8 @@ class UserContext:
         if provider:
             from ._schema_capability import SCHEMA_CAPABILITY
             await provider._ensure_schema(self, SCHEMA_CAPABILITY)
+            for bootstrap in self.get_resource("_teaql_generated_bootstraps") or ():
+                await bootstrap(self)
         else:
             raise Exception("missing schema provider")
 
@@ -618,7 +622,7 @@ class UserContext:
     def sql_log_options(self) -> 'SqlLogOptions':
         opts = self.get_resource("sql_log_options")
         if not opts:
-            opts = SqlLogOptions.disabled()
+            opts = SqlLogOptions.all()
             self.insert_resource("sql_log_options", opts)
         return opts
 
@@ -645,6 +649,14 @@ class UserContext:
         self.set_sql_log_options(SqlLogOptions.disabled())
         self.clear_sql_logs()
 
+    def disable_select_sql_log(self):
+        options = self.sql_log_options()
+        self.set_sql_log_options(SqlLogOptions(False, options.mutation))
+
+    def disable_mutation_sql_log(self):
+        options = self.sql_log_options()
+        self.set_sql_log_options(SqlLogOptions(options.select, False))
+
     def sql_logs(self) -> List['SqlLogEntry']:
         return self._resources.get("sql_logs", [])
 
@@ -679,6 +691,10 @@ class UserContext:
         ended_at = getattr(metadata, 'ended_at', started_at)
         entry = SqlLogEntry(
             operation=op,
+            comment=getattr(metadata, 'comment', None),
+            purpose=getattr(metadata, 'purpose', None),
+            audit_reason=getattr(metadata, 'audit_reason', None),
+            trace_path=list(getattr(metadata, 'trace_chain', [])),
             sql=getattr(metadata, 'parameterized_sql', ''),
             params=list(getattr(metadata, 'parameters', [])),
             debug_sql=getattr(metadata, 'debug_query', '') or '',
@@ -719,6 +735,10 @@ class UserContext:
         
         entry = SqlLogEntry(
             operation=operation,
+            comment=None,
+            purpose=None,
+            audit_reason=None,
+            trace_path=[],
             sql=getattr(query, 'sql', ""),
             params=getattr(query, 'params', []),
             debug_sql=debug_sql,
@@ -944,8 +964,8 @@ class SqlLogOperation(Enum):
 
 @dataclass
 class SqlLogOptions:
-    select: bool = False
-    mutation: bool = False
+    select: bool = True
+    mutation: bool = True
 
     @classmethod
     def disabled(cls) -> 'SqlLogOptions':
@@ -969,6 +989,10 @@ class SqlLogOptions:
 @dataclass
 class SqlLogEntry:
     operation: SqlLogOperation
+    comment: Optional[str]
+    purpose: Optional[str]
+    audit_reason: Optional[str]
+    trace_path: List[Any]
     sql: str
     params: List[Any]
     debug_sql: str
@@ -982,7 +1006,7 @@ class SqlLogEntry:
     result_summary: str
 
 class DiagnosticSqlLogSink:
-    """Explicit value-bearing diagnostic SQL destination; never installed by default."""
+    """Value-bearing diagnostic SQL destination; the text sink is installed by default."""
     def write(self, entry: SqlLogEntry) -> None:
         raise NotImplementedError
 
@@ -994,7 +1018,10 @@ class TextDiagnosticSqlLogSink(DiagnosticSqlLogSink):
         elapsed_us = int(entry.elapsed.total_seconds() * 1_000_000) if entry.elapsed else 0
         self._writer(
             f"[TeaQL SQL][{entry.operation.name.lower()}][{elapsed_us}us] "
-            f"{entry.result_summary}\n{entry.debug_sql}"
+            f"{entry.result_summary} comment={entry.comment!r} purpose={entry.purpose!r} "
+            f"auditReason={entry.audit_reason!r} tracePath={entry.trace_path!r}\n"
+            f"Parameterized SQL: {entry.sql} params={entry.params!r}\n"
+            f"Debug SQL: {entry.debug_sql}"
         )
 
 @dataclass

{teaql-0.2.2 → teaql-0.2.4}/src/teaql/runtime/module.py

@@ -8,6 +8,7 @@ class RuntimeModule:
         self._dependencies: Dict[str, Any] = {}
         self._audit_sinks: List[Any] = []
         self._checkers: Dict[str, Any] = {}
+        self._generated_bootstraps: List[Any] = []
 
     @classmethod
     def new(cls) -> 'RuntimeModule':
@@ -48,6 +49,11 @@ class RuntimeModule:
         self._checkers[entity] = checker
         return self
 
+    def generated_bootstrap(self, bootstrap: Any) -> 'RuntimeModule':
+        """Register generated typed data bootstrap; invoked only by ensure_schema()."""
+        self._generated_bootstraps.append(bootstrap)
+        return self
+
     def and_module(self, other: 'RuntimeModule') -> 'RuntimeModule':
         combined = RuntimeModule.new()
         combined._entities = [*self._entities, *other._entities]
@@ -55,6 +61,10 @@ class RuntimeModule:
         combined._dependencies = {**self._dependencies, **other._dependencies}
         combined._audit_sinks = [*self._audit_sinks, *other._audit_sinks]
         combined._checkers = {**self._checkers, **other._checkers}
+        combined._generated_bootstraps = [
+            *self._generated_bootstraps,
+            *other._generated_bootstraps,
+        ]
         combined._initial_graphs = [
             *getattr(self, '_initial_graphs', []),
             *getattr(other, '_initial_graphs', []),
@@ -78,6 +88,7 @@ class RuntimeModule:
                 context.add_root_graph(graph)
         context.insert_resource("entities", self._entities)
         context.insert_resource("behaviors", self._behaviors)
+        context.insert_resource("_teaql_generated_bootstraps", tuple(self._generated_bootstraps))
         if self._checkers:
             checkers = dict(self._checkers)
             class GeneratedCheckerRegistry:

{teaql-0.2.2 → teaql-0.2.4}/src/teaql/sql/executor.py

@@ -16,7 +16,7 @@ from teaql.data_service import (
     DataServiceOperation, StreamChunk
 )
 from teaql.core.mutation import (
-    InsertCommand, UpdateCommand, DeleteCommand, RecoverCommand
+    InsertCommand, UpdateCommand, DeleteCommand, RecoverCommand, TraceNode
 )
 from .types import CompiledQuery, SqlCompileError
 from .dialect import SqlDialect
@@ -187,10 +187,19 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
         execution_query, retained_order, retained_empty = await self._prepare_id_set_page(context, request.query)
         if retained_empty:
             now = datetime.now()
+            provider = str(self.dialect.kind()).lower()
             metadata = ExecutionMetadata(
-                backend="sql", operation=DataServiceOperation.Query,
+                backend=provider, operation=DataServiceOperation.Query,
                 started_at=now, ended_at=now, result_count=0,
-                trace_chain=request.trace_chain, comment=request._comment,
+                trace_chain=[
+                    TraceNode(kind="operation", name="query", comment="query"),
+                    TraceNode(kind="request", name=request.query.entity,
+                              comment=request.query.entity),
+                    *request.trace_chain,
+                    TraceNode(kind="provider", name=provider, comment=provider),
+                    TraceNode(kind="sql", name="select", comment="select"),
+                ],
+                comment=request._comment, purpose=request._purpose,
             )
             if context is not None:
                 context.record_metadata_log(metadata)
@@ -227,8 +236,8 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
         except Exception as e:
             raise TransportError(e)
 
-        await self._enhance_relations(context, rows, request.query)
-        await self._enhance_relation_aggregates(context, rows, request.query)
+        await self._enhance_relations(context, rows, request)
+        await self._enhance_relation_aggregates(context, rows, request)
         if retained_order:
             by_id = {int(row["id"]): row for row in rows if row.get("id") is not None}
             rows = [by_id[entity_id] for entity_id in retained_order if entity_id in by_id]
@@ -274,16 +283,25 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
         
         end = datetime.now()
         
+        provider = str(self.dialect.kind()).lower()
+        trace_path = [
+            TraceNode(kind="operation", name="query", comment="query"),
+            TraceNode(kind="request", name=request.query.entity, comment=request.query.entity),
+            *request.trace_chain,
+            TraceNode(kind="provider", name=provider, comment=provider),
+            TraceNode(kind="sql", name="select", comment="select"),
+        ]
         metadata = ExecutionMetadata(
-            backend="sql",
+            backend=provider,
             operation=DataServiceOperation.Query,
             started_at=start,
             ended_at=end,
             parameterized_sql=compiled.sql_with_comment(),
             parameters=list(compiled.params),
             result_count=len(rows),
-            trace_chain=request.trace_chain,
+            trace_chain=trace_path,
             comment=request._comment,
+            purpose=request._purpose,
             debug_query=compiled.debug_sql(self.dialect.kind())
         )
         if context is not None:
@@ -393,7 +411,8 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
                  _canonical_id_set_value(normalized))
         return "teaql:id-set:v1:" + hashlib.sha256(repr(scope).encode("utf-8")).hexdigest()
 
-    async def _enhance_relations(self, context, parents: List[Dict[str, Any]], query: SelectQuery) -> None:
+    async def _enhance_relations(self, context, parents: List[Dict[str, Any]], request: QueryRequest) -> None:
+        query = request.query
         if not parents or not query.relations:
             return
         parent_desc = self.schema_provider.get_entity(query.entity)
@@ -433,7 +452,11 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
                         probe.and_filter(BinaryExpr(
                             ColumnExpr(relation.foreign_key), BinaryOp.Eq,
                             ValueExpr(Value.from_any(parent_id))))
-                        children.extend((await self.query(context, QueryRequest(probe))).rows)
+                        child_trace = [*request.trace_chain, TraceNode(
+                            kind="relation", name=f"{query.entity}.{load.name}",
+                            comment=load.name)]
+                        children.extend((await self.query(context, QueryRequest(
+                            probe, child_trace, request._comment, request._purpose))).rows)
                     selected_plan = "bounded_probes"
                     probe_count = len(parent_ids)
                 else:
@@ -442,7 +465,11 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
                         ColumnExpr(relation.foreign_key), BinaryOp.In, ValueExpr(values)))
                     if limited:
                         child_query.partition_by_field(relation.foreign_key)
-                    children = (await self.query(context, QueryRequest(child_query))).rows
+                    child_trace = [*request.trace_chain, TraceNode(
+                        kind="relation", name=f"{query.entity}.{load.name}",
+                        comment=load.name)]
+                    children = (await self.query(context, QueryRequest(
+                        child_query, child_trace, request._comment, request._purpose))).rows
                     selected_plan = "window" if limited else "batch"
                     probe_count = 0
                 for child in children:
@@ -467,7 +494,8 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
                 relation_scope.failure(error)
                 raise
 
-    async def _enhance_relation_aggregates(self, context, parents: List[Dict[str, Any]], query: SelectQuery) -> None:
+    async def _enhance_relation_aggregates(self, context, parents: List[Dict[str, Any]], request: QueryRequest) -> None:
+        query = request.query
         if not parents or not query.relation_aggregates:
             return
         parent_desc = self.schema_provider.get_entity(query.entity)
@@ -498,7 +526,11 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
             values = Value.List([Value.from_any(value) for value in parent_ids])
             child_query.and_filter(BinaryExpr(
                 ColumnExpr(relation.foreign_key), BinaryOp.In, ValueExpr(values)))
-            rows = (await self.query(context, QueryRequest(child_query))).rows
+            child_trace = [*request.trace_chain, TraceNode(
+                kind="relation", name=f"{query.entity}.{aggregate.relation_name}",
+                comment=aggregate.relation_name)]
+            rows = (await self.query(context, QueryRequest(
+                child_query, child_trace, request._comment, request._purpose))).rows
             child_desc = self.schema_provider.get_entity(relation.target_entity)
             foreign_property = child_desc.property_by_name(relation.foreign_key) if child_desc else None
             if foreign_property and foreign_property.column_name_val != relation.foreign_key:
@@ -668,8 +700,16 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
                     f"authoritative persisted row not found for {req_data.entity}"))
             persisted_record = persisted_rows[0]
 
+        provider = str(self.dialect.kind()).lower()
+        trace_path = [
+            TraceNode(kind="operation", name="mutation", comment="mutation"),
+            TraceNode(kind="entity", name=req_data.entity, comment=req_data.entity),
+            *request.trace_chain(),
+            TraceNode(kind="provider", name=provider, comment=provider),
+            TraceNode(kind="sql", name=op, comment=op),
+        ]
         metadata = ExecutionMetadata(
-            backend="sql",
+            backend=provider,
             operation={
                 "insert": DataServiceOperation.Insert,
                 "update": DataServiceOperation.Update,
@@ -681,8 +721,9 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
             parameterized_sql=compiled.sql_with_comment(),
             parameters=list(compiled.params),
             affected_rows=affected_rows,
-            trace_chain=request.trace_chain(),
+            trace_chain=trace_path,
             comment=request.comment(),
+            audit_reason=request.comment(),
             debug_query=compiled.debug_sql(self.dialect.kind())
         )
         if context is not None:
@@ -706,7 +747,15 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
                 kind = MutationAuditKind.RECOVERED
                 entity_id = req_data.id
                 changes = ()
-            await context.send_audit_event(RawAuditEvent(kind, req_data.entity, entity_id, changes, tuple(request.trace_chain())))
+            await context.send_audit_event(RawAuditEvent(
+                kind,
+                req_data.entity,
+                entity_id,
+                changes,
+                tuple(request.trace_chain()),
+                context.user_identifier(),
+                context.get_resource("bootstrapCategory"),
+            ))
         return MutationResult(
             affected_rows=affected_rows,
             generated_values=generated_values,
@@ -843,60 +892,6 @@ class SqlDataServiceExecutor(QueryExecutor, MutationExecutor):
             "CREATE TABLE IF NOT EXISTS teaql_id_space ("
             "type_name VARCHAR(255) NOT NULL PRIMARY KEY, "
             "current_level BIGINT NOT NULL)", []))
-        await self.ensure_initial_graphs(context)
-
-    async def ensure_initial_graphs(self, context: 'UserContext') -> None:
-        from teaql.core.mutation import InsertCommand, UpdateCommand
-        graphs = [
-            *((graph, False) for graph in context.root_graphs()),
-            *((graph, True) for graph in context.initial_graphs()),
-        ]
-        for graph, reconcile in graphs:
-            entity_name = getattr(graph, 'entity', None)
-            if not entity_name:
-                continue
-                
-            entity_desc = self.schema_provider.get_entity(entity_name)
-            if not entity_desc:
-                entities = context.get_resource("entities") or []
-                for e in entities:
-                    if getattr(e, "_name", None) == entity_name:
-                        entity_desc = e
-                        break
-            if not entity_desc:
-                continue
-                
-            values = getattr(graph, 'fields', getattr(graph, 'values', {}))
-            seed_id = values.get('id')
-            seed_id = seed_id.val if hasattr(seed_id, 'val') else seed_id
-            if seed_id is None:
-                raise ValueError(f"bootstrap graph {entity_name} must define id")
-            query = SelectQuery(entity_name).filter(BinaryExpr(
-                ColumnExpr('id'), BinaryOp.Eq, ValueExpr(Value.from_any(seed_id))))
-            current_rows = (await self._query(context, QueryRequest(query))).rows
-            if not current_rows:
-                mutation = InsertCommand(entity_name)
-                for k, v in values.items():
-                    mutation.value(k, v)
-                version_prop = next((p for p in getattr(entity_desc, 'properties', [])
-                    if getattr(p, '_is_version', False) or getattr(p, 'is_version_val', False)), None)
-                if version_prop is not None and version_prop.name not in mutation.values:
-                    mutation.value(version_prop.name, 1)
-                await self.transport.execute_sql(self.dialect.compile_insert(entity_desc, mutation))
-            elif reconcile:
-                current = current_rows[0]
-                changed = {k: v for k, v in values.items() if k != 'id'
-                    and current.get(k) != (v.val if hasattr(v, 'val') else v)}
-                if changed:
-                    mutation = UpdateCommand(entity_name, Value.from_any(seed_id))
-                    for k, v in changed.items():
-                        mutation.value(k, v)
-                    version = current.get('version')
-                    version = version.val if hasattr(version, 'val') else version
-                    if version is not None:
-                        mutation.expected_version(int(version))
-                    await self.transport.execute_sql(self.dialect.compile_update(entity_desc, mutation))
-            await self.ensure_id_floor(entity_name, int(seed_id))
 
     async def begin(self, context: 'UserContext') -> 'teaql.data_service.Transaction':
         if not isinstance(self.transport, SqlTransactionTransport):

{teaql-0.2.2 → teaql-0.2.4}/src/teaql.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teaql
-Version: 0.2.2
+Version: 0.2.4
 Summary: TeaQL Runtime and Data Service for Python
 Author: TeaQL
 License-Expression: Apache-2.0