climate_ref.cli

Entrypoint for the CLI

CLIContext

Context object that can be passed to commands.

The database is created lazily on first access to avoid running migrations and creating backups for commands that don't need the database.

Source code in packages/climate-ref/src/climate_ref/cli/__init__.py

@define
class CLIContext:
    """
    Context object that can be passed to commands.

    The database is created lazily on first access to avoid running
    migrations and creating backups for commands that don't need the database.
    """

    config: Config
    console: Console
    configuration_directory: Path | None = None
    config_load_error: str | None = None
    skip_backup: bool = False
    _database: "Database | None" = field(default=None, alias="_database")
    _database_unmigrated: "Database | None" = field(default=None, alias="_database_unmigrated")

    @property
    def database(self) -> "Database":
        """
        Get the database instance, creating it lazily if needed.

        The database is created on first access, which triggers migrations.
        Backup creation is skipped for read-only commands to reduce overhead.
        """
        if self._database is None:
            from climate_ref.database import Database

            self._database = Database.from_config(self.config, skip_backup=self.skip_backup)
        return self._database

    @property
    def database_unmigrated(self) -> "Database":
        """
        Get a database instance without running migrations.

        Used by ``db`` subcommands that inspect or manage migration state directly.
        """
        if self._database_unmigrated is None:
            from climate_ref.database import Database

            self._database_unmigrated = Database.from_config(self.config, run_migrations=False)
        return self._database_unmigrated

    def close(self) -> None:
        """Close the database connection if it was opened."""
        if self._database is not None:
            self._database.close()
        if self._database_unmigrated is not None:
            self._database_unmigrated.close()

database property

Get the database instance, creating it lazily if needed.

The database is created on first access, which triggers migrations. Backup creation is skipped for read-only commands to reduce overhead.

database_unmigrated property

Get a database instance without running migrations.

Used by db subcommands that inspect or manage migration state directly.

close()

Close the database connection if it was opened.

Source code in packages/climate-ref/src/climate_ref/cli/__init__.py

def close(self) -> None:
    """Close the database connection if it was opened."""
    if self._database is not None:
        self._database.close()
    if self._database_unmigrated is not None:
        self._database_unmigrated.close()

LogLevel

Bases: StrEnum

Log levels for the CLI

Source code in packages/climate-ref/src/climate_ref/cli/__init__.py

class LogLevel(StrEnum):
    """
    Log levels for the CLI
    """

    Error = "ERROR"
    Warning = "WARNING"
    Debug = "DEBUG"
    Info = "INFO"

available_subcommands() cached

Get the top-level commands that can run in this environment.

A command with requires set is only available if that package is installed.

Source code in packages/climate-ref/src/climate_ref/cli/__init__.py

@functools.cache
def available_subcommands() -> dict[str, _Subcommand]:
    """
    Get the top-level commands that can run in this environment.

    A command with ``requires`` set is only available if that package is installed.
    """
    return {
        name: sub
        for name, sub in _SUBCOMMANDS.items()
        if sub.requires is None or importlib.util.find_spec(sub.requires) is not None
    }

build_app()

Build the CLI app

The subcommands are registered lazily by the root group, see available_subcommands.

Returns:

Type	Description
Typer	The CLI app

Source code in packages/climate-ref/src/climate_ref/cli/__init__.py

def build_app() -> typer.Typer:
    """
    Build the CLI app

    The subcommands are registered lazily by the root group, see `available_subcommands`.

    Returns
    -------
    :
        The CLI app
    """
    return typer.Typer(name="ref", no_args_is_help=True, cls=_RootGroup)

main(ctx, configuration_directory=None, verbose=False, quiet=False, log_level=None, version=None)

A CLI for the Assessment Fast Track Rapid Evaluation Framework

This CLI provides a number of commands for managing and executing diagnostics.

Source code in packages/climate-ref/src/climate_ref/cli/__init__.py

@app.callback()
def main(  # noqa: PLR0913
    ctx: typer.Context,
    configuration_directory: Annotated[
        Path | None,
        typer.Option(help="Configuration directory"),
    ] = None,
    verbose: Annotated[
        bool,
        typer.Option("--verbose", "-v", help="Set the log level to DEBUG"),
    ] = False,
    quiet: Annotated[
        bool,
        typer.Option("--quiet", "-q", help="Set the log level to WARNING"),
    ] = False,
    log_level: Annotated[
        LogLevel | None,
        typer.Option(case_sensitive=False, help="Set the level of logging information to display"),
    ] = None,
    version: Annotated[
        bool | None,
        typer.Option(
            "--version", callback=_version_callback, is_eager=True, help="Print the version and exit"
        ),
    ] = None,
) -> None:
    """
    A CLI for the Assessment Fast Track Rapid Evaluation Framework

    This CLI provides a number of commands for managing and executing diagnostics.
    """  # noqa: D401
    if quiet:
        log_level = LogLevel.Warning
    if verbose:
        log_level = LogLevel.Debug

    logger.remove()

    tolerate_config_problems = ctx.invoked_subcommand == "config" or _is_config_bootstrap_command()
    config, config_load_error = _load_config(
        configuration_directory,
        tolerate_problems=tolerate_config_problems,
    )
    if log_level is not None:
        config.log_level = log_level.value

    log_format = config.log_format
    initialise_logging(
        level=config.log_level,
        format=log_format,
        log_directory=config.paths.log,
        serialize=config.log_json,
    )

    logger.debug(f"Configuration loaded from: {config._config_file!s}")

    if "celery" not in available_subcommands():
        logger.debug("Celery CLI not available")

    # Create context with lazy database initialization
    # The database is only created when first accessed
    # Skip backup for read-only commands to reduce overhead
    skip_backup = _is_read_only_command()
    cli_context = CLIContext(
        config=config,
        console=_create_console(),
        configuration_directory=configuration_directory,
        config_load_error=config_load_error,
        skip_backup=skip_backup,
    )
    ctx.obj = cli_context

    # Register cleanup to close database connection when CLI exits
    ctx.call_on_close(cli_context.close)

sub-packages

Sub-package	Description
_config_access	Helpers for reading and updating dotted configuration keys.
_git_utils	Git utilities for CLI commands.
_utils
config	View and update the REF configuration
datasets	View and ingest input datasets
db	Database management commands
diagnostics	View diagnostic metadata
doctor	Check a deployment for problems that a solve would otherwise hide.
executions	View execution groups and their results
providers	Manage the REF providers.
solve
test_cases	Test management commands for diagnostic development.