lsst-felis 24.1.6rc1__py3-none-any.whl

felis/tests/postgresql.py

@@ -0,0 +1,134 @@
+"""Provides a temporary Postgresql instance for testing."""
+
+# 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 gc
+import unittest
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from sqlalchemy import text
+from sqlalchemy.engine import Connection, Engine, create_engine
+
+try:
+    from testing.postgresql import Postgresql  # type: ignore
+except ImportError:
+    Postgresql = None
+
+__all__ = ["TemporaryPostgresInstance", "setup_postgres_test_db"]
+
+
+class TemporaryPostgresInstance:
+    """Wrapper for a temporary Postgres database.
+
+    Parameters
+    ----------
+    server
+        The ``testing.postgresql.Postgresql`` instance.
+    engine
+        The SQLAlchemy engine for the temporary database server.
+
+    Notes
+    -----
+    This class was copied and modified from
+    ``lsst.daf.butler.tests.postgresql``.
+    """
+
+    def __init__(self, server: Postgresql, engine: Engine) -> None:
+        """Initialize the temporary Postgres database instance."""
+        self._server = server
+        self._engine = engine
+
+    @property
+    def url(self) -> str:
+        """Return connection URL for the temporary database server.
+
+        Returns
+        -------
+        str
+            The connection URL.
+        """
+        return self._server.url()
+
+    @property
+    def engine(self) -> Engine:
+        """Return the SQLAlchemy engine for the temporary database server.
+
+        Returns
+        -------
+        `~sqlalchemy.engine.Engine`
+            The SQLAlchemy engine.
+        """
+        return self._engine
+
+    @contextmanager
+    def begin(self) -> Iterator[Connection]:
+        """Return a SQLAlchemy connection to the test database.
+
+        Returns
+        -------
+        `~sqlalchemy.engine.Connection`
+            The SQLAlchemy connection.
+        """
+        with self._engine.begin() as connection:
+            yield connection
+
+    def print_info(self) -> None:
+        """Print information about the temporary database server."""
+        print("\n\n---- PostgreSQL URL ----")
+        print(self.url)
+        self._engine = create_engine(self.url)
+        with self.begin() as conn:
+            print("\n---- PostgreSQL Version ----")
+            res = conn.execute(text("SELECT version()")).fetchone()
+            if res:
+                print(res[0])
+            print("\n")
+
+
+@contextmanager
+def setup_postgres_test_db() -> Iterator[TemporaryPostgresInstance]:
+    """Set up a temporary Postgres database instance that can be used for
+    testing.
+
+    Returns
+    -------
+    TemporaryPostgresInstance
+        The temporary Postgres database instance.
+
+    Raises
+    ------
+    unittest.SkipTest
+        Raised if the ``testing.postgresql`` module is not available.
+    """
+    if Postgresql is None:
+        raise unittest.SkipTest("testing.postgresql module not available.")
+
+    with Postgresql() as server:
+        engine = create_engine(server.url())
+        instance = TemporaryPostgresInstance(server, engine)
+        yield instance
+
+        # Clean up any lingering SQLAlchemy engines/connections
+        # so they're closed before we shut down the server.
+        gc.collect()
+        engine.dispose()

felis/tests/utils.py

@@ -0,0 +1,122 @@
+"""Test utility functions."""
+
+# 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 os
+import shutil
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import IO
+
+__all__ = ["open_test_file", "mk_temp_dir", "rm_temp_dir"]
+
+TEST_DATA_DIR = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "..", "..", "tests", "data"))
+"""The directory containing test data files."""
+
+TEST_TMP_DIR = os.path.normpath(os.path.join(TEST_DATA_DIR, ".."))
+"""The directory for temporary files."""
+
+__all__ = ["open_test_file", "mk_temp_dir", "rm_temp_dir"]
+
+logger = logging.getLogger(__name__)
+
+
+def get_test_file_path(file_name: str) -> str:
+    """Return the path to a test file.
+
+    Parameters
+    ----------
+    file_name
+        The name of the test file.
+
+    Returns
+    -------
+    str
+        The path to the test file.
+
+    Raises
+    ------
+    FileNotFoundError
+        Raised if the file does not exist.
+    """
+    file_path = os.path.join(TEST_DATA_DIR, file_name)
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(file_path)
+    return file_path
+
+
+@contextmanager
+def open_test_file(file_name: str) -> Iterator[IO[str]]:
+    """Return a file object for a test file using a context manager.
+
+    Parameters
+    ----------
+    file_name
+        The name of the test file.
+
+    Returns
+    -------
+    `Iterator` [ `IO` [ `str` ] ]
+        A file object for the test file.
+
+    Raises
+    ------
+    FileNotFoundError
+        Raised if the file does not exist.
+    """
+    logger.debug("Opening test file: %s", file_name)
+    file_path = get_test_file_path(file_name)
+    file = open(file_path)
+    try:
+        yield file
+    finally:
+        file.close()
+
+
+def mk_temp_dir(parent_dir: str = TEST_TMP_DIR) -> str:
+    """Create a temporary directory for testing.
+
+    Parameters
+    ----------
+    parent_dir
+        The parent directory for the temporary directory.
+
+    Returns
+    -------
+    str
+        The path to the temporary directory.
+    """
+    return tempfile.mkdtemp(dir=parent_dir)
+
+
+def rm_temp_dir(temp_dir: str) -> None:
+    """Remove a temporary directory.
+
+    Parameters
+    ----------
+    temp_dir
+        The path to the temporary directory.
+    """
+    logger.debug("Removing temporary directory: %s", temp_dir)
+    shutil.rmtree(temp_dir, ignore_errors=True)

felis/types.py

@@ -0,0 +1,185 @@
+"""Define the supported Felis datatypes."""
+
+# 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 __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "FelisType",
+    "Boolean",
+    "Byte",
+    "Short",
+    "Int",
+    "Long",
+    "Float",
+    "Double",
+    "Char",
+    "String",
+    "Unicode",
+    "Text",
+    "Binary",
+    "Timestamp",
+]
+
+
+class FelisType:
+    """Base class for a representation of Felis column types.
+
+    Notes
+    -----
+    This class plays a role of a metaclass without being an actual metaclass.
+    It provides a method to retrieve a class (type) given Felis type name.
+    There should be no instances of this class (or sub-classes), the utility
+    of the class hierarchy is in the type system itself.
+    """
+
+    felis_name: str
+    """Name of the type as defined in the Felis schema."""
+
+    votable_name: str
+    """Name of the type as defined in VOTable."""
+
+    is_numeric: bool
+    """Flag indicating if the type is numeric."""
+
+    is_sized: bool
+    """Flag indicating if the type is sized, meaning it requires a length."""
+
+    is_timestamp: bool
+    """Flag indicating if the type is a timestamp."""
+
+    _types: dict[str, type[FelisType]] = {}
+    """Dictionary of all known Felis types."""
+
+    @classmethod
+    def __init_subclass__(
+        cls,
+        /,
+        felis_name: str,
+        votable_name: str,
+        is_numeric: bool = False,
+        is_sized: bool = False,
+        is_timestamp: bool = False,
+        **kwargs: Any,
+    ):
+        """Register a new Felis type.
+
+        Parameters
+        ----------
+        felis_name
+            Name of the type.
+        votable_name
+            Name of the type as defined in VOTable.
+        is_numeric
+            Flag indicating if the type is numeric.
+        is_sized
+            Flag indicating if the type is sized.
+        is_timestamp
+            Flag indicating if the type is a timestamp.
+        kwargs
+            Additional keyword arguments.
+        """
+        super().__init_subclass__(**kwargs)
+        cls.felis_name = felis_name
+        cls.votable_name = votable_name
+        cls.is_numeric = is_numeric
+        cls.is_sized = is_sized
+        cls.is_timestamp = is_timestamp
+        cls._types[felis_name] = cls
+
+    @classmethod
+    def felis_type(cls, felis_name: str) -> type[FelisType]:
+        """Return specific Felis type for a given name.
+
+        Parameters
+        ----------
+        felis_name
+            Name of the felis type as defined in felis schema.
+
+        Returns
+        -------
+        `type` [ `FelisType` ]
+            A specific Felis type class.
+
+        Raises
+        ------
+        TypeError
+            Raised if ``felis_name`` does not correspond to a known type.
+        """
+        try:
+            return cls._types[felis_name]
+        except KeyError:
+            raise TypeError(f"Unknown felis type {felis_name!r}") from None
+
+
+class Boolean(FelisType, felis_name="boolean", votable_name="boolean", is_numeric=False):
+    """Felis definition of boolean type."""
+
+
+class Byte(FelisType, felis_name="byte", votable_name="unsignedByte", is_numeric=True):
+    """Felis definition of byte type."""
+
+
+class Short(FelisType, felis_name="short", votable_name="short", is_numeric=True):
+    """Felis definition of short integer type."""
+
+
+class Int(FelisType, felis_name="int", votable_name="int", is_numeric=True):
+    """Felis definition of integer type."""
+
+
+class Long(FelisType, felis_name="long", votable_name="long", is_numeric=True):
+    """Felis definition of long integer type."""
+
+
+class Float(FelisType, felis_name="float", votable_name="float", is_numeric=True):
+    """Felis definition of single precision floating point type."""
+
+
+class Double(FelisType, felis_name="double", votable_name="double", is_numeric=True):
+    """Felis definition of double precision floating point type."""
+
+
+class Char(FelisType, felis_name="char", votable_name="char", is_sized=True):
+    """Felis definition of character type."""
+
+
+class String(FelisType, felis_name="string", votable_name="char", is_sized=True):
+    """Felis definition of string type."""
+
+
+class Unicode(FelisType, felis_name="unicode", votable_name="unicodeChar", is_sized=True):
+    """Felis definition of unicode string type."""
+
+
+class Text(FelisType, felis_name="text", votable_name="char"):
+    """Felis definition of text type."""
+
+
+class Binary(FelisType, felis_name="binary", votable_name="unsignedByte", is_sized=True):
+    """Felis definition of binary type."""
+
+
+class Timestamp(FelisType, felis_name="timestamp", votable_name="char", is_timestamp=True):
+    """Felis definition of timestamp type."""

felis/version.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "24.1.6rc1"

lsst_felis-24.1.6rc1.dist-info/COPYRIGHT

@@ -0,0 +1 @@
+Copyright 2018-2024 The Board of Trustees of the Leland Stanford Junior University, through SLAC National Accelerator Laboratory