velocity-python 0.1.125__tar.gz → 0.1.127__tar.gz

{velocity_python-0.1.125 → velocity_python-0.1.127}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.125
+Version: 0.1.127
 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.125 → velocity_python-0.1.127}/pyproject.toml

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

{velocity_python-0.1.125 → velocity_python-0.1.127}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.125"
+__version__ = version = "0.1.127"
 
 import importlib as _importlib
 

{velocity_python-0.1.125 → velocity_python-0.1.127}/src/velocity/db/core/jsonproxy.py

@@ -68,6 +68,22 @@ class BoundList(list):
         super().__init__(_wrap(v, ctrl) for v in iterable)
         self._ctrl = ctrl
 
+    # -- copies are plain values ---------------------------------------
+    # A copy of a bound value is a plain list with no link to the row.
+    # Without these, copy.deepcopy rebuilt the proxy through the pickle
+    # path and refilled it with __setitem__ — one flush (an UPDATE) per
+    # nested container for a read-only copy, or an AttributeError when the
+    # rebuilt controller had no flush (2026-09-28, found by a dance forms
+    # migration deep-copying a definition read from a JSONB column).
+    def __copy__(self):
+        return unwrap(self)
+
+    def __deepcopy__(self, memo):
+        return unwrap(self)
+
+    def __reduce__(self):
+        return (list, (unwrap(self),))
+
     # -- mutators ------------------------------------------------------
     def __setitem__(self, index, value):
         if isinstance(index, slice):
@@ -131,6 +147,22 @@ class BoundDict(dict):
         super().__init__({k: _wrap(v, ctrl) for k, v in mapping.items()})
         self._ctrl = ctrl
 
+    # -- copies are plain values ---------------------------------------
+    # A copy of a bound value is a plain dict with no link to the row.
+    # Without these, copy.deepcopy rebuilt the proxy through the pickle
+    # path and refilled it with __setitem__ — one flush (an UPDATE) per
+    # nested container for a read-only copy, or an AttributeError when the
+    # rebuilt controller had no flush (2026-09-28, found by a dance forms
+    # migration deep-copying a definition read from a JSONB column).
+    def __copy__(self):
+        return unwrap(self)
+
+    def __deepcopy__(self, memo):
+        return unwrap(self)
+
+    def __reduce__(self):
+        return (dict, (unwrap(self),))
+
     # -- mutators ------------------------------------------------------
     def __setitem__(self, key, value):
         super().__setitem__(key, _wrap(value, self._ctrl))

{velocity_python-0.1.125 → velocity_python-0.1.127}/src/velocity/db/maintenance.py

@@ -33,6 +33,7 @@ import os
 from typing import Iterable, List, Optional
 
 from velocity.db.servers import postgres
+from velocity.db.tunnel import apply_db_tunnel
 
 SNAPSHOT_INFIX = "-snapshot-"
 TS_FORMAT = "%Y%m%d-%H%M%S"  # sortable: lexical order == chronological order
@@ -136,12 +137,16 @@ class DatabaseMaintenance:
         return _run()
 
     def _conn_params(self) -> dict:
-        return {
-            "host": self._config.get("host") or os.environ.get("DBHost"),
-            "port": self._config.get("port") or os.environ.get("DBPort"),
-            "user": self._config.get("user") or os.environ.get("DBUser"),
-            "password": self._config.get("password") or os.environ.get("DBPassword"),
-        }
+        # the pg_dump/pg_restore/psql runs follow DB_TUNNEL like the engine does
+        return apply_db_tunnel(
+            {
+                "host": self._config.get("host") or os.environ.get("DBHost"),
+                "port": self._config.get("port") or os.environ.get("DBPort"),
+                "user": self._config.get("user") or os.environ.get("DBUser"),
+                "password": self._config.get("password")
+                or os.environ.get("DBPassword"),
+            }
+        )
 
     # ------------------------------------------------------------------ guards
     def _guard(self, db: str, action: str) -> None:

{velocity_python-0.1.125 → velocity_python-0.1.127}/src/velocity/db/servers/postgres/__init__.py

@@ -2,6 +2,7 @@ import os
 from ..base.initializer import BaseInitializer
 from velocity.db.core import engine
 from velocity.aws.ssm_config import getenv as _getenv
+from velocity.db.tunnel import apply_db_tunnel
 
 
 # Default TCP keepalive settings for PostgreSQL connections.
@@ -60,6 +61,10 @@ class PostgreSQLInitializer(BaseInitializer):
             base_config, config, **kwargs
         )
 
+        # DB_TUNNEL (operator laptops): every connection goes to the local end
+        # of a tunnel to a private server. See velocity.db.tunnel.
+        apply_db_tunnel(final_config)
+
         # Apply TCP keepalive defaults (user config takes precedence).
         for key, default_val in _DEFAULT_KEEPALIVE.items():
             final_config.setdefault(key, default_val)

velocity_python-0.1.127/src/velocity/db/tunnel.py

@@ -0,0 +1,49 @@
+"""``DB_TUNNEL``: reach a private database through a local tunnel end.
+
+An operator on a laptop cannot reach a database that has no public address;
+a tunnel (SSH ``-L``, an SSM port forward, ...) exposes it on a local port.
+Setting ``DB_TUNNEL=127.0.0.1:15433`` points every velocity PostgreSQL
+connection in the process -- engines from ``postgres.initialize()`` and the
+``pg_dump``/``pg_restore``/``psql`` runs of ``DatabaseMaintenance`` -- at that
+local end instead of the configured host. Host and port only: the database
+name and credentials still come from wherever they were configured.
+
+A tunnel forwards to ONE server, so the override applies to every connection,
+including an explicit ``config={"host": ...}``: under a tunnel, no other host
+is reachable anyway. ``sslmode=require`` still encrypts end to end;
+``verify-full`` would reject the local name, so don't combine the two.
+
+Read from ``os.environ`` only (never SSM): it describes this process's
+network path, not the application's configuration.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Mapping, Optional, Tuple
+
+DB_TUNNEL_VAR = "DB_TUNNEL"
+
+
+def db_tunnel(environ: Optional[Mapping[str, str]] = None) -> Optional[Tuple[str, str]]:
+    """``(host, port)`` from ``DB_TUNNEL``, or ``None`` when it is unset/blank.
+
+    Raises ``ValueError`` for anything that is not ``host:port`` -- a typo must
+    not silently fall back to the unreachable real host."""
+    value = (os.environ if environ is None else environ).get(DB_TUNNEL_VAR, "")
+    value = (value or "").strip()
+    if not value:
+        return None
+    host, _, port = value.rpartition(":")
+    if not host or not port.isdigit():
+        raise ValueError(f"{DB_TUNNEL_VAR} must be host:port, got {value!r}")
+    return host, port
+
+
+def apply_db_tunnel(config: dict, environ: Optional[Mapping[str, str]] = None) -> dict:
+    """Replace ``config['host']``/``config['port']`` with the tunnel's local end
+    when ``DB_TUNNEL`` is set. Mutates and returns ``config``."""
+    tunnel = db_tunnel(environ)
+    if tunnel:
+        config["host"], config["port"] = tunnel
+    return config

{velocity_python-0.1.125 → velocity_python-0.1.127}/src/velocity_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.125
+Version: 0.1.127
 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.125 → velocity_python-0.1.127}/src/velocity_python.egg-info/SOURCES.txt

@@ -69,6 +69,7 @@ src/velocity/db/__init__.py
 src/velocity/db/exceptions.py
 src/velocity/db/maintenance.py
 src/velocity/db/migrations.py
+src/velocity/db/tunnel.py
 src/velocity/db/utils.py
 src/velocity/db/core/__init__.py
 src/velocity/db/core/async_support.py
@@ -229,6 +230,7 @@ tests/test_data_service_renumber.py
 tests/test_data_service_save_as.py
 tests/test_db_credentials_ssm_cascade.py
 tests/test_db_maintenance.py
+tests/test_db_tunnel.py
 tests/test_decorators.py
 tests/test_delete_hook_fk_blocked.py
 tests/test_dirty_pipeline_fast_path.py

velocity_python-0.1.127/tests/test_db_tunnel.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""``DB_TUNNEL=host:port`` points every PostgreSQL connection in the process at
+a local tunnel end: engines from ``postgres.initialize()`` and the
+``pg_dump``/``pg_restore`` runs of ``DatabaseMaintenance``. Host and port only;
+a malformed value fails loudly instead of falling back to the real host."""
+
+import os
+import unittest
+from unittest.mock import MagicMock, patch
+
+from velocity.db import maintenance
+from velocity.db.servers import postgres as postgres_server
+from velocity.db.tunnel import DB_TUNNEL_VAR, apply_db_tunnel, db_tunnel
+
+FAKE = {
+    "DBDatabase": "app_db",
+    "DBHost": "private.rds.example.com",
+    "DBPort": "5433",
+    "DBUser": "app_user",
+    "DBPassword": "app_pass",
+}
+
+
+def _no_tunnel():
+    env = dict(os.environ)
+    env.pop(DB_TUNNEL_VAR, None)
+    return patch.dict(os.environ, env, clear=True)
+
+
+class TestParse(unittest.TestCase):
+    def test_unset_or_blank_is_none(self):
+        self.assertIsNone(db_tunnel({}))
+        self.assertIsNone(db_tunnel({DB_TUNNEL_VAR: "  "}))
+
+    def test_host_and_port(self):
+        self.assertEqual(
+            db_tunnel({DB_TUNNEL_VAR: " 127.0.0.1:15433 "}), ("127.0.0.1", "15433")
+        )
+
+    def test_malformed_raises(self):
+        for bad in ("localhost", ":15433", "127.0.0.1:", "127.0.0.1:abc"):
+            with self.subTest(bad=bad), self.assertRaises(ValueError):
+                db_tunnel({DB_TUNNEL_VAR: bad})
+
+    def test_apply_replaces_host_and_port_only(self):
+        config = {"host": "h", "port": "1", "user": "u", "dbname": "d"}
+        apply_db_tunnel(config, {DB_TUNNEL_VAR: "127.0.0.1:15433"})
+        self.assertEqual(
+            config,
+            {"host": "127.0.0.1", "port": "15433", "user": "u", "dbname": "d"},
+        )
+
+    def test_apply_without_tunnel_leaves_config(self):
+        config = {"host": "h", "port": "1"}
+        self.assertEqual(apply_db_tunnel(config, {}), {"host": "h", "port": "1"})
+
+
+class TestPostgresInitialize(unittest.TestCase):
+    def _initialize(self, config=None):
+        captured = {}
+
+        def fake_engine(driver, cfg, sql, **kwargs):
+            captured.update(cfg)
+            return MagicMock()
+
+        with (
+            patch.object(postgres_server, "_getenv", lambda key: FAKE.get(key)),
+            patch.object(postgres_server.engine, "Engine", fake_engine),
+        ):
+            postgres_server.PostgreSQLInitializer.initialize(config)
+        return captured
+
+    def test_without_tunnel_uses_configured_host(self):
+        with _no_tunnel():
+            cfg = self._initialize()
+        self.assertEqual(
+            (cfg["host"], cfg["port"]), ("private.rds.example.com", "5433")
+        )
+
+    def test_tunnel_overrides_host_and_port_keeps_credentials(self):
+        with patch.dict(os.environ, {DB_TUNNEL_VAR: "127.0.0.1:15433"}):
+            cfg = self._initialize()
+        self.assertEqual((cfg["host"], cfg["port"]), ("127.0.0.1", "15433"))
+        self.assertEqual(cfg["dbname"], "app_db")
+        self.assertEqual(cfg["user"], "app_user")
+        self.assertEqual(cfg["password"], "app_pass")
+
+    def test_tunnel_overrides_an_explicit_config_host(self):
+        # a tunnel reaches one server; any other host is unreachable anyway
+        with patch.dict(os.environ, {DB_TUNNEL_VAR: "127.0.0.1:15433"}):
+            cfg = self._initialize({"host": "other.example.com", "port": "5432"})
+        self.assertEqual((cfg["host"], cfg["port"]), ("127.0.0.1", "15433"))
+
+    def test_malformed_tunnel_fails_before_connecting(self):
+        with patch.dict(os.environ, {DB_TUNNEL_VAR: "localhost"}):
+            with self.assertRaises(ValueError):
+                self._initialize()
+
+
+class TestMaintenanceTools(unittest.TestCase):
+    def test_pg_dump_follows_the_tunnel(self):
+        m = maintenance.DatabaseMaintenance(
+            config={"host": "private.rds.example.com", "port": "5433", "user": "u"},
+            engine=MagicMock(),
+        )
+        with (
+            patch.dict(os.environ, {DB_TUNNEL_VAR: "127.0.0.1:15433"}),
+            patch.object(m, "_run_tool") as run,
+        ):
+            m.backup_to_file("app_db", "/tmp/x.dump")
+        args = run.call_args[0][0]
+        self.assertEqual(args[args.index("-h") + 1], "127.0.0.1")
+        self.assertEqual(args[args.index("-p") + 1], "15433")
+
+    def test_pg_dump_without_tunnel_uses_configured_host(self):
+        m = maintenance.DatabaseMaintenance(
+            config={"host": "private.rds.example.com", "port": "5433", "user": "u"},
+            engine=MagicMock(),
+        )
+        with _no_tunnel(), patch.object(m, "_run_tool") as run:
+            m.backup_to_file("app_db", "/tmp/x.dump")
+        args = run.call_args[0][0]
+        self.assertEqual(args[args.index("-h") + 1], "private.rds.example.com")
+
+
+if __name__ == "__main__":
+    unittest.main()

{velocity_python-0.1.125 → velocity_python-0.1.127}/tests/test_json_columns.py

@@ -423,3 +423,60 @@ class TestRowJsonTextDecode(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestProxyCopies(unittest.TestCase):
+    """A copy of a bound JSON value is a plain value: copying never
+    touches the row (2026-09-28)."""
+
+    def _bound(self):
+        from velocity.db.core import jsonproxy
+
+        writes = []
+        value = {
+            "pages": [{"ui": [{"copy": "x"}], "skippable": {"label": "s"}}],
+            "tags": ["a", ["b"]],
+        }
+        return jsonproxy.bind(value, writes.append), value, writes
+
+    def _assert_plain(self, value):
+        self.assertIn(type(value), (dict, list))
+        items = value.values() if isinstance(value, dict) else value
+        for item in items:
+            if isinstance(item, (dict, list)):
+                self._assert_plain(item)
+
+    def test_deepcopy_and_copy_are_plain_and_write_nothing(self):
+        import copy
+
+        bound, original, writes = self._bound()
+        deep = copy.deepcopy(bound)
+        shallow = copy.copy(bound)
+        self.assertEqual(deep, original)
+        self.assertEqual(shallow, original)
+        self._assert_plain(deep)
+        self._assert_plain(shallow)
+        self.assertEqual(writes, [])
+        # the copy is independent of the row
+        deep["pages"][0]["skippable"]["label"] = "changed"
+        self.assertEqual(bound["pages"][0]["skippable"]["label"], "s")
+        self.assertEqual(writes, [])
+        # nested proxies copy plain too
+        self._assert_plain(copy.deepcopy(bound["pages"]))
+        self._assert_plain(copy.copy(bound["tags"]))
+        self.assertEqual(writes, [])
+
+    def test_pickle_round_trip_is_plain(self):
+        import pickle
+
+        bound, original, writes = self._bound()
+        back = pickle.loads(pickle.dumps(bound))
+        self.assertEqual(back, original)
+        self._assert_plain(back)
+        self.assertEqual(writes, [])
+
+    def test_mutation_still_flushes(self):
+        bound, _original, writes = self._bound()
+        bound["pages"][0]["skippable"]["label"] = "t"
+        self.assertEqual(len(writes), 1)
+        self.assertEqual(writes[0]["pages"][0]["skippable"]["label"], "t")