velocity-python 0.1.111__tar.gz → 0.1.113__tar.gz

{velocity_python-0.1.111/src/velocity_python.egg-info → velocity_python-0.1.113}/PKG-INFO

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

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

{velocity_python-0.1.111 → velocity_python-0.1.113}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.111"
+__version__ = version = "0.1.113"
 
 import importlib as _importlib
 

{velocity_python-0.1.111 → velocity_python-0.1.113}/src/velocity/aws/handlers/context.py

@@ -18,8 +18,13 @@ from velocity.aws.ssm_config import get_region as config_get_region
 from velocity.aws.ssm_config import get_stage as config_get_stage
 from velocity.logging import get_logger
 from velocity.cache import memo
+from velocity.db.core.lazy_engine import LazyEngine
 
-engine = velocity.db.postgres.initialize()
+# Built on first use, not at import: importing a handler must not demand DB
+# configuration (see LazyEngine). ``@engine.transaction`` on Context below is
+# honoured lazily — the first call of a ``tx``-taking method constructs the
+# engine and dispatches through the real decorator.
+engine = LazyEngine(velocity.db.postgres.initialize)
 
 
 cognito_client = boto3.client("cognito-idp")

{velocity_python-0.1.111 → velocity_python-0.1.113}/src/velocity/aws/mirror.py

@@ -40,9 +40,13 @@ def alternate_engine(alternate_db: str | None = None):
     """Engine for the alternate database — same instance, other ``database``.
 
     Host/port/user/password are inherited from the running config, so no
-    separate credentials are needed; only the database name changes (the
-    ``DBAlternate`` config key by default). Cached per database name so
-    repeated mirrors in one process reuse the connection.
+    separate credentials are needed; only the database name changes: the
+    ``DBAlternate`` config key, which the site factory's
+    ``provision-capabilities`` derives on every deploy-backend from the
+    sibling environment's ``DBDatabase`` (``/{Project}/{env}/DBAlternate`` =
+    the other stage's database) — nothing to declare by hand inside the
+    factory. Cached per database name so repeated mirrors in one process
+    reuse the connection.
     """
     from velocity.aws import ssm_config
     from velocity.db.servers import postgres

velocity_python-0.1.113/src/velocity/db/core/lazy_engine.py

@@ -0,0 +1,116 @@
+"""A module-level engine that is built on first use, not at import.
+
+``velocity.aws.handlers.context`` used to run ``postgres.initialize()`` at
+import, so merely importing a handler (or collecting a test that touches one)
+demanded DB configuration — three unrelated test suites ended up stubbing DB
+env vars just to import the package (IMPROVEMENT_BACKLOG, 2026-08-14).
+
+``LazyEngine`` is a drop-in stand-in for that module attribute:
+
+* attribute access (``engine.schema_locked``, ``engine.transaction()``) builds
+  the real engine once, then delegates;
+* ``@engine.transaction`` still works as a function, ``classmethod`` and class
+  decorator — decoration never builds the engine; the first *call* of a
+  decorated callable that declares ``tx`` does, and then dispatches through the
+  real ``Engine.transaction`` so retry/commit semantics are unchanged;
+* callables that do not declare ``tx`` are returned untouched, exactly as the
+  real decorator would run them, so using them never needs configuration.
+
+The configuration error a missing DB env produces therefore surfaces at first
+use, with the same message, instead of at import.
+"""
+
+from __future__ import annotations
+
+import inspect
+from functools import wraps
+from typing import Any, Callable
+
+
+class LazyEngine:
+    """Proxy that constructs ``factory()`` on first use and delegates to it."""
+
+    def __init__(self, factory: Callable[[], Any]):
+        self._factory = factory
+        self._engine = None
+
+    # ── construction ──────────────────────────────────────────────────────
+
+    def resolve(self):
+        """The real engine, built on the first call."""
+        if self._engine is None:
+            self._engine = self._factory()
+        return self._engine
+
+    @property
+    def initialized(self) -> bool:
+        """True once the real engine has been built."""
+        return self._engine is not None
+
+    def __getattr__(self, name: str):
+        # Only reached for names not found on the proxy itself.
+        return getattr(self.resolve(), name)
+
+    def __repr__(self) -> str:
+        state = repr(self._engine) if self._engine is not None else "uninitialized"
+        return f"LazyEngine({state})"
+
+    # ── @engine.transaction ───────────────────────────────────────────────
+
+    def transaction(self, func_or_cls=None):
+        """Mirror ``Engine.transaction``: no args → a Transaction on the real
+        engine; a function / classmethod / class → wrapped lazily."""
+        if func_or_cls is None:
+            return self.resolve().transaction()
+        if isinstance(func_or_cls, classmethod):
+            return classmethod(self._lazy_function(func_or_cls.__func__))
+        if inspect.isclass(func_or_cls):
+            return self._lazy_class(func_or_cls)
+        if inspect.isfunction(func_or_cls) or inspect.ismethod(func_or_cls):
+            return self._lazy_function(func_or_cls)
+        return self.resolve().transaction(func_or_cls)
+
+    def _lazy_function(self, func):
+        names = list(inspect.signature(func).parameters.keys())
+        if "_tx" in names:
+            # Same contract as Engine.transaction, enforced at decoration time.
+            raise NameError(
+                f"In function {func.__name__}, '_tx' is not allowed as a parameter."
+            )
+        if "tx" not in names:
+            # Engine.transaction would call such a function straight through;
+            # returning it untouched is the same behaviour with no engine needed.
+            return func
+
+        wrapped = None
+
+        @wraps(func)
+        def lazy(*args, **kwds):
+            nonlocal wrapped
+            if wrapped is None:
+                wrapped = self.resolve().transaction(func)
+            return wrapped(*args, **kwds)
+
+        return lazy
+
+    def _lazy_class(self, cls):
+        # Same shape as Engine.transaction's class branch: a subclass carrying
+        # wrapped copies of every public callable, descriptors preserved.
+        new_cls = type(cls.__name__, (cls,), {})
+        for attr_name in dir(cls):
+            if attr_name.startswith("__") and attr_name.endswith("__"):
+                continue
+            raw = inspect.getattr_static(cls, attr_name, None)
+            if isinstance(raw, staticmethod):
+                setattr(
+                    new_cls, attr_name, staticmethod(self._lazy_function(raw.__func__))
+                )
+            elif isinstance(raw, classmethod):
+                setattr(
+                    new_cls, attr_name, classmethod(self._lazy_function(raw.__func__))
+                )
+            else:
+                attr = getattr(cls, attr_name)
+                if callable(attr):
+                    setattr(new_cls, attr_name, self._lazy_function(attr))
+        return new_cls

{velocity_python-0.1.111 → velocity_python-0.1.113/src/velocity_python.egg-info}/PKG-INFO

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

@@ -75,6 +75,7 @@ src/velocity/db/core/database.py
 src/velocity/db/core/decorators.py
 src/velocity/db/core/engine.py
 src/velocity/db/core/jsonproxy.py
+src/velocity/db/core/lazy_engine.py
 src/velocity/db/core/result.py
 src/velocity/db/core/row.py
 src/velocity/db/core/sequence.py
@@ -245,6 +246,7 @@ tests/test_lambda_handler.py
 tests/test_lambda_handler_auth.py
 tests/test_lambda_handler_masquerade.py
 tests/test_lambda_handler_user_cache.py
+tests/test_lazy_engine.py
 tests/test_masquerade_grant.py
 tests/test_mirror.py
 tests/test_mixins_import.py

velocity_python-0.1.113/tests/test_lazy_engine.py

@@ -0,0 +1,179 @@
+"""LazyEngine: the handler package imports without DB configuration, the
+engine is built exactly once on first use, and @engine.transaction keeps the
+real decorator's semantics (tx injected on call, static/class methods intact,
+tx-less callables untouched)."""
+
+import os
+import subprocess
+import sys
+
+import pytest
+
+import velocity
+from velocity.db.core.lazy_engine import LazyEngine
+
+SENTINEL_TX = object()
+
+
+class FakeEngine:
+    """Stands in for Engine: transaction(func) injects SENTINEL_TX when the
+    caller passed no tx, transaction() returns a marker."""
+
+    schema_locked = "fake-flag"
+
+    def transaction(self, func_or_cls=None):
+        if func_or_cls is None:
+            return "TX"
+
+        def wrapper(*args, **kwds):
+            if "tx" not in kwds:
+                kwds["tx"] = SENTINEL_TX
+            return func_or_cls(*args, **kwds)
+
+        return wrapper
+
+
+def make_lazy():
+    calls = []
+
+    def factory():
+        calls.append(1)
+        return FakeEngine()
+
+    return LazyEngine(factory), calls
+
+
+def test_construction_and_decoration_do_not_build_the_engine():
+    lazy, calls = make_lazy()
+
+    @lazy.transaction
+    class Ctx:
+        def with_tx(self, tx=None, value=None):
+            return tx, value
+
+        def plain(self, value):
+            return value
+
+        @staticmethod
+        def static(tx=None):
+            return tx
+
+        @classmethod
+        def klass(cls, tx=None):
+            return cls, tx
+
+    assert calls == []
+    assert not lazy.initialized
+    assert Ctx.__name__ == "Ctx"
+
+
+def test_first_tx_call_builds_once_and_injects_tx():
+    lazy, calls = make_lazy()
+
+    @lazy.transaction
+    class Ctx:
+        def with_tx(self, tx=None, value=None):
+            return tx, value
+
+    ctx = Ctx()
+    assert ctx.with_tx(value=1) == (SENTINEL_TX, 1)
+    assert ctx.with_tx(value=2) == (SENTINEL_TX, 2)
+    assert calls == [1]
+    assert lazy.initialized
+
+
+def test_callables_without_tx_never_need_the_engine():
+    lazy, calls = make_lazy()
+
+    @lazy.transaction
+    class Ctx:
+        def plain(self, value):
+            return value * 2
+
+    assert Ctx().plain(21) == 42
+    assert calls == []
+
+
+def test_static_and_class_methods_keep_their_nature():
+    lazy, _calls = make_lazy()
+
+    @lazy.transaction
+    class Ctx:
+        @staticmethod
+        def static(tx=None):
+            return tx
+
+        @classmethod
+        def klass(cls, tx=None):
+            return cls.__name__, tx
+
+    assert Ctx.static() is SENTINEL_TX
+    assert Ctx().static() is SENTINEL_TX
+    assert Ctx.klass() == ("Ctx", SENTINEL_TX)
+
+
+def test_function_and_classmethod_decoration():
+    lazy, calls = make_lazy()
+
+    @lazy.transaction
+    def work(tx=None, n=0):
+        return tx, n
+
+    assert calls == []
+    assert work(n=3) == (SENTINEL_TX, 3)
+    assert calls == [1]
+
+
+def test_tx_underscore_parameter_is_rejected_at_decoration_without_building():
+    lazy, calls = make_lazy()
+    with pytest.raises(NameError):
+
+        @lazy.transaction
+        def bad(_tx=None):
+            return _tx
+
+    assert calls == []
+
+
+def test_attribute_access_and_bare_transaction_delegate():
+    lazy, calls = make_lazy()
+    assert lazy.schema_locked == "fake-flag"
+    assert lazy.transaction() == "TX"
+    assert calls == [1]
+    assert "LazyEngine(" in repr(lazy)
+
+
+def _run_without_db_env(code: str) -> subprocess.CompletedProcess:
+    env = {k: v for k, v in os.environ.items() if not k.startswith("DB")}
+    src = os.path.dirname(os.path.dirname(os.path.abspath(velocity.__file__)))
+    env["PYTHONPATH"] = src + os.pathsep + env.get("PYTHONPATH", "")
+    return subprocess.run(
+        [sys.executable, "-c", code],
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+
+
+def test_handlers_import_without_db_configuration():
+    result = _run_without_db_env(
+        "import velocity.aws.handlers.context as c\n"
+        "assert not c.engine.initialized, 'engine built at import'\n"
+        "print('imported')"
+    )
+    assert result.returncode == 0, result.stderr
+    assert "imported" in result.stdout
+
+
+def test_missing_configuration_surfaces_on_first_use_not_import():
+    result = _run_without_db_env(
+        "import velocity.aws.handlers.context as c\n"
+        "try:\n"
+        "    c.engine.transaction()\n"
+        "except Exception as e:\n"
+        "    print('FIRST_USE:', type(e).__name__, e)\n"
+    )
+    assert result.returncode == 0, result.stderr
+    assert "FIRST_USE:" in result.stdout
+    assert "Missing required configuration keys" in result.stdout