jvspatial 0.2.1__tar.gz → 0.2.2__tar.gz

{jvspatial-0.2.1/jvspatial.egg-info → jvspatial-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jvspatial
-Version: 0.2.1
+Version: 0.2.2
 Summary: An asynchronous object-spatial Python library for persistence and business logic application layers.
 Author-email: "TrueSelph Inc." <adminh@trueselph.com>
 License: MIT
@@ -353,7 +353,7 @@ server = Server(
 - [Custom Database Guide](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/custom-database-guide.md) - Implementing custom database backends
 - [Graph Visualization](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/graph-visualization.md) - Export graphs in DOT/Mermaid formats
 - [Pagination](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/pagination.md) - ObjectPager usage
-- [Observability](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/observability.md) - Structured DB logging, slow-query threshold, MetricsRecorder, OpenTelemetry adapter
+- [Observability](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/observability.md) - Failure-only DB logging, operation/slow-call metrics, OpenTelemetry adapter
 - [Performance Benchmarks](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/benchmarks.md) - Regression-detection bench suite (pytest-benchmark + CI workflow)
 - [API Stability](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/stability.md) - Public/internal/experimental tiers and deprecation policy
 

{jvspatial-0.2.1 → jvspatial-0.2.2}/README.md

@@ -273,7 +273,7 @@ server = Server(
 - [Custom Database Guide](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/custom-database-guide.md) - Implementing custom database backends
 - [Graph Visualization](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/graph-visualization.md) - Export graphs in DOT/Mermaid formats
 - [Pagination](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/pagination.md) - ObjectPager usage
-- [Observability](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/observability.md) - Structured DB logging, slow-query threshold, MetricsRecorder, OpenTelemetry adapter
+- [Observability](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/observability.md) - Failure-only DB logging, operation/slow-call metrics, OpenTelemetry adapter
 - [Performance Benchmarks](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/benchmarks.md) - Regression-detection bench suite (pytest-benchmark + CI workflow)
 - [API Stability](https://github.com/TrueSelph/jvspatial/blob/main/docs/md/stability.md) - Public/internal/experimental tiers and deprecation policy
 

{jvspatial-0.2.1 → jvspatial-0.2.2}/jvspatial/core/context.py

@@ -587,9 +587,22 @@ class GraphContext:
         imap = _request_identity_map.get()
         if imap is not None and entity_id in imap:
             result = imap[entity_id]
+            # Identity-map entries are context-bound. A transaction replaces
+            # the request map, but callers may explicitly use another context
+            # while that map is active; do not return an entity attached to a
+            # different database handle in that case.
+            if getattr(result, "_graph_context", self) is self:
+                if self._perf_monitoring_enabled and self._perf_monitor:
+                    self._perf_monitor.record_cache_hit()
+                return result
+        # A graph transaction owns an isolated identity map. Consulting the
+        # process cache here could return an entity bound to the outer
+        # database context, causing reads to escape the transaction and
+        # writes to bypass its connection (or expose uncommitted state).
+        if self._transaction_cache_keys is not None:
             if self._perf_monitoring_enabled and self._perf_monitor:
-                self._perf_monitor.record_cache_hit()
-            return result
+                self._perf_monitor.record_cache_miss()
+            return None
         result = await self._cache.get(entity_id)
         # Track cache hit/miss
         if self._perf_monitoring_enabled and self._perf_monitor:
@@ -606,6 +619,8 @@ class GraphContext:
         imap = _request_identity_map.get()
         if imap is not None:
             imap[entity_id] = entity
+        if self._transaction_cache_keys is not None:
+            return
         await self._cache.set(entity_id, entity)
 
     async def _evict_from_cache(self, entity_id: str) -> None:
@@ -2275,7 +2290,8 @@ async def graph_transaction(database: Optional[Any] = None):
     back every write in the block.
 
     Requires a backend that exposes ``begin_transaction``,
-    ``commit_transaction``, and ``rollback_transaction`` (Postgres today).
+    ``commit_transaction``, and ``rollback_transaction`` (PostgreSQL and
+    transaction-capable MongoDB deployments).
 
     Usage:
         async with graph_transaction(db) as ctx:
@@ -2293,6 +2309,10 @@ async def graph_transaction(database: Optional[Any] = None):
             "graph_transaction requires a database with begin/commit/rollback"
         )
     txn = await db.begin_transaction()
+    if txn is None:
+        raise TransactionUnavailable(
+            "The configured deployment cannot start a native transaction"
+        )
     ctx = GraphContext(txn)
     parent_ctx = _default_context_var.get() or _module_default_context
     ctx._transaction_cache_keys = set()

{jvspatial-0.2.1 → jvspatial-0.2.2}/jvspatial/db/_observable.py

@@ -1,12 +1,10 @@
 """Observability wrapper for :class:`Database` instances.
 
 Wraps any backend (raw or already wrapped in :class:`CachingDatabase`)
-and emits, for each operation:
+and records, for each operation:
 
-1. A structured log line with the standard fields
-   ``backend`` / ``op`` / ``collection`` / ``duration_ms`` / ``result_count``
-   / ``success``. DEBUG for successful calls under the threshold;
-   WARNING for failures or calls reaching ``slow_query_ms``.
+1. A structured ERROR for failed operations. Successful operations, including
+   calls above ``slow_query_ms``, produce no log record.
 2. One metrics emission to the configured :class:`MetricsRecorder`:
    a duration histogram and a counter, both labeled with the standard
    dimensions.
@@ -63,9 +61,8 @@ from jvspatial.observability.metrics import (
 logger = logging.getLogger("jvspatial.db.observable")
 
 
-# Default slow-query threshold. Anything above 100 ms gets surfaced as
-# a WARNING so it shows up in normal log feeds without operator
-# configuration. Tunable per-instance via ``slow_query_ms``.
+# Default slow-query threshold. Calls above it increment a metric; they do not
+# generate log records. Tunable per-instance via ``slow_query_ms``.
 DEFAULT_SLOW_QUERY_MS = 100.0
 
 
@@ -83,15 +80,16 @@ def _backend_label(inner: Database) -> str:
 
 
 class ObservableDatabase(Database):
-    """Wraps a :class:`Database` with structured logging + metrics.
+    """Wrap a :class:`Database` with per-operation metrics and sparse logs.
 
     Args:
         inner: The wrapped database. May itself be wrapped (e.g. by
             :class:`~jvspatial.db._cache.CachingDatabase`).
         metrics: A :class:`MetricsRecorder`. Defaults to
             :class:`NullMetricsRecorder` (zero overhead).
-        slow_query_ms: Threshold above which the per-op log line is
-            elevated from DEBUG to WARNING. Defaults to 100ms.
+        slow_query_ms: Threshold above which successful calls increment the
+            slow-operation metric. Successful calls are not logged. Failures
+            are logged at ERROR. Defaults to 100ms.
     """
 
     def __init__(
@@ -123,7 +121,7 @@ class ObservableDatabase(Database):
         *,
         result_count_extractor: Optional[Callable[[Any], int]] = None,
     ) -> Any:
-        """Run ``coro_factory()`` while emitting a log line and metric.
+        """Run ``coro_factory()`` while recording metrics and failure logs.
 
         ``coro_factory`` is a thunk so we measure the underlying call
         only, not the time spent constructing the coroutine.
@@ -186,26 +184,24 @@ class ObservableDatabase(Database):
             "collection": collection,
             "success": success,
         }
-        log_extra = {**labels, "duration_ms": round(duration_ms, 3)}
-        if result_count is not None:
-            log_extra["result_count"] = result_count
-
-        if query_plan:
-            log_extra.update(query_plan)
-        if active_duration_s is not None:
-            log_extra["active_duration_ms"] = round(active_duration_s * 1000, 3)
-
-        # Structured log. WARNING when slow or failed, DEBUG otherwise. extra=
-        # supplies the structured fields to any handler that
-        # understands them (json formatters, structlog, etc.).
+        # Build failure-only log data lazily. Successful calls do not allocate
+        # a logging payload or format a message, even when DEBUG is enabled.
         slow = duration_ms >= self.slow_query_ms
-        msg = "db.%s on '%s' took %.2fms" % (op, collection, duration_ms)
-        if slow:
-            logger.warning("SLOW %s", msg, extra=log_extra)
-        elif not success:
-            logger.warning("FAILED %s", msg, extra=log_extra)
-        else:
-            logger.debug(msg, extra=log_extra)
+        if not success and logger.isEnabledFor(logging.ERROR):
+            log_extra = {**labels, "duration_ms": round(duration_ms, 3)}
+            if result_count is not None:
+                log_extra["result_count"] = result_count
+            if query_plan:
+                log_extra.update(query_plan)
+            if active_duration_s is not None:
+                log_extra["active_duration_ms"] = round(active_duration_s * 1000, 3)
+            logger.error(
+                "FAILED db.%s on '%s' took %.2fms",
+                op,
+                collection,
+                duration_ms,
+                extra=log_extra,
+            )
 
         # Metrics. Best-effort -- do not surface backend errors here.
         try:

{jvspatial-0.2.1 → jvspatial-0.2.2}/jvspatial/db/factory.py

@@ -278,12 +278,12 @@ def create_database(
             TTL (LRU eviction only).
         observe: When ``True``, wrap the database in an
             :class:`~jvspatial.db._observable.ObservableDatabase` that
-            emits a structured log line and one metric per operation.
+            records metrics per operation and logs failures only.
             Defaults to ``False`` (no behavior change for existing
             callers).
-        slow_query_ms: Threshold above which the per-op log line is
-            elevated to WARNING. Only meaningful when
-            ``observe=True``. Defaults to 100ms.
+        slow_query_ms: Threshold above which successful operations are
+            counted as slow in metrics. Successful operations are not
+            logged. Only meaningful when ``observe=True``. Defaults to 100ms.
         metrics: Optional :class:`~jvspatial.observability.metrics.MetricsRecorder`
             implementation. Defaults to
             :class:`~jvspatial.observability.metrics.NullMetricsRecorder`
@@ -345,9 +345,8 @@ def create_database(
         db = CachingDatabase(db, max_entries=cache_get_size, ttl_seconds=cache_get_ttl)
 
     # Optional observability layer (off by default). Applied AFTER the
-    # cache so the structured log line measures user-visible latency
-    # including cache hits/misses -- which is what SLO calculations
-    # need.
+    # cache so metrics and slow-query counters measure user-visible
+    # latency including cache hits/misses.
     if observe:
         db = ObservableDatabase(db, metrics=metrics, slow_query_ms=slow_query_ms)
 

{jvspatial-0.2.1 → jvspatial-0.2.2}/jvspatial/db/mongodb.py

@@ -1179,8 +1179,8 @@ class MongoDB(Database):
         Returns a ``MongoDBTransaction`` whose session is bound to a
         ``start_transaction`` call.  If the deployment does not support
         transactions (standalone / DocumentDB without transactions), the
-        returned object will be ``None`` and callers should fall back to
-        non-transactional writes.
+        returned object will be ``None``. Callers requiring atomicity must
+        reject that case rather than perform unprotected writes.
         """
         from jvspatial.db.transaction import MongoDBTransaction
 
@@ -1208,13 +1208,13 @@ class MongoDB(Database):
         """Commit the given transaction and end its session."""
         if txn is not None:
             await txn.commit()
-            txn.session.end_session()
+            await _resolve_driver_result(txn.session.end_session())
 
     async def rollback_transaction(self, txn) -> None:
         """Roll back the given transaction and end its session."""
         if txn is not None:
             await txn.rollback()
-            txn.session.end_session()
+            await _resolve_driver_result(txn.session.end_session())
 
     async def drop_deprecated_indexes(self, deprecated: Dict[str, List[str]]) -> None:
         """Drop indexes that have been removed or renamed in code.