lsst-felis 27.2024.2500__tar.gz → 27.2024.2600__tar.gz

{lsst_felis-27.2024.2500 → lsst_felis-27.2024.2600}/COPYRIGHT

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

{lsst_felis-27.2024.2500/python/lsst_felis.egg-info → lsst_felis-27.2024.2600}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: lsst-felis
-Version: 27.2024.2500
+Version: 27.2024.2600
 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+)
@@ -27,4 +27,6 @@ Requires-Dist: lsst-utils
 Provides-Extra: test
 Requires-Dist: pytest>=3.2; extra == "test"
 Provides-Extra: dev
-Requires-Dist: documenteer[guide]; extra == "dev"
+Requires-Dist: documenteer[guide]<2; extra == "dev"
+Requires-Dist: autodoc_pydantic; extra == "dev"
+Requires-Dist: sphinx-click; extra == "dev"

{lsst_felis-27.2024.2500 → lsst_felis-27.2024.2600}/pyproject.toml

@@ -40,7 +40,9 @@ test = [
     "pytest >= 3.2"
 ]
 dev = [
-    "documenteer[guide]"
+    "documenteer[guide] < 2",
+    "autodoc_pydantic",
+    "sphinx-click",
 ]
 
 [tool.pytest.ini_options]
@@ -61,7 +63,6 @@ version = { attr = "lsst_versions.get_lsst_version" }
 [project.scripts]
 felis = "felis.cli:cli"
 
-
 [tool.towncrier]
     package = "felis"
     package_dir = "python"
@@ -152,6 +153,41 @@ select = [
     "UP",  # pyupgrade
 ]
 
+[tool.pydocstyle]
+convention = "numpy"
+# Our coding style does not require docstrings for magic methods (D105)
+# Our docstyle documents __init__ at the class level (D107)
+# We allow methods to inherit docstrings and this is not compatible with D102.
+# Docstring at the very first line is not required
+# D200, D205 and D400 all complain if the first sentence of the docstring does
+# not fit on one line. We do not require docstrings in __init__ files (D104).
+add-ignore = ["D107", "D105", "D102", "D100", "D200", "D205", "D400", "D104"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 79
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.numpydoc_validation]
+checks = [
+    "all",  # All except the rules listed below.
+    "SA01",  # See Also section.
+    "SA04",  # We don't use descriptions with See Also.
+    "EX01",  # Example section.
+    "SS06",  # Summary can go into second line.
+    "GL01",  # Summary text can start on same line as """
+    "GL08",  # Do not require docstring.
+    "ES01",  # No extended summary required.
+    "SS05",  # pydocstyle is better at finding infinitive verb.
+    "PR04",  # Sphinx does not require parameter type.
+]
+exclude = [
+    "^test_.*",  # Do not test docstrings in test code.
+    '^__init__$',
+    '\._[a-zA-Z_]+$',  # Private methods.
+]
+
 [tool.pydeps]
 max_bacon = 2
 no_show = true

{lsst_felis-27.2024.2500 → lsst_felis-27.2024.2600}/python/felis/cli.py

@@ -1,3 +1,5 @@
+"""Click command line interface."""
+
 # This file is part of felis.
 #
 # Developed for the LSST Data Management System.
@@ -38,6 +40,8 @@ from .db.utils import DatabaseContext
 from .metadata import MetaDataBuilder
 from .tap import Tap11Base, TapLoadingVisitor, init_tables
 
+__all__ = ["cli"]
+
 logger = logging.getLogger("felis")
 
 loglevel_choices = ["CRITICAL", "FATAL", "ERROR", "WARNING", "INFO", "DEBUG"]
@@ -59,14 +63,14 @@ loglevel_choices = ["CRITICAL", "FATAL", "ERROR", "WARNING", "INFO", "DEBUG"]
     help="Felis log file path",
 )
 def cli(log_level: str, log_file: str | None) -> None:
-    """Felis Command Line Tools."""
+    """Felis command line tools"""
     if log_file:
         logging.basicConfig(filename=log_file, level=log_level)
     else:
         logging.basicConfig(level=log_level)
 
 
-@cli.command("create")
+@cli.command("create", help="Create database objects from the Felis file")
 @click.option("--engine-url", envvar="ENGINE_URL", help="SQLAlchemy Engine URL", default="sqlite://")
 @click.option("--schema-name", help="Alternate schema name to override Felis file")
 @click.option(
@@ -89,7 +93,34 @@ def create(
     output_file: IO[str] | None,
     file: IO,
 ) -> None:
-    """Create database objects from the Felis file."""
+    """Create database objects from the Felis file.
+
+    Parameters
+    ----------
+    engine_url
+        SQLAlchemy Engine URL.
+    schema_name
+        Alternate schema name to override Felis file.
+    create_if_not_exists
+        Create the schema in the database if it does not exist.
+    drop_if_exists
+        Drop schema if it already exists in the database.
+    echo
+        Echo database commands as they are executed.
+    dry_run
+        Dry run only to print out commands instead of executing.
+    output_file
+        Write SQL commands to a file instead of executing.
+    file
+        Felis file to read.
+
+    Notes
+    -----
+    This command creates database objects from the Felis file. The
+    ``--create-if-not-exists`` or ``--drop-if-exists`` flags can be used to
+    create a new MySQL database or PostgreSQL schema if it does not exist
+    already.
+    """
     yaml_data = yaml.safe_load(file)
     schema = Schema.model_validate(yaml_data)
     url = make_url(engine_url)
@@ -130,13 +161,13 @@ def create(
     context.create_all()
 
 
-@cli.command("init-tap")
-@click.option("--tap-schema-name", help="Alt Schema Name for TAP_SCHEMA")
-@click.option("--tap-schemas-table", help="Alt Table Name for TAP_SCHEMA.schemas")
-@click.option("--tap-tables-table", help="Alt Table Name for TAP_SCHEMA.tables")
-@click.option("--tap-columns-table", help="Alt Table Name for TAP_SCHEMA.columns")
-@click.option("--tap-keys-table", help="Alt Table Name for TAP_SCHEMA.keys")
-@click.option("--tap-key-columns-table", help="Alt Table Name for TAP_SCHEMA.key_columns")
+@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,
@@ -147,10 +178,31 @@ def init_tap(
     tap_keys_table: str,
     tap_key_columns_table: str,
 ) -> None:
-    """Initialize TAP 1.1 TAP_SCHEMA objects.
+    """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``.
 
-    Please verify the schema/catalog you are executing this in in your
-    engine URL.
+    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, echo=True)
     init_tables(
@@ -164,19 +216,19 @@ def init_tap(
     Tap11Base.metadata.create_all(engine)
 
 
-@cli.command("load-tap")
+@cli.command("load-tap", help="Load metadata from a Felis file into a TAP_SCHEMA database")
 @click.option("--engine-url", envvar="ENGINE_URL", help="SQLAlchemy Engine URL to catalog")
 @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="Alt Schema Name for TAP_SCHEMA")
-@click.option("--tap-tables-postfix", help="Postfix for TAP table names")
-@click.option("--tap-schemas-table", help="Alt Table Name for TAP_SCHEMA.schemas")
-@click.option("--tap-tables-table", help="Alt Table Name for TAP_SCHEMA.tables")
-@click.option("--tap-columns-table", help="Alt Table Name for TAP_SCHEMA.columns")
-@click.option("--tap-keys-table", help="Alt Table Name for TAP_SCHEMA.keys")
-@click.option("--tap-key-columns-table", help="Alt Table Name for TAP_SCHEMA.key_columns")
-@click.option("--tap-schema-index", type=int, help="TAP_SCHEMA index of the schema")
+@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,
@@ -193,10 +245,46 @@ def load_tap(
     tap_schema_index: int,
     file: io.TextIOBase,
 ) -> None:
-    """Load TAP metadata from a Felis FILE.
+    """Load TAP metadata from a Felis file.
+
+    This command loads the associated TAP metadata from a Felis YAML file
+    into the TAP_SCHEMA tables.
 
-    This command loads the associated TAP metadata from a Felis FILE
-    to 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.
     """
     yaml_data = yaml.load(file, Loader=yaml.SafeLoader)
     schema = Schema.model_validate(yaml_data)
@@ -239,10 +327,12 @@ def load_tap(
         tap_visitor.visit_schema(schema)
 
 
-@cli.command("validate")
-@click.option("--check-description", is_flag=True, help="Require description for all objects", default=False)
+@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
+)
 @click.option(
-    "--check-redundant-datatypes", is_flag=True, help="Check for redundant datatypes", default=False
+    "--check-redundant-datatypes", is_flag=True, help="Check for redundant datatype overrides", default=False
 )
 @click.option(
     "--check-tap-table-indexes",
@@ -264,7 +354,33 @@ def validate(
     check_tap_principal: bool,
     files: Iterable[io.TextIOBase],
 ) -> None:
-    """Validate one or more felis YAML files."""
+    """Validate one or more felis YAML files.
+
+    Parameters
+    ----------
+    check_description
+        Check that all objects have a valid description.
+    check_redundant_datatypes
+        Check for redundant type overrides.
+    check_tap_table_indexes
+        Check that every table has a unique TAP table index.
+    check_tap_principal
+        Check that at least one column per table is flagged as TAP principal.
+    files
+        The Felis YAML files to validate.
+
+    Raises
+    ------
+    click.exceptions.Exit
+        If any validation errors are found. The ``ValidationError`` which is
+        thrown when a schema fails to validate will be logged as an error
+        message.
+
+    Notes
+    -----
+    All of the ``check`` flags are turned off by default and represent
+    optional validations controlled by the Pydantic context.
+    """
     rc = 0
     for file in files:
         file_name = getattr(file, "name", None)