velocity-python 0.1.39__tar.gz → 0.1.41__tar.gz

{velocity_python-0.1.39/src/velocity_python.egg-info → velocity_python-0.1.41}/PKG-INFO

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

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

{velocity_python-0.1.39 → velocity_python-0.1.41}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.39"
+__version__ = version = "0.1.41"
 
 import importlib as _importlib
 

{velocity_python-0.1.39 → velocity_python-0.1.41}/src/velocity/db/core/table.py

@@ -358,6 +358,99 @@ def _normalize_foreign_key_specs(foreign_keys):
     return normalized
 
 
+def _normalize_drop_index_specs(indexes):
+    if indexes is None:
+        return []
+
+    if isinstance(indexes, (str, bytes, Mapping)):
+        indexes = [indexes]
+
+    normalized = []
+    for definition in indexes:
+        if isinstance(definition, Mapping):
+            name = definition.get("name")
+            columns = definition.get("columns")
+        else:
+            name = definition
+            columns = None
+
+        if isinstance(columns, str):
+            columns = [column.strip() for column in columns.split(",") if column.strip()]
+        elif isinstance(columns, Sequence):
+            columns = list(columns)
+        elif columns is not None:
+            columns = [columns]
+
+        if not name and not columns:
+            raise ValueError("drop_indexes entries require a name or columns")
+
+        normalized.append(
+            {
+                "name": _normalize_identifier(name) if name else None,
+                "columns": tuple(_normalize_identifier(column) for column in columns)
+                if columns
+                else None,
+            }
+        )
+
+    return normalized
+
+
+def _normalize_drop_foreign_key_specs(foreign_keys):
+    if foreign_keys is None:
+        return []
+
+    if isinstance(foreign_keys, (str, bytes, Mapping)):
+        foreign_keys = [foreign_keys]
+
+    normalized = []
+    for definition in foreign_keys:
+        if isinstance(definition, Mapping):
+            name = definition.get("name")
+            columns = definition.get("columns") or definition.get("column")
+            ref_table = definition.get("ref_table") or definition.get("key_to_table")
+            ref_columns = definition.get("ref_columns") or definition.get("key_to_columns")
+        else:
+            name = definition
+            columns = None
+            ref_table = None
+            ref_columns = None
+
+        if isinstance(columns, str):
+            columns = [column.strip() for column in columns.split(",") if column.strip()]
+        elif isinstance(columns, Sequence):
+            columns = list(columns)
+        elif columns is not None:
+            columns = [columns]
+
+        if isinstance(ref_columns, str):
+            ref_columns = [column.strip() for column in ref_columns.split(",") if column.strip()]
+        elif isinstance(ref_columns, Sequence):
+            ref_columns = list(ref_columns)
+        elif ref_columns is not None:
+            ref_columns = [ref_columns]
+
+        if not name and not columns:
+            raise ValueError("drop_foreign_keys entries require a name or columns")
+
+        normalized.append(
+            {
+                "name": _normalize_identifier(name) if name else None,
+                "columns": tuple(_normalize_identifier(column) for column in columns)
+                if columns
+                else None,
+                "ref_table": _normalize_identifier(ref_table) if ref_table else None,
+                "ref_columns": tuple(
+                    _normalize_identifier(column) for column in ref_columns
+                )
+                if ref_columns
+                else None,
+            }
+        )
+
+    return normalized
+
+
 class Table:
     SYSTEM_COLUMNS = SYSTEM_COLUMN_NAMES
 
@@ -532,14 +625,16 @@ class Table:
         return statements if sql_only else None
 
     @return_default(None)
-    def drop_index(self, columns, **kwds):
+    def drop_index(self, columns=None, name=None, **kwds):
         """
         Drops an index for the specified columns.
         """
-        sql, vals = self.sql.drop_index(self.name, columns)
+        sql, vals = self.sql.drop_index(self.name, columns, name=name)
         if kwds.get("sql_only", False):
             return sql, vals
-        _ddl_logger.warning("DDL DROP INDEX on %s columns=%s", self.name, columns)
+        _ddl_logger.warning(
+            "DDL DROP INDEX on %s columns=%s name=%s", self.name, columns, name
+        )
         self.tx.execute(sql, vals, cursor=self.cursor())
 
     @return_default(None)
@@ -887,6 +982,396 @@ class Table:
 
         return summary
 
+    def migrate_schema(
+        self,
+        columns=None,
+        rename_columns=None,
+        drop_columns=None,
+        unique_indexes=None,
+        indexes=None,
+        foreign_keys=None,
+        drop_indexes=None,
+        drop_foreign_keys=None,
+        replace_indexes=False,
+        replace_foreign_keys=False,
+        create_missing=True,
+        ensure_system_columns=False,
+    ):
+        """Apply explicit schema migrations needed to evolve this table.
+
+        Unlike ``ensure_schema()``, this helper may rename columns, alter
+        existing column definitions, drop obsolete columns, and explicitly
+        replace indexes or foreign keys. It is intended for deliberate
+        deploy-time migration code rather than passive schema alignment.
+
+        Operations run in this order:
+
+        1. Create the table when missing and ``create_missing=True``.
+        2. Rename columns.
+        3. Drop explicit foreign keys and indexes.
+        4. Add or alter columns using :meth:`alter` in ``smart`` mode.
+        5. Ensure system columns when requested.
+        6. Create or replace declared indexes and foreign keys.
+        7. Drop columns.
+        """
+
+        if columns is not None and not isinstance(columns, Mapping):
+            raise TypeError("columns must be a mapping when provided.")
+        if rename_columns is not None and not isinstance(rename_columns, Mapping):
+            raise TypeError("rename_columns must be a mapping when provided.")
+
+        normalized_columns = self.lower_keys(columns or {})
+        normalized_renames = {}
+        for orig, new in (rename_columns or {}).items():
+            orig_name = _normalize_identifier(orig)
+            new_name = _normalize_identifier(new)
+            if not orig_name or not new_name:
+                raise ValueError("rename_columns entries require non-empty source and target names")
+            normalized_renames[orig_name] = new_name
+
+        if drop_columns is None:
+            normalized_drops = []
+        elif isinstance(drop_columns, str):
+            normalized_drops = [
+                _normalize_identifier(column)
+                for column in drop_columns.split(",")
+                if _normalize_identifier(column)
+            ]
+        elif isinstance(drop_columns, Sequence):
+            normalized_drops = [
+                _normalize_identifier(column)
+                for column in drop_columns
+                if _normalize_identifier(column)
+            ]
+        else:
+            normalized_drops = [_normalize_identifier(drop_columns)]
+
+        conflicting_columns = set(normalized_columns).intersection(normalized_drops)
+        if conflicting_columns:
+            raise ValueError(
+                "columns and drop_columns cannot reference the same column(s): "
+                + ", ".join(sorted(conflicting_columns))
+            )
+
+        normalized_indexes = _normalize_index_specs(indexes)
+        normalized_unique_indexes = _normalize_index_specs(
+            unique_indexes, unique_default=True
+        )
+        normalized_foreign_keys = _normalize_foreign_key_specs(foreign_keys)
+        normalized_drop_indexes = _normalize_drop_index_specs(drop_indexes)
+        normalized_drop_foreign_keys = _normalize_drop_foreign_key_specs(
+            drop_foreign_keys
+        )
+
+        summary = {
+            "created_table": False,
+            "renamed_columns": [],
+            "altered_columns": [],
+            "dropped_columns": [],
+            "created_indexes": [],
+            "dropped_indexes": [],
+            "created_foreign_keys": [],
+            "dropped_foreign_keys": [],
+            "ensured_system_columns": False,
+        }
+
+        table_exists = self.exists()
+        if not table_exists:
+            if not create_missing:
+                raise exceptions.DbTableMissingError(
+                    f"Table '{self.name}' does not exist and create_missing=False."
+                )
+            self._ensure_schema_unlocked("create missing table")
+            self.create(normalized_columns)
+            summary["created_table"] = True
+            table_exists = True
+
+        existing_columns = {column.lower() for column in self.sys_columns()}
+
+        if not summary["created_table"]:
+            for orig_name, new_name in normalized_renames.items():
+                if orig_name == new_name:
+                    continue
+
+                orig_exists = orig_name in existing_columns
+                new_exists = new_name in existing_columns
+
+                if orig_exists and new_exists:
+                    raise exceptions.DbSchemaConflictError(
+                        f"Cannot rename column '{orig_name}' to '{new_name}' on table '{self.name}': "
+                        "both columns already exist."
+                    )
+                if not orig_exists and new_exists:
+                    continue
+                if not orig_exists:
+                    raise exceptions.DbSchemaConflictError(
+                        f"Cannot rename column '{orig_name}' to '{new_name}' on table '{self.name}': "
+                        f"column '{orig_name}' does not exist."
+                    )
+
+                self._ensure_schema_unlocked("rename columns")
+                self.rename_column(orig_name, new_name)
+                summary["renamed_columns"].append(
+                    {"from": orig_name, "to": new_name}
+                )
+                existing_columns.remove(orig_name)
+                existing_columns.add(new_name)
+
+        existing_foreign_keys = self._existing_foreign_key_signatures()
+        for spec in normalized_drop_foreign_keys:
+            match = next(
+                (
+                    existing
+                    for existing in existing_foreign_keys
+                    if (
+                        spec["name"]
+                        and existing["constraint_name"] == spec["name"]
+                    )
+                    or (
+                        spec["columns"]
+                        and existing["columns"] == spec["columns"]
+                        and (
+                            spec["ref_table"] is None
+                            or existing["ref_table"] == spec["ref_table"]
+                        )
+                        and (
+                            spec["ref_columns"] is None
+                            or existing["ref_columns"] == spec["ref_columns"]
+                        )
+                    )
+                ),
+                None,
+            )
+            if not match:
+                continue
+
+            self._ensure_schema_unlocked("drop foreign keys")
+            self.drop_foreign_key(
+                list(match["columns"]),
+                match["ref_table"],
+                list(match["ref_columns"]),
+                name=match["constraint_name"],
+            )
+            summary["dropped_foreign_keys"].append(
+                {
+                    "name": match["constraint_name"],
+                    "columns": list(match["columns"]),
+                }
+            )
+            existing_foreign_keys = self._existing_foreign_key_signatures()
+
+        existing_indexes = self._existing_index_signatures()
+        for spec in normalized_drop_indexes:
+            match = next(
+                (
+                    existing
+                    for existing in existing_indexes
+                    if (
+                        spec["name"] and existing["name"] == spec["name"]
+                    )
+                    or (
+                        spec["columns"]
+                        and existing["columns"] == spec["columns"]
+                    )
+                ),
+                None,
+            )
+            if not match:
+                continue
+
+            self._ensure_schema_unlocked("drop indexes")
+            self.drop_index(list(match["columns"]), name=match["name"])
+            summary["dropped_indexes"].append(
+                {
+                    "name": match["name"],
+                    "columns": list(match["columns"]),
+                }
+            )
+            existing_indexes = self._existing_index_signatures()
+
+        if normalized_columns and not summary["created_table"]:
+            planned = self.alter(normalized_columns, sql_only=True)
+            if planned:
+                self._ensure_schema_unlocked("alter columns")
+                self.alter(normalized_columns)
+                summary["altered_columns"] = list(normalized_columns.keys())
+                existing_columns.update(normalized_columns.keys())
+
+        if ensure_system_columns:
+            required_system_columns = {name.lower() for name in self.SYSTEM_COLUMNS}
+            if not required_system_columns.issubset(existing_columns):
+                self._ensure_schema_unlocked("ensure system columns")
+            self.ensure_system_columns()
+            summary["ensured_system_columns"] = True
+            existing_columns.update(required_system_columns)
+
+        existing_indexes = self._existing_index_signatures()
+        for spec in normalized_unique_indexes + normalized_indexes:
+            desired_signature = self._desired_index_signature(spec)
+            exact_match = next(
+                (
+                    existing
+                    for existing in existing_indexes
+                    if existing["unique"] == desired_signature["unique"]
+                    and existing["columns"] == desired_signature["columns"]
+                    and existing["where"] == desired_signature["where"]
+                ),
+                None,
+            )
+            if exact_match and (
+                not spec["name"] or exact_match["name"] == desired_signature["name"]
+            ):
+                continue
+
+            conflict = None
+            if exact_match and spec["name"]:
+                conflict = exact_match
+            if conflict is None and spec["name"]:
+                conflict = next(
+                    (
+                        existing
+                        for existing in existing_indexes
+                        if existing["name"] == desired_signature["name"]
+                    ),
+                    None,
+                )
+            if conflict is None:
+                conflict = next(
+                    (
+                        existing
+                        for existing in existing_indexes
+                        if existing["columns"] == desired_signature["columns"]
+                        and existing["where"] == desired_signature["where"]
+                    ),
+                    None,
+                )
+            if conflict is not None:
+                if not replace_indexes:
+                    raise exceptions.DbSchemaConflictError(
+                        f"Index migration on table '{self.name}' conflicts with existing index '{conflict['name']}'. "
+                        "Pass replace_indexes=True to replace it explicitly."
+                    )
+                self._ensure_schema_unlocked("replace indexes")
+                self.drop_index(list(conflict["columns"]), name=conflict["name"])
+                summary["dropped_indexes"].append(
+                    {
+                        "name": conflict["name"],
+                        "columns": list(conflict["columns"]),
+                    }
+                )
+                existing_indexes = self._existing_index_signatures()
+
+            self._ensure_schema_unlocked("create indexes")
+            self.create_index(
+                spec["columns"],
+                unique=spec["unique"],
+                direction=spec["direction"],
+                where=spec["where"],
+                lower=spec["lower"],
+                name=spec["name"],
+            )
+            summary["created_indexes"].append(
+                {
+                    "name": spec["name"] or desired_signature["name"],
+                    "columns": list(spec["columns"]),
+                    "unique": spec["unique"],
+                }
+            )
+            existing_indexes = self._existing_index_signatures()
+
+        existing_foreign_keys = self._existing_foreign_key_signatures()
+        for spec in normalized_foreign_keys:
+            exact_match = next(
+                (
+                    existing
+                    for existing in existing_foreign_keys
+                    if existing["columns"] == spec["columns"]
+                    and existing["ref_table"] == spec["ref_table"]
+                    and existing["ref_columns"] == spec["ref_columns"]
+                    and existing["on_delete"] == spec["on_delete"]
+                    and existing["on_update"] == spec["on_update"]
+                ),
+                None,
+            )
+            if exact_match and (
+                not spec["name"] or exact_match["constraint_name"] == spec["name"]
+            ):
+                continue
+
+            conflict = None
+            if exact_match and spec["name"]:
+                conflict = exact_match
+            if conflict is None and spec["name"]:
+                conflict = next(
+                    (
+                        existing
+                        for existing in existing_foreign_keys
+                        if existing["constraint_name"] == spec["name"]
+                    ),
+                    None,
+                )
+            if conflict is None:
+                conflict = next(
+                    (
+                        existing
+                        for existing in existing_foreign_keys
+                        if existing["columns"] == spec["columns"]
+                    ),
+                    None,
+                )
+            if conflict is not None:
+                if not replace_foreign_keys:
+                    raise exceptions.DbSchemaConflictError(
+                        f"Foreign key migration on table '{self.name}' conflicts with existing constraint '{conflict['constraint_name']}'. "
+                        "Pass replace_foreign_keys=True to replace it explicitly."
+                    )
+                self._ensure_schema_unlocked("replace foreign keys")
+                self.drop_foreign_key(
+                    list(conflict["columns"]),
+                    conflict["ref_table"],
+                    list(conflict["ref_columns"]),
+                    name=conflict["constraint_name"],
+                )
+                summary["dropped_foreign_keys"].append(
+                    {
+                        "name": conflict["constraint_name"],
+                        "columns": list(conflict["columns"]),
+                    }
+                )
+                existing_foreign_keys = self._existing_foreign_key_signatures()
+
+            self._ensure_schema_unlocked("create foreign keys")
+            self.create_foreign_key(
+                list(spec["columns"]),
+                spec["ref_table"],
+                list(spec["ref_columns"]),
+                name=spec["name"],
+                on_delete=spec["on_delete"],
+                on_update=spec["on_update"],
+            )
+            summary["created_foreign_keys"].append(
+                {
+                    "name": spec["name"],
+                    "columns": list(spec["columns"]),
+                    "ref_table": spec["ref_table"],
+                    "ref_columns": list(spec["ref_columns"]),
+                    "on_delete": spec["on_delete"],
+                    "on_update": spec["on_update"],
+                }
+            )
+            existing_foreign_keys = self._existing_foreign_key_signatures()
+
+        if not summary["created_table"]:
+            for column_name in normalized_drops:
+                if column_name not in existing_columns:
+                    continue
+                self._ensure_schema_unlocked("drop columns")
+                self.drop_column(column_name)
+                summary["dropped_columns"].append(column_name)
+                existing_columns.remove(column_name)
+
+        return summary
+
     def drop(self):
         """
         Drops this table if it exists.

{velocity_python-0.1.39 → velocity_python-0.1.41/src/velocity_python.egg-info}/PKG-INFO

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

@@ -156,6 +156,7 @@ tests/test_batch_operations.py
 tests/test_concurrency_safety.py
 tests/test_connection_pool.py
 tests/test_connection_resilience.py
+tests/test_context_job_descriptions.py
 tests/test_decorators.py
 tests/test_dirty_pipeline_fast_path.py
 tests/test_email_processing.py

velocity_python-0.1.41/tests/test_context_job_descriptions.py

@@ -0,0 +1,92 @@
+import unittest
+from unittest.mock import patch
+
+from velocity.aws.handlers import context as handler_context
+
+
+class _FakeQueue:
+    def __init__(self):
+        self.entries = []
+
+    def send_messages(self, Entries):
+        self.entries.extend(Entries)
+        return {"Successful": [{"Id": item["Id"]} for item in Entries], "Failed": []}
+
+
+class _FakeSqsResource:
+    def __init__(self, queue):
+        self.queue = queue
+
+    def get_queue_by_name(self, QueueName):
+        return self.queue
+
+
+class _FakeContext:
+    def __init__(self):
+        self.jobs = []
+
+    def session(self):
+        return {"email_address": "owner@example.com"}
+
+    def create_job(self, job_data=None):
+        self.jobs.append(job_data)
+
+
+class TestQueueJobDescriptions(unittest.TestCase):
+    def test_enqueue_uses_caller_supplied_description(self):
+        fake_queue = _FakeQueue()
+        fake_context = _FakeContext()
+
+        with patch.dict(
+            handler_context.os.environ,
+            {"SqsWorkQueue": "example-queue"},
+            clear=False,
+        ), patch.object(
+            handler_context.boto3,
+            "resource",
+            return_value=_FakeSqsResource(fake_queue),
+        ):
+            handler_context.Context.enqueue(
+                fake_context,
+                "run-program-object",
+                payload={
+                    "sys_id": 1021,
+                    "program_handle": "daily_update_summary_table",
+                    "description": "Program Object: daily_update_summary_table",
+                },
+            )
+
+        self.assertEqual(1, len(fake_context.jobs))
+        self.assertEqual(
+            "Program Object: daily_update_summary_table",
+            fake_context.jobs[0]["description"],
+        )
+
+    def test_enqueue_leaves_description_empty_when_caller_omits_it(self):
+        fake_queue = _FakeQueue()
+        fake_context = _FakeContext()
+
+        with patch.dict(
+            handler_context.os.environ,
+            {"SqsWorkQueue": "example-queue"},
+            clear=False,
+        ), patch.object(
+            handler_context.boto3,
+            "resource",
+            return_value=_FakeSqsResource(fake_queue),
+        ):
+            handler_context.Context.enqueue(
+                fake_context,
+                "run-program-object",
+                payload={
+                    "sys_id": 1021,
+                    "program_handle": "daily_update_summary_table",
+                },
+            )
+
+        self.assertEqual(1, len(fake_context.jobs))
+        self.assertIsNone(fake_context.jobs[0]["description"])
+
+
+if __name__ == "__main__":
+    unittest.main()