velocity-python 0.1.10__tar.gz → 0.1.12__tar.gz

{velocity_python-0.1.10/src/velocity_python.egg-info → velocity_python-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.10
+Version: 0.1.12
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.10 → velocity_python-0.1.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.10"
+version = "0.1.12"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.10 → velocity_python-0.1.12}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.10"
+__version__ = version = "0.1.12"
 
 import importlib as _importlib
 

{velocity_python-0.1.10 → velocity_python-0.1.12}/src/velocity/db/core/row.py

@@ -1,6 +1,5 @@
 import pprint
 import time as _time
-import warnings
 from collections.abc import MutableMapping
 from velocity.db.exceptions import DbColumnMissingError
 
@@ -9,7 +8,7 @@ from velocity.db.exceptions import DbColumnMissingError
 # intercepted by __getattr__ / __setattr__.
 _INTERNAL_ATTRS = frozenset({
     "table", "pk", "_cache", "_column_set", "_batching", "_pending",
-    "_cache_ttl", "_cache_time", "_no_cache",
+    "_cache_ttl", "_cache_time", "_no_cache", "_dirty_tracking", "_dirty",
 })
 
 
@@ -25,7 +24,7 @@ class Row(MutableMapping):
     write-through (immediate UPDATE) and also update the local cache.
     """
 
-    def __init__(self, table, key, lock=None, cache_ttl=None, no_cache=False):
+    def __init__(self, table, key, lock=None, cache_ttl=None, no_cache=False, dirty_tracking=False):
         if isinstance(table, str):
             raise Exception("Table parameter must be a `table` instance.")
         object.__setattr__(self, "table", table)
@@ -48,6 +47,8 @@ class Row(MutableMapping):
         object.__setattr__(self, "_cache_ttl", cache_ttl)
         object.__setattr__(self, "_cache_time", None)
         object.__setattr__(self, "_no_cache", no_cache)
+        object.__setattr__(self, "_dirty_tracking", dirty_tracking)
+        object.__setattr__(self, "_dirty", {})
         if lock:
             self.lock()
 
@@ -78,6 +79,8 @@ class Row(MutableMapping):
         object.__setattr__(row, "_cache_ttl", None)
         object.__setattr__(row, "_cache_time", _time.monotonic())
         object.__setattr__(row, "_no_cache", False)
+        object.__setattr__(row, "_dirty_tracking", False)
+        object.__setattr__(row, "_dirty", {})
         return row
 
     # ------------------------------------------------------------------
@@ -144,6 +147,13 @@ class Row(MutableMapping):
                 self._cache[key] = val
                 object.__setattr__(self, "_column_set", None)
             return
+        if self._dirty_tracking:
+            self._dirty[key] = val
+            # Update local cache optimistically so reads see the dirty value
+            if self._cache is not None:
+                self._cache[key] = val
+                object.__setattr__(self, "_column_set", None)
+            return
         self.table.update_or_insert({key: val}, pk=self.pk)
         # Invalidate cache so trigger-computed columns are re-fetched
         object.__setattr__(self, "_cache", None)
@@ -394,6 +404,55 @@ class Row(MutableMapping):
         """
         return _BatchContext(self)
 
+    def save(self):
+        """Flush accumulated dirty-tracking changes to the database.
+
+        When ``dirty_tracking=True``, assignments to the row accumulate
+        in memory instead of writing through immediately.  Call
+        ``.save()`` to flush them all in a single UPDATE::
+
+            row = Row(table, 1, dirty_tracking=True)
+            row["name"] = "John"
+            row["email"] = "john@example.com"
+            row.save()  # Single UPDATE with both columns
+
+        Returns ``self`` for chaining.
+
+        Raises:
+            RuntimeError: If dirty tracking is not enabled on this row.
+        """
+        if not self._dirty_tracking:
+            raise RuntimeError(
+                "save() requires dirty_tracking=True. "
+                "Use Row(table, key, dirty_tracking=True) or row.update({...})."
+            )
+        dirty = self._dirty
+        object.__setattr__(self, "_dirty", {})
+        if dirty:
+            self.table.update_or_insert(dirty, pk=self.pk)
+            # Invalidate cache so trigger-computed columns are re-fetched
+            object.__setattr__(self, "_cache", None)
+            object.__setattr__(self, "_column_set", None)
+        return self
+
+    @property
+    def is_dirty(self):
+        """Return True if there are unsaved dirty-tracking changes."""
+        return bool(self._dirty)
+
+    def discard(self):
+        """Discard accumulated dirty-tracking changes without writing to DB.
+
+        Also invalidates the cache so the next read re-fetches from the
+        database, undoing any optimistic cache updates.
+
+        Returns ``self`` for chaining.
+        """
+        object.__setattr__(self, "_dirty", {})
+        object.__setattr__(self, "_cache", None)
+        object.__setattr__(self, "_column_set", None)
+        return self
+
     def touch(self):
         """
         Update sys_modified to current timestamp.
@@ -473,5 +532,7 @@ class _BatchContext:
 
         if pending:
             row.table.update_or_insert(pending, pk=row.pk)
-            # Cache was already updated optimistically in __setitem__
+            # Invalidate cache so trigger-computed columns are re-fetched
+            object.__setattr__(row, "_cache", None)
+            object.__setattr__(row, "_column_set", None)
         return False

{velocity_python-0.1.10 → velocity_python-0.1.12}/src/velocity/db/migrations.py

@@ -25,14 +25,12 @@ from __future__ import annotations
 
 import hashlib
 import inspect
-import logging
-import os
 import importlib
 import importlib.util
+import logging
 import time
-from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Tuple
+from typing import Any, Callable, Dict, List, Optional
 
 logger = logging.getLogger("velocity.db.migrations")
 
@@ -102,14 +100,17 @@ class MigrationRunner:
     """
     Discovers, applies, and rolls back schema migrations.
 
-    Migrations are tracked in a ``velocity_migrations`` table with columns:
+    Migrations are tracked in a ``velocity_migrations`` table managed by
+    velocity (with standard system columns like ``sys_id``, ``sys_created``,
+    etc.).  User columns:
 
-    - ``version`` (INT, PRIMARY KEY) — migration version number
+    - ``version`` (INT) — migration version number
     - ``description`` (TEXT) — human-readable description
-    - ``applied_at`` (TIMESTAMPTZ) — when the migration was applied
     - ``checksum`` (TEXT) — SHA-256 of the migration function source
     - ``execution_ms`` (INT) — how long the migration took in milliseconds
 
+    The ``sys_created`` system column serves as the applied-at timestamp.
+
     Args:
         engine: A velocity Engine instance.
         migrations_dir: Optional path to a directory containing migration .py files.
@@ -147,34 +148,23 @@ class MigrationRunner:
         """Create the velocity_migrations tracking table if it doesn't exist."""
         table = tx.table(TRACKING_TABLE)
         if not table.exists():
-            # Use raw SQL to avoid velocity system columns — we manage our own schema
-            tx.execute(
-                f"""
-                CREATE TABLE IF NOT EXISTS {TRACKING_TABLE} (
-                    version     INTEGER PRIMARY KEY,
-                    description TEXT NOT NULL DEFAULT '',
-                    applied_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-                    checksum    TEXT NOT NULL DEFAULT '',
-                    execution_ms INTEGER NOT NULL DEFAULT 0
-                )
-                """,
-                cursor=tx.cursor(),
-            )
+            table.create(columns={
+                "version": int,
+                "description": str,
+                "checksum": str,
+                "execution_ms": int,
+            })
             logger.info("Created tracking table: %s", TRACKING_TABLE)
 
     def _get_applied_versions(self, tx) -> Dict[int, Dict[str, Any]]:
         """Return dict of {version: {description, applied_at, checksum, execution_ms}}."""
         self._ensure_tracking_table(tx)
-        result = tx.execute(
-            f"SELECT version, description, applied_at, checksum, execution_ms "
-            f"FROM {TRACKING_TABLE} ORDER BY version",
-            cursor=tx.cursor(),
-        )
+        table = tx.table(TRACKING_TABLE)
         applied = {}
-        for row in result.all():
+        for row in table.select(orderby="version").all():
             applied[row["version"]] = {
                 "description": row["description"],
-                "applied_at": row["applied_at"],
+                "applied_at": row["sys_created"],
                 "checksum": row["checksum"],
                 "execution_ms": row["execution_ms"],
             }
@@ -182,20 +172,18 @@ class MigrationRunner:
 
     def _record_migration(self, tx, version: int, description: str, checksum: str, execution_ms: int) -> None:
         """Insert a record into the tracking table."""
-        tx.execute(
-            f"INSERT INTO {TRACKING_TABLE} (version, description, checksum, execution_ms) "
-            f"VALUES (%s, %s, %s, %s)",
-            (version, description, checksum, execution_ms),
-            cursor=tx.cursor(),
-        )
+        table = tx.table(TRACKING_TABLE)
+        table.insert({
+            "version": version,
+            "description": description,
+            "checksum": checksum,
+            "execution_ms": execution_ms,
+        })
 
     def _remove_migration_record(self, tx, version: int) -> None:
         """Delete a record from the tracking table."""
-        tx.execute(
-            f"DELETE FROM {TRACKING_TABLE} WHERE version = %s",
-            (version,),
-            cursor=tx.cursor(),
-        )
+        table = tx.table(TRACKING_TABLE)
+        table.delete(where={"version": version})
 
     # ── Checksum ────────────────────────────────────────────────
 

{velocity_python-0.1.10 → velocity_python-0.1.12/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.10
+Version: 0.1.12
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.10 → velocity_python-0.1.12}/src/velocity_python.egg-info/SOURCES.txt

@@ -175,6 +175,7 @@ tests/test_psycopg3_upgrade.py
 tests/test_query_cache.py
 tests/test_row_batch_update.py
 tests/test_row_cache_staleness.py
+tests/test_row_dirty_tracking.py
 tests/test_schema_migrations.py
 tests/test_security_hardening.py
 tests/test_sqs_per_record_transactions.py

{velocity_python-0.1.10 → velocity_python-0.1.12}/tests/test_row_batch_update.py

@@ -29,6 +29,8 @@ def _make_row(cache=None, pk=None):
     object.__setattr__(row, "_cache_ttl", None)
     object.__setattr__(row, "_cache_time", None)
     object.__setattr__(row, "_no_cache", False)
+    object.__setattr__(row, "_dirty_tracking", False)
+    object.__setattr__(row, "_dirty", {})
     return row
 
 

velocity_python-0.1.12/tests/test_row_dirty_tracking.py

@@ -0,0 +1,193 @@
+"""
+Tests for R3 — Row dirty-tracking mode with .save().
+
+When ``dirty_tracking=True``, writes accumulate in memory and are flushed
+to the database only on explicit ``.save()``.
+"""
+
+import pytest
+from unittest.mock import MagicMock
+
+from velocity.db.core.row import Row
+
+
+def _make_dirty_row(cache=None, pk=None):
+    """Create a Row with dirty_tracking=True and a mocked table."""
+    table = MagicMock()
+    table.name = "test_table"
+    table.select.return_value.as_dict.return_value.one.return_value = cache or {
+        "name": "Alice",
+        "email": "alice@example.com",
+        "sys_id": 1,
+    }
+    table.update_or_insert = MagicMock()
+
+    row = Row.__new__(Row)
+    object.__setattr__(row, "table", table)
+    object.__setattr__(row, "pk", pk or {"sys_id": 1})
+    object.__setattr__(row, "_cache", dict(cache) if cache else None)
+    object.__setattr__(row, "_column_set", None)
+    object.__setattr__(row, "_batching", False)
+    object.__setattr__(row, "_pending", {})
+    object.__setattr__(row, "_cache_ttl", None)
+    object.__setattr__(row, "_cache_time", None)
+    object.__setattr__(row, "_no_cache", False)
+    object.__setattr__(row, "_dirty_tracking", True)
+    object.__setattr__(row, "_dirty", {})
+    return row
+
+
+def _make_normal_row(cache=None, pk=None):
+    """Create a Row with dirty_tracking=False (default)."""
+    table = MagicMock()
+    table.name = "test_table"
+    table.select.return_value.as_dict.return_value.one.return_value = cache or {
+        "name": "Alice",
+        "email": "alice@example.com",
+        "sys_id": 1,
+    }
+    table.update_or_insert = MagicMock()
+
+    row = Row.__new__(Row)
+    object.__setattr__(row, "table", table)
+    object.__setattr__(row, "pk", pk or {"sys_id": 1})
+    object.__setattr__(row, "_cache", dict(cache) if cache else None)
+    object.__setattr__(row, "_column_set", None)
+    object.__setattr__(row, "_batching", False)
+    object.__setattr__(row, "_pending", {})
+    object.__setattr__(row, "_cache_ttl", None)
+    object.__setattr__(row, "_cache_time", None)
+    object.__setattr__(row, "_no_cache", False)
+    object.__setattr__(row, "_dirty_tracking", False)
+    object.__setattr__(row, "_dirty", {})
+    return row
+
+
+class TestDirtyTracking:
+
+    def test_no_db_write_on_assignment(self):
+        """Assignments should NOT trigger DB writes when dirty tracking is on."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        row.table.update_or_insert.assert_not_called()
+
+    def test_save_flushes_all_changes(self):
+        """save() should issue a single UPDATE with all accumulated changes."""
+        row = _make_dirty_row({"name": "Alice", "email": "old@test.com", "sys_id": 1})
+        row["name"] = "Bob"
+        row["email"] = "bob@test.com"
+        row.save()
+
+        row.table.update_or_insert.assert_called_once_with(
+            {"name": "Bob", "email": "bob@test.com"}, pk={"sys_id": 1}
+        )
+
+    def test_save_clears_dirty_dict(self):
+        """After save(), the dirty dict should be empty."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        assert row.is_dirty
+        row.save()
+        assert not row.is_dirty
+
+    def test_save_no_changes_is_noop(self):
+        """save() with no changes should not issue a DB call."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row.save()
+        row.table.update_or_insert.assert_not_called()
+
+    def test_reads_see_dirty_values(self):
+        """Reads should return the dirty (not-yet-saved) value."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        assert row["name"] == "Bob"
+
+    def test_is_dirty_property(self):
+        """is_dirty should reflect whether unsaved changes exist."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        assert not row.is_dirty
+        row["name"] = "Bob"
+        assert row.is_dirty
+
+    def test_discard_clears_changes(self):
+        """discard() should drop pending changes and invalidate cache."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        assert row.is_dirty
+        row.discard()
+        assert not row.is_dirty
+
+    def test_discard_invalidates_cache(self):
+        """After discard(), cache should be None so next read re-fetches."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        row.discard()
+        assert row._cache is None
+
+    def test_save_invalidates_cache(self):
+        """After save(), cache should be invalidated for trigger-computed columns."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        row.save()
+        assert row._cache is None
+
+    def test_last_write_wins(self):
+        """Multiple assignments to the same column keep the last value."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        row["name"] = "Charlie"
+        row.save()
+
+        row.table.update_or_insert.assert_called_once_with(
+            {"name": "Charlie"}, pk={"sys_id": 1}
+        )
+
+    def test_pk_write_raises(self):
+        """Writing to a PK column should raise even with dirty tracking."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        with pytest.raises(Exception, match="Cannot update a primary key"):
+            row["sys_id"] = 999
+
+    def test_attr_style_is_deferred(self):
+        """Attribute-style writes should also be deferred."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row.name = "Bob"
+        row.table.update_or_insert.assert_not_called()
+        row.save()
+        row.table.update_or_insert.assert_called_once()
+
+    def test_save_without_dirty_tracking_raises(self):
+        """save() on a normal row should raise RuntimeError."""
+        row = _make_normal_row({"name": "Alice", "sys_id": 1})
+        with pytest.raises(RuntimeError, match="dirty_tracking=True"):
+            row.save()
+
+    def test_save_returns_self(self):
+        """save() should return self for chaining."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        result = row.save()
+        assert result is row
+
+    def test_discard_returns_self(self):
+        """discard() should return self for chaining."""
+        row = _make_dirty_row({"name": "Alice", "sys_id": 1})
+        result = row.discard()
+        assert result is row
+
+    def test_constructor_parameter(self):
+        """Row can be created with dirty_tracking=True via constructor."""
+        table = MagicMock()
+        table.name = "test_table"
+        table.select.return_value.as_dict.return_value.one.return_value = {
+            "name": "Alice", "sys_id": 1,
+        }
+        row = Row(table, 1, dirty_tracking=True)
+        assert row._dirty_tracking is True
+        assert row._dirty == {}
+
+    def test_normal_row_writes_through(self):
+        """Without dirty tracking, writes still go through immediately."""
+        row = _make_normal_row({"name": "Alice", "sys_id": 1})
+        row["name"] = "Bob"
+        row.table.update_or_insert.assert_called_once()