lsst-felis 28.2024.4500__py3-none-any.whl → 29.2025.4500__py3-none-any.whl

felis/db/dialects.py

@@ -32,7 +32,7 @@ from sqlalchemy.engine.mock import create_mock_engine
 
 from .sqltypes import MYSQL, POSTGRES, SQLITE
 
-__all__ = ["get_supported_dialects", "get_dialect_module"]
+__all__ = ["get_dialect_module", "get_supported_dialects"]
 
 _DIALECT_NAMES = (MYSQL, POSTGRES, SQLITE)
 """List of supported dialect names.

felis/db/schema.py

@@ -0,0 +1,62 @@
+"""Database utilities for Felis schemas."""
+
+# This file is part of felis.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+from sqlalchemy import Engine, create_engine
+
+from ..datamodel import Schema
+from ..metadata import MetaDataBuilder
+from .utils import DatabaseContext
+
+__all__ = ["create_database"]
+
+
+def create_database(schema: Schema, engine_or_url_str: Engine | str | None = None) -> DatabaseContext:
+    """
+    Create a database from the specified `Schema`.
+
+    Parameters
+    ----------
+    schema
+        The schema to create.
+    engine_or_url_str
+        The SQLAlchemy engine or URL to use for database creation.
+        If None, an in-memory SQLite database will be created.
+
+    Returns
+    -------
+    `DatabaseContext`
+        The database context object.
+    """
+    if engine_or_url_str is not None:
+        engine = (
+            engine_or_url_str if isinstance(engine_or_url_str, Engine) else create_engine(engine_or_url_str)
+        )
+    else:
+        engine = create_engine("sqlite:///:memory:")
+    metadata = MetaDataBuilder(
+        schema, apply_schema_to_metadata=False if engine.url.drivername == "sqlite" else True
+    ).build()
+    ctx = DatabaseContext(metadata, engine)
+    ctx.initialize()
+    ctx.create_all()
+    return ctx

felis/db/sqltypes.py

@@ -32,20 +32,20 @@ from sqlalchemy.dialects import mysql, postgresql
 from sqlalchemy.ext.compiler import compiles
 
 __all__ = [
+    "binary",
     "boolean",
     "byte",
-    "short",
+    "char",
+    "double",
+    "float",
+    "get_type_func",
     "int",
     "long",
-    "float",
-    "double",
-    "char",
+    "short",
     "string",
-    "unicode",
     "text",
-    "binary",
     "timestamp",
-    "get_type_func",
+    "unicode",
 ]
 
 MYSQL = "mysql"

felis/db/utils.py

@@ -38,7 +38,7 @@ from sqlalchemy.types import TypeEngine
 
 from .dialects import get_dialect_module
 
-__all__ = ["string_to_typeengine", "SQLWriter", "ConnectionWrapper", "DatabaseContext"]
+__all__ = ["ConnectionWrapper", "DatabaseContext", "SQLWriter", "string_to_typeengine"]
 
 logger = logging.getLogger("felis")
 

felis/diff.py

@@ -0,0 +1,234 @@
+"""Compare schemas and print the differences."""
+
+# This file is part of felis.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import logging
+import pprint
+import re
+from collections.abc import Callable
+from typing import Any
+
+from alembic.autogenerate import compare_metadata
+from alembic.migration import MigrationContext
+from deepdiff.diff import DeepDiff
+from sqlalchemy import Engine, MetaData
+
+from .datamodel import Schema
+from .metadata import MetaDataBuilder
+
+__all__ = ["DatabaseDiff", "SchemaDiff"]
+
+logger = logging.getLogger(__name__)
+
+# Change alembic log level to avoid unnecessary output
+logging.getLogger("alembic").setLevel(logging.WARNING)
+
+
+class SchemaDiff:
+    """
+    Compare two schemas using DeepDiff and print the differences.
+
+    Parameters
+    ----------
+    schema1
+        The first schema to compare.
+    schema2
+        The second schema to compare.
+    """
+
+    def __init__(self, schema1: Schema, schema2: Schema):
+        self.dict1 = schema1.model_dump(exclude_none=True)
+        self.dict2 = schema2.model_dump(exclude_none=True)
+        self.diff = DeepDiff(self.dict1, self.dict2, ignore_order=True)
+
+    def print(self) -> None:
+        """
+        Print the differences between the two schemas.
+        """
+        pprint.pprint(self.diff)
+
+    @property
+    def has_changes(self) -> bool:
+        """
+        Check if there are any differences between the two schemas.
+
+        Returns
+        -------
+        bool
+            True if there are differences, False otherwise.
+        """
+        return len(self.diff) > 0
+
+
+class FormattedSchemaDiff(SchemaDiff):
+    """
+    Compare two schemas using DeepDiff and print the differences using a
+    customized output format.
+
+    Parameters
+    ----------
+    schema1
+        The first schema to compare.
+    schema2
+        The second schema to compare.
+    """
+
+    def __init__(self, schema1: Schema, schema2: Schema):
+        super().__init__(schema1, schema2)
+
+    def print(self) -> None:
+        """
+        Print the differences between the two schemas using a custom format.
+        """
+        handlers: dict[str, Callable[[dict[str, Any]], None]] = {
+            "values_changed": self._handle_values_changed,
+            "iterable_item_added": self._handle_iterable_item_added,
+            "iterable_item_removed": self._handle_iterable_item_removed,
+            "dictionary_item_added": self._handle_dictionary_item_added,
+            "dictionary_item_removed": self._handle_dictionary_item_removed,
+        }
+
+        for change_type, handler in handlers.items():
+            if change_type in self.diff:
+                handler(self.diff[change_type])
+
+    def _print_header(self, id_dict: dict[str, Any], keys: list[int | str]) -> None:
+        # id = self._get_id(id_dict, keys)
+        # Don't display ID here for now; it is always just the schema ID.
+        print(f"{self._get_key_display(keys)}")
+        # print(f"{id} @ {self._get_key_display(keys)}")
+
+    def _handle_values_changed(self, changes: dict[str, Any]) -> None:
+        for key in changes:
+            keys = self._parse_deepdiff_path(key)
+            value1 = changes[key]["old_value"]
+            value2 = changes[key]["new_value"]
+            self._print_header(self.dict1, keys)
+            print(f"- {value1}")
+            print(f"+ {value2}")
+
+    def _handle_iterable_item_added(self, changes: dict[str, Any]) -> None:
+        for key in changes:
+            keys = self._parse_deepdiff_path(key)
+            value = changes[key]
+            self._print_header(self.dict2, keys)
+            print(f"+ {value}")
+
+    def _handle_iterable_item_removed(self, changes: dict[str, Any]) -> None:
+        for key in changes:
+            keys = self._parse_deepdiff_path(key)
+            value = changes[key]
+            self._print_header(self.dict1, keys)
+            print(f"- {value}")
+
+    def _handle_dictionary_item_added(self, changes: dict[str, Any]) -> None:
+        for key in changes:
+            keys = self._parse_deepdiff_path(key)
+            value = keys[-1]
+            keys.pop()
+            self._print_header(self.dict2, keys)
+            print(f"+ {value}")
+
+    def _handle_dictionary_item_removed(self, changes: dict[str, Any]) -> None:
+        for key in changes:
+            keys = self._parse_deepdiff_path(key)
+            value = keys[-1]
+            keys.pop()
+            self._print_header(self.dict1, keys)
+            print(f"- {value}")
+
+    @staticmethod
+    def _get_id(values: dict, keys: list[str | int]) -> str:
+        # Unused for now, pending updates to diff tool in DM-49446.
+        value: list | dict = values
+        last_id = None
+
+        for key in keys:
+            logger.debug(f"Processing key <{key}> with type {type(key)}")
+            logger.debug(f"Type of value: {type(value)}")
+            if isinstance(value, dict) and "id" in value:
+                last_id = value["id"]
+            elif isinstance(value, list) and isinstance(key, int):
+                if 0 <= key < len(value):
+                    value = value[key]
+                else:
+                    raise ValueError(f"Index '{key}' is out of range for list of length {len(value)}")
+                value = value[key]
+
+        if isinstance(value, dict) and "id" in value:
+            last_id = value["id"]
+
+        if last_id is not None:
+            return last_id
+        else:
+            raise ValueError("No 'id' found in the specified path")
+
+    @staticmethod
+    def _get_key_display(keys: list[str | int]) -> str:
+        return ".".join(str(k) for k in keys)
+
+    @staticmethod
+    def _parse_deepdiff_path(path: str) -> list[str | int]:
+        if path.startswith("root"):
+            path = path[4:]
+
+        pattern = re.compile(r"\['([^']+)'\]|\[(\d+)\]")
+        matches = pattern.findall(path)
+
+        keys = []
+        for match in matches:
+            if match[0]:  # String key
+                keys.append(match[0])
+            elif match[1]:  # Integer index
+                keys.append(int(match[1]))
+
+        return keys
+
+
+class DatabaseDiff(SchemaDiff):
+    """
+    Compare a schema with a database and print the differences.
+
+    Parameters
+    ----------
+    schema
+        The schema to compare.
+    engine
+        The database engine to compare with.
+    """
+
+    def __init__(self, schema: Schema, engine: Engine):
+        db_metadata = MetaData()
+        with engine.connect() as connection:
+            db_metadata.reflect(bind=connection)
+            mc = MigrationContext.configure(
+                connection, opts={"compare_type": True, "target_metadata": db_metadata}
+            )
+            schema_metadata = MetaDataBuilder(schema, apply_schema_to_metadata=False).build()
+            self.diff = compare_metadata(mc, schema_metadata)
+
+    def print(self) -> None:
+        """
+        Print the differences between the schema and the database.
+        """
+        if self.has_changes:
+            pprint.pprint(self.diff)

felis/metadata.py

@@ -125,29 +125,27 @@ class MetaDataBuilder:
         The schema object from which to build the SQLAlchemy metadata.
     apply_schema_to_metadata
         Whether to apply the schema name to the metadata object.
-    apply_schema_to_tables
-        Whether to apply the schema name to the tables.
     ignore_constraints
         Whether to ignore constraints when building the metadata.
+    table_name_postfix
+        A string to append to the table names when building the metadata.
     """
 
     def __init__(
         self,
         schema: Schema,
         apply_schema_to_metadata: bool = True,
-        apply_schema_to_tables: bool = True,
         ignore_constraints: bool = False,
+        table_name_postfix: str = "",
     ) -> None:
         """Initialize the metadata builder."""
         self.schema = schema
         if not apply_schema_to_metadata:
             logger.debug("Schema name will not be applied to metadata")
-        if not apply_schema_to_tables:
-            logger.debug("Schema name will not be applied to tables")
         self.metadata = MetaData(schema=schema.name if apply_schema_to_metadata else None)
         self._objects: dict[str, Any] = {}
-        self.apply_schema_to_tables = apply_schema_to_tables
         self.ignore_constraints = ignore_constraints
+        self.table_name_postfix = table_name_postfix
 
     def build(self) -> MetaData:
         """Build the SQLAlchemy tables and constraints from the schema.
@@ -231,11 +229,10 @@ class MetaDataBuilder:
         description = table_obj.description
         columns = [self.build_column(column) for column in table_obj.columns]
         table = Table(
-            name,
+            name + self.table_name_postfix,
             self.metadata,
             *columns,
             comment=description,
-            schema=self.schema.name if self.apply_schema_to_tables else None,
             **optargs,  # type: ignore[arg-type]
         )
 
@@ -341,12 +338,17 @@ class MetaDataBuilder:
             "deferrable": constraint_obj.deferrable or None,
             "initially": constraint_obj.initially or None,
         }
+
         constraint: Constraint
 
         if isinstance(constraint_obj, datamodel.ForeignKeyConstraint):
             fk_obj: datamodel.ForeignKeyConstraint = constraint_obj
             columns = [self._objects[column_id] for column_id in fk_obj.columns]
             refcolumns = [self._objects[column_id] for column_id in fk_obj.referenced_columns]
+            if constraint_obj.on_delete is not None:
+                args["ondelete"] = constraint_obj.on_delete
+            if constraint_obj.on_update is not None:
+                args["onupdate"] = constraint_obj.on_update
             constraint = ForeignKeyConstraint(columns, refcolumns, **args)
         elif isinstance(constraint_obj, datamodel.CheckConstraint):
             check_obj: datamodel.CheckConstraint = constraint_obj