lsst-felis 28.2024.4800__tar.gz → 28.2025.500__tar.gz

{lsst_felis-28.2024.4800/python/lsst_felis.egg-info → lsst_felis-28.2025.500}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: lsst-felis
-Version: 28.2024.4800
+Version: 28.2025.500
 Summary: A vocabulary for describing catalogs and acting on those descriptions
 Author-email: Rubin Observatory Data Management <dm-admin@lists.lsst.org>
 License: GNU General Public License v3 or later (GPLv3+)
@@ -13,18 +13,22 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Astronomy
 Requires-Python: >=3.11.0
 Description-Content-Type: text/markdown
 License-File: COPYRIGHT
 License-File: LICENSE
-Requires-Dist: astropy>=4
-Requires-Dist: sqlalchemy>=1.4
-Requires-Dist: click>=7
-Requires-Dist: pyyaml>=6
-Requires-Dist: pydantic<3,>=2
-Requires-Dist: lsst-utils
+Requires-Dist: alembic
+Requires-Dist: astropy
+Requires-Dist: click
+Requires-Dist: deepdiff
 Requires-Dist: lsst-resources
+Requires-Dist: lsst-utils
+Requires-Dist: numpy
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyyaml
+Requires-Dist: sqlalchemy
 Provides-Extra: test
 Requires-Dist: pytest>=3.2; extra == "test"
 Provides-Extra: dev

{lsst_felis-28.2024.4800 → lsst_felis-28.2025.500}/README.rst

@@ -19,8 +19,6 @@ Felis
     :target: https://github.com/lsst/felis/tags
     :alt: Latest Tag
 
-YAML Schema Definition Language for Databases
-
 Overview
 --------
 

{lsst_felis-28.2024.4800 → lsst_felis-28.2025.500}/pyproject.toml

@@ -17,17 +17,21 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Astronomy"
 ]
 keywords = ["lsst"]
 dependencies = [
-    "astropy >= 4",
-    "sqlalchemy >= 1.4",
-    "click >= 7",
-    "pyyaml >= 6",
-    "pydantic >= 2, < 3",
+    "alembic",
+    "astropy",
+    "click",
+    "deepdiff",
+    "lsst-resources",
     "lsst-utils",
-    "lsst-resources"
+    "numpy",
+    "pydantic >=2,<3",
+    "pyyaml",
+    "sqlalchemy"
 ]
 requires-python = ">=3.11.0"
 dynamic = ["version"]

{lsst_felis-28.2024.4800 → lsst_felis-28.2025.500}/python/felis/__init__.py

@@ -19,4 +19,8 @@
 # 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 .datamodel import Schema
+from .db.schema import create_database
+from .diff import DatabaseDiff, FormattedSchemaDiff, SchemaDiff
+from .metadata import MetaDataBuilder
 from .version import *

{lsst_felis-28.2024.4800 → lsst_felis-28.2025.500}/python/felis/cli.py

@@ -34,9 +34,10 @@ from sqlalchemy.engine.mock import MockConnection, create_mock_engine
 
 from . import __version__
 from .datamodel import Schema
+from .db.schema import create_database
 from .db.utils import DatabaseContext, is_mock_url
+from .diff import DatabaseDiff, FormattedSchemaDiff, SchemaDiff
 from .metadata import MetaDataBuilder
-from .tap import Tap11Base, TapLoadingVisitor, init_tables
 from .tap_schema import DataLoader, TableManager
 
 __all__ = ["cli"]
@@ -177,174 +178,9 @@ def create(
         raise click.ClickException(str(e))
 
 
-@cli.command("init-tap", help="Initialize TAP_SCHEMA objects in the database")
-@click.option("--tap-schema-name", help="Alternate database schema name for 'TAP_SCHEMA'")
-@click.option("--tap-schemas-table", help="Alternate table name for 'schemas'")
-@click.option("--tap-tables-table", help="Alternate table name for 'tables'")
-@click.option("--tap-columns-table", help="Alternate table name for 'columns'")
-@click.option("--tap-keys-table", help="Alternate table name for 'keys'")
-@click.option("--tap-key-columns-table", help="Alternate table name for 'key_columns'")
-@click.argument("engine-url")
-def init_tap(
-    engine_url: str,
-    tap_schema_name: str,
-    tap_schemas_table: str,
-    tap_tables_table: str,
-    tap_columns_table: str,
-    tap_keys_table: str,
-    tap_key_columns_table: str,
-) -> None:
-    """Initialize TAP_SCHEMA objects in the database.
-
-    Parameters
-    ----------
-    engine_url
-        SQLAlchemy Engine URL. The target PostgreSQL schema or MySQL database
-        must already exist and be referenced in the URL.
-    tap_schema_name
-        Alterate name for the database schema ``TAP_SCHEMA``.
-    tap_schemas_table
-        Alterate table name for ``schemas``.
-    tap_tables_table
-        Alterate table name for ``tables``.
-    tap_columns_table
-        Alterate table name for ``columns``.
-    tap_keys_table
-        Alterate table name for ``keys``.
-    tap_key_columns_table
-        Alterate table name for ``key_columns``.
-
-    Notes
-    -----
-    The supported version of TAP_SCHEMA in the SQLAlchemy metadata is 1.1. The
-    tables are created in the database schema specified by the engine URL,
-    which must be a PostgreSQL schema or MySQL database that already exists.
-    """
-    engine = create_engine(engine_url)
-    init_tables(
-        tap_schema_name,
-        tap_schemas_table,
-        tap_tables_table,
-        tap_columns_table,
-        tap_keys_table,
-        tap_key_columns_table,
-    )
-    Tap11Base.metadata.create_all(engine)
-
-
-@cli.command("load-tap", help="Load metadata from a Felis file into a TAP_SCHEMA database")
-@click.option("--engine-url", envvar="FELIS_ENGINE_URL", help="SQLAlchemy Engine URL")
-@click.option("--schema-name", help="Alternate Schema Name for Felis file")
-@click.option("--catalog-name", help="Catalog Name for Schema")
-@click.option("--dry-run", is_flag=True, help="Dry Run Only. Prints out the DDL that would be executed")
-@click.option("--tap-schema-name", help="Alternate schema name for 'TAP_SCHEMA'")
-@click.option("--tap-tables-postfix", help="Postfix for TAP_SCHEMA table names")
-@click.option("--tap-schemas-table", help="Alternate table name for 'schemas'")
-@click.option("--tap-tables-table", help="Alternate table name for 'tables'")
-@click.option("--tap-columns-table", help="Alternate table name for 'columns'")
-@click.option("--tap-keys-table", help="Alternate table name for 'keys'")
-@click.option("--tap-key-columns-table", help="Alternate table name for 'key_columns'")
-@click.option("--tap-schema-index", type=int, help="TAP_SCHEMA index of the schema in this environment")
-@click.argument("file", type=click.File())
-def load_tap(
-    engine_url: str,
-    schema_name: str,
-    catalog_name: str,
-    dry_run: bool,
-    tap_schema_name: str,
-    tap_tables_postfix: str,
-    tap_schemas_table: str,
-    tap_tables_table: str,
-    tap_columns_table: str,
-    tap_keys_table: str,
-    tap_key_columns_table: str,
-    tap_schema_index: int,
-    file: IO[str],
-) -> None:
-    """Load TAP metadata from a Felis file.
-
-    This command loads the associated TAP metadata from a Felis YAML file
-    into the TAP_SCHEMA tables.
-
-    Parameters
-    ----------
-    engine_url
-        SQLAlchemy Engine URL to catalog.
-    schema_name
-        Alternate schema name. This overrides the schema name in the
-        ``catalog`` field of the Felis file.
-    catalog_name
-        Catalog name for the schema. This possibly duplicates the
-        ``tap_schema_name`` argument (DM-44870).
-    dry_run
-        Dry run only to print out commands instead of executing.
-    tap_schema_name
-        Alternate name for the schema of TAP_SCHEMA in the database.
-    tap_tables_postfix
-        Postfix for TAP table names that will be automatically appended.
-    tap_schemas_table
-        Alternate table name for ``schemas``.
-    tap_tables_table
-        Alternate table name for ``tables``.
-    tap_columns_table
-        Alternate table name for ``columns``.
-    tap_keys_table
-        Alternate table name for ``keys``.
-    tap_key_columns_table
-        Alternate table name for ``key_columns``.
-    tap_schema_index
-        TAP_SCHEMA index of the schema in this TAP environment.
-    file
-        Felis file to read.
-
-    Notes
-    -----
-    The data will be loaded into the TAP_SCHEMA from the engine URL. The
-    tables must have already been initialized or an error will occur.
-    """
-    schema = Schema.from_stream(file)
-
-    tap_tables = init_tables(
-        tap_schema_name,
-        tap_tables_postfix,
-        tap_schemas_table,
-        tap_tables_table,
-        tap_columns_table,
-        tap_keys_table,
-        tap_key_columns_table,
-    )
-
-    if not dry_run:
-        engine = create_engine(engine_url)
-
-        if engine_url == "sqlite://" and not dry_run:
-            # In Memory SQLite - Mostly used to test
-            Tap11Base.metadata.create_all(engine)
-
-        tap_visitor = TapLoadingVisitor(
-            engine,
-            catalog_name=catalog_name,
-            schema_name=schema_name,
-            tap_tables=tap_tables,
-            tap_schema_index=tap_schema_index,
-        )
-        tap_visitor.visit_schema(schema)
-    else:
-        conn = DatabaseContext.create_mock_engine(engine_url)
-
-        tap_visitor = TapLoadingVisitor.from_mock_connection(
-            conn,
-            catalog_name=catalog_name,
-            schema_name=schema_name,
-            tap_tables=tap_tables,
-            tap_schema_index=tap_schema_index,
-        )
-        tap_visitor.visit_schema(schema)
-
-
 @cli.command("load-tap-schema", help="Load metadata from a Felis file into a TAP_SCHEMA database")
 @click.option("--engine-url", envvar="FELIS_ENGINE_URL", help="SQLAlchemy Engine URL")
-@click.option("--tap-schema-name", help="Name of the TAP_SCHEMA schema in the database")
+@click.option("--tap-schema-name", help="Name of the TAP_SCHEMA schema in the database (default: TAP_SCHEMA)")
 @click.option(
     "--tap-tables-postfix", help="Postfix which is applied to standard TAP_SCHEMA table names", default=""
 )
@@ -415,6 +251,40 @@ def load_tap_schema(
     ).load()
 
 
+@cli.command("init-tap-schema", help="Initialize a standard TAP_SCHEMA database")
+@click.option("--engine-url", envvar="FELIS_ENGINE_URL", help="SQLAlchemy Engine URL")
+@click.option("--tap-schema-name", help="Name of the TAP_SCHEMA schema in the database")
+@click.option(
+    "--tap-tables-postfix", help="Postfix which is applied to standard TAP_SCHEMA table names", default=""
+)
+@click.pass_context
+def init_tap_schema(
+    ctx: click.Context, engine_url: str, tap_schema_name: str, tap_tables_postfix: str
+) -> None:
+    """Initialize a standard TAP_SCHEMA database.
+
+    Parameters
+    ----------
+    engine_url
+        SQLAlchemy Engine URL.
+    tap_schema_name
+        Name of the TAP_SCHEMA schema in the database.
+    tap_tables_postfix
+        Postfix which is applied to standard TAP_SCHEMA table names.
+    """
+    url = make_url(engine_url)
+    engine: Engine | MockConnection
+    if is_mock_url(url):
+        raise click.ClickException("Mock engine URL is not supported for this command")
+    engine = create_engine(engine_url)
+    mgr = TableManager(
+        apply_schema_to_metadata=False if engine.dialect.name == "sqlite" else True,
+        schema_name=tap_schema_name,
+        table_name_postfix=tap_tables_postfix,
+    )
+    mgr.initialize_database(engine)
+
+
 @cli.command("validate", help="Validate one or more Felis YAML files")
 @click.option(
     "--check-description", is_flag=True, help="Check that all objects have a description", default=False
@@ -493,5 +363,63 @@ def validate(
         raise click.exceptions.Exit(rc)
 
 
+@cli.command(
+    "diff",
+    help="""
+    Compare two schemas or a schema and a database for changes
+
+    Examples:
+
+      felis diff schema1.yaml schema2.yaml
+
+      felis diff -c alembic schema1.yaml schema2.yaml
+
+      felis diff --engine-url sqlite:///test.db schema.yaml
+    """,
+)
+@click.option("--engine-url", envvar="FELIS_ENGINE_URL", help="SQLAlchemy Engine URL")
+@click.option(
+    "-c",
+    "--comparator",
+    type=click.Choice(["alembic", "deepdiff"], case_sensitive=False),
+    help="Comparator to use for schema comparison",
+    default="deepdiff",
+)
+@click.option("-E", "--error-on-change", is_flag=True, help="Exit with error code if schemas are different")
+@click.argument("files", nargs=-1, type=click.File())
+@click.pass_context
+def diff(
+    ctx: click.Context,
+    engine_url: str | None,
+    comparator: str,
+    error_on_change: bool,
+    files: Iterable[IO[str]],
+) -> None:
+    schemas = [
+        Schema.from_stream(file, context={"id_generation": ctx.obj["id_generation"]}) for file in files
+    ]
+
+    diff: SchemaDiff
+    if len(schemas) == 2 and engine_url is None:
+        if comparator == "alembic":
+            db_context = create_database(schemas[0])
+            assert isinstance(db_context.engine, Engine)
+            diff = DatabaseDiff(schemas[1], db_context.engine)
+        else:
+            diff = FormattedSchemaDiff(schemas[0], schemas[1])
+    elif len(schemas) == 1 and engine_url is not None:
+        engine = create_engine(engine_url)
+        diff = DatabaseDiff(schemas[0], engine)
+    else:
+        raise click.ClickException(
+            "Invalid arguments - provide two schemas or a schema and a database engine URL"
+        )
+
+    diff.print()
+
+    if diff.has_changes and error_on_change:
+        raise click.ClickException("Schema was changed")
+
+
 if __name__ == "__main__":
     cli()

{lsst_felis-28.2024.4800 → lsst_felis-28.2025.500}/python/felis/datamodel.py

@@ -134,6 +134,32 @@ class DataType(StrEnum):
     timestamp = auto()
 
 
+def validate_ivoa_ucd(ivoa_ucd: str) -> str:
+    """Validate IVOA UCD values.
+
+    Parameters
+    ----------
+    ivoa_ucd
+        IVOA UCD value to check.
+
+    Returns
+    -------
+    `str`
+        The IVOA UCD value if it is valid.
+
+    Raises
+    ------
+    ValueError
+        If the IVOA UCD value is invalid.
+    """
+    if ivoa_ucd is not None:
+        try:
+            ucd.parse_ucd(ivoa_ucd, check_controlled_vocabulary=True, has_colon=";" in ivoa_ucd)
+        except ValueError as e:
+            raise ValueError(f"Invalid IVOA UCD: {e}")
+    return ivoa_ucd
+
+
 class Column(BaseObject):
     """Column model."""
 
@@ -235,12 +261,7 @@ class Column(BaseObject):
         `str`
             The IVOA UCD value if it is valid.
         """
-        if ivoa_ucd is not None:
-            try:
-                ucd.parse_ucd(ivoa_ucd, check_controlled_vocabulary=True, has_colon=";" in ivoa_ucd)
-            except ValueError as e:
-                raise ValueError(f"Invalid IVOA UCD: {e}")
-        return ivoa_ucd
+        return validate_ivoa_ucd(ivoa_ucd)
 
     @model_validator(mode="after")
     def check_units(self) -> Column:
@@ -551,6 +572,70 @@ _ConstraintType = Annotated[
 """Type alias for a constraint type."""
 
 
+ColumnRef: TypeAlias = str
+"""Type alias for a column reference."""
+
+
+class ColumnGroup(BaseObject):
+    """Column group model."""
+
+    columns: list[ColumnRef | Column] = Field(..., min_length=1)
+    """Columns in the group."""
+
+    ivoa_ucd: str | None = Field(None, alias="ivoa:ucd")
+    """IVOA UCD of the column."""
+
+    table: Table | None = None
+    """Reference to the parent table."""
+
+    @field_validator("ivoa_ucd")
+    @classmethod
+    def check_ivoa_ucd(cls, ivoa_ucd: str) -> str:
+        """Check that IVOA UCD values are valid.
+
+        Parameters
+        ----------
+        ivoa_ucd
+            IVOA UCD value to check.
+
+        Returns
+        -------
+        `str`
+            The IVOA UCD value if it is valid.
+        """
+        return validate_ivoa_ucd(ivoa_ucd)
+
+    @model_validator(mode="after")
+    def check_unique_columns(self) -> ColumnGroup:
+        """Check that the columns list contains unique items.
+
+        Returns
+        -------
+        `ColumnGroup`
+            The column group being validated.
+        """
+        column_ids = [col if isinstance(col, str) else col.id for col in self.columns]
+        if len(column_ids) != len(set(column_ids)):
+            raise ValueError("Columns in the group must be unique")
+        return self
+
+    def _dereference_columns(self) -> None:
+        """Dereference ColumnRef to Column objects."""
+        if self.table is None:
+            raise ValueError("ColumnGroup must have a reference to its parent table")
+
+        dereferenced_columns: list[ColumnRef | Column] = []
+        for col in self.columns:
+            if isinstance(col, str):
+                # Dereference ColumnRef to Column object
+                col_obj = self.table._find_column_by_id(col)
+                dereferenced_columns.append(col_obj)
+            else:
+                dereferenced_columns.append(col)
+
+        self.columns = dereferenced_columns
+
+
 class Table(BaseObject):
     """Table model."""
 
@@ -563,6 +648,9 @@ class Table(BaseObject):
     indexes: list[Index] = Field(default_factory=list)
     """Indexes on the table."""
 
+    column_groups: list[ColumnGroup] = Field(default_factory=list, alias="columnGroups")
+    """Column groups in the table."""
+
     primary_key: str | list[str] | None = Field(None, alias="primaryKey")
     """Primary key of the table."""
 
@@ -653,6 +741,43 @@ class Table(BaseObject):
                 return self
         raise ValueError(f"Table '{self.name}' is missing at least one column designated as 'tap:principal'")
 
+    def _find_column_by_id(self, id: str) -> Column:
+        """Find a column by ID.
+
+        Parameters
+        ----------
+        id
+            The ID of the column to find.
+
+        Returns
+        -------
+        `Column`
+            The column with the given ID.
+
+        Raises
+        ------
+        ValueError
+            Raised if the column is not found.
+        """
+        for column in self.columns:
+            if column.id == id:
+                return column
+        raise ValueError(f"Column '{id}' not found in table '{self.name}'")
+
+    @model_validator(mode="after")
+    def dereference_column_groups(self: Table) -> Table:
+        """Dereference columns in column groups.
+
+        Returns
+        -------
+        `Table`
+            The table with dereferenced column groups.
+        """
+        for group in self.column_groups:
+            group.table = self
+            group._dereference_columns()
+        return self
+
 
 class SchemaVersion(BaseModel):
     """Schema version model."""

lsst_felis-28.2025.500/python/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