Command Line Interface

gambit.cli

GAMBIT command line interface.

gambit.cli.common

class gambit.cli.common.CLIContext

Bases: object

Click context object for GAMBIT CLI.

Loads reference database data lazily the first time it is requested.

Currently a single option (or environment variable) is used to specify the location of the database files, in the future options may be added to specify the reference genomes SQLite file and genome signatures file separately. Class methods treat them as being independent.

root_context

Click context object from root command group.

Type:

click.core.Context

db_path

Path to directory containing database files, specified in root command group.

Type:

pathlib.Path | None

has_genomes

Whether reference genome metadata is available.

Type:

bool

has_signatures

Whether reference signatures are available.

Type:

bool

has_database

Whether reference genome metadata and reference signatures are both available.

Type:

bool

engine

SQLAlchemy engine connecting to genomes database.

Type:

sqlalchemy.engine.base.Engine | None

Session

SQLAlchemy session maker for genomes database.

Type:

sqlalchemy.orm.session.sessionmaker | None

signatures

Reference genome signatures.

Type:

gambit.sigs.base.ReferenceSignatures | None

__init__(root_context)
Parameters:

root_context (Context) – Click context object from root command group.

get_database()

Get reference database object.

Return type:

ReferenceDatabase

require_database()

Raise an exception if genome metadata and signatures are not available.

require_genomes()

Raise an exception if genome metadata is not available.

require_signatures()

Raise an exception if signatures are not available.

gambit.cli.common.check_params_group(ctx, names, exclusive, required)

Check for the presence of the given parameter values and raise an informative error if needed.

Parameters:

  • ctx (Context) –

  • names (Iterable[str]) – Parameter names.

  • exclusive (bool) – No more than one of the parameters may be present.

  • required (bool) – At least one of the parameters must be present.

Raises:

click.ClickException –

gambit.cli.common.cores_param()

Click parameter for number of CPU cores.

gambit.cli.common.dirpath(**kw)

Click Path argument type accepting directories only.

Return type:

Path

gambit.cli.common.filepath(**kw)

Click Path argument type accepting files only.

Return type:

Path

gambit.cli.common.genome_files_arg()

Click positional argument for genome files.

gambit.cli.common.get_file_id(path, strip_dir=True, strip_ext=True)

Get sequence file ID derived from file path.

Parameters:

  • strip_dir (bool) – Strip leading path components.

  • strip_ext (bool) – Strip file extension(s).

  • path (str | PathLike) –

Return type:

str

gambit.cli.common.get_sequence_files(explicit=None, listfile=None, listfile_dir=None, strip_dir=True, strip_ext=True)

Get list of sequence file paths and IDs from several types of CLI arguments.

Does not check for conflict between explicit and listfile.

Parameters:

  • explicit (Iterable[str | PathLike] | None) – List of paths given explicitly, such as with a positional argument.

  • listfile (None | str | PathLike | TextIO) – File listing sequence files, one per line.

  • listfile_dir (str | None) – Parent directory for files in listfile.

  • strip_dir (bool) – Strip leading path components from file paths to derive IDs.

  • strip_ext (bool) – Strip file extension from file names to derive IDs.

Returns:

(ids, files) tuple. ids is a list of string IDs that can be used to label output. If the explicit and listfile arguments are None/empty both components of the tuple will be None as well.

Return type:

Tuple[Optional[List[str]], Optional[List[SequenceFile]]]

gambit.cli.common.kspec_from_params(k, prefix, default=False)

Get KmerSpec from CLI arguments and validate.

Parameters:

  • k (int | None) –

  • prefix (str | None) –

  • default (bool) – Return default KmerSpec if arguments are None.

Return type:

KmerSpec | None

gambit.cli.common.kspec_params(default=False)

Returns a decorator to add k and prefix options to command.

Parameters:

default (bool) – Whether to add default values.

gambit.cli.common.listfile_dir_param(*param, file_metavar=None, **kw)

Returns decorator to add param for parent directory of paths in list file.

Parameters:

param (str) –

gambit.cli.common.listfile_param(*param, **kw)

Returns decorator to add param for file listing input paths.

Parameters:

param (str) –

gambit.cli.common.param_name_human(param)

Get the name/metavar of the given parameter as it appears in the auto-generated help output.

Parameters:

param (Parameter) –

Return type:

str

gambit.cli.common.params_by_name(cmd, names=None)

Get parameters of click command by name.

Parameters:

  • cmd (Command) –

  • names (Iterable[str] | None) – Names of specific parameters to get.

Returns:

Parameters with given in names argument if not None, otherwise a dictionary containing all of the command’s parameters keyed by name.

Return type:

Union[Dict[str, click.Parameter], List[click.Parameter]]

gambit.cli.common.print_table(rows, colsep=' ', left='', right='')

Print a basic table.

Parameters:

  • rows (Sequence[Sequence]) –

  • colsep (str) –

  • left (str) –

  • right (str) –

gambit.cli.common.progress_param()

Click argument to show progress meter.

gambit.cli.common.strip_seq_file_ext(filename)

Strip FASTA and/or gzip extensions from sequence file name.

Parameters:

filename (str) –

Return type:

str

gambit.cli.common.warn_duplicate_file_ids(ids, template)

Print a warning message if duplicate file IDs are present.

Parameters:

  • ids (List[str]) – List of file ID strings, such as from get_sequence_files().

  • template (str) – Message template. May contain formatting placeholders for ids (comma-delimited string of duplicated IDs), id (first duplicated ID), and n (number of duplicated IDs).

gambit.cli.root

Define the root CLI command group.

gambit.cli.query

gambit.cli.signatures

gambit.cli.debug

gambit.cli.debug.make_shell_ns(ctx)

Make the user namespace for the shell command.

Return type:

Dict[str, Any]

gambit.cli.debug.SHELL_MODULES = {'kmers': 'gambit.kmers', 'metric': 'gambit.metric'}

Modules to import in interactive shell.