pyrocko.squirrel.tool.common

Squirrel command line tool infrastructure and argument parsing.

Functions

add_squirrel_query_arguments(parser[, without])	Set up command line options commonly used in squirrel queries.
add_squirrel_selection_arguments(parser[, ...])	Set up command line options commonly used to configure a Squirrel instance.
add_squirrel_selection_arguments_base(parser)	Set up command line options used to configure a Dataset instance.
add_squirrel_storage_scheme_arguments(parser)	Set up command line options commonly used for saving.
ce(prefix, func, *args)	Convert Exceptions in to ToolError.
dataset_from_selection_arguments(args)	Create a Dataset instance from command line arguments.
hint_codes_patterns_extra(source, patterns)	Warn about codes patterns which only fail because of the extra code.
squirrel_effective_storage_scheme_from_arguments(args)	Get storage scheme from command line arguments.
squirrel_from_selection_arguments(args[, ...])	Create a Squirrel instance from command line arguments.
squirrel_query_from_arguments(args)	Get common arguments to be used in squirrel queries from command line.

Classes

SquirrelArgumentParser(*args[, command, ...])	Parser for CLI arguments with a some extras for Squirrel based apps.
SquirrelCommand()	Base class for Squirrel-based CLI programs and subcommands.

class SquirrelArgumentParser(*args, command=None, subcommands=[], **kwargs)

Bases: PyrockoArgumentParser

Parser for CLI arguments with a some extras for Squirrel based apps.

Parameters:

• command (SquirrelCommand or module providing the same interface) – Implementation of the command.

• subcommands (list of SquirrelCommand or modules providing the same interface) – Implementations of subcommands.

• *args – Handed through to base class’s init.

• **kwargs – Handed through to base class’s init.

parse_args(args=None, namespace=None)

Parse arguments given on command line.

Extends the functionality of argparse.ArgumentParser.parse_args() to process and handle the standard options --loglevel, --progress and --help.

dispatch(args)

Dispatch execution to selected command/subcommand.

Parameters:

args – Parsed arguments obtained from parse_args().

Returns:

True if dispatching was successful, False otherwise.

If an exception of type SquirrelError or ToolError is caught, the error is logged and the program is terminated with exit code 1.

run(args=None)

Parse arguments and dispatch to selected command/subcommand.

This simply calls parse_args() and then dispatch() with the obtained args. A usage message is printed if no command is selected.

add_squirrel_selection_arguments(without=[])

Set up command line options commonly used to configure a Squirrel instance.

This will add optional arguments --add, --include, --exclude, --optimistic, --format, --add-only, --persistent, and --dataset.

Call args.make_squirrel() on the arguments returned from parse_args() to finally instantiate and configure the Squirrel instance.

add_squirrel_selection_arguments_base(without=[])

Set up command line options commonly used to configure a Dataset instance.

This will add optional arguments --add, --include, --exclude, --format, --add-only.

Call args.return make_dataset() on the arguments returned from parse_args() to finally instantiate and configure the Dataset instance.

add_squirrel_query_arguments(without=[])

Set up command line options commonly used in squirrel queries.

This will add optional arguments --kinds, --codes, --tmin, --tmax, and --time.

Once finished with parsing, the query arguments are available as args.squirrel_query on the arguments returned from parse_args().

Parameters:

without (list of str, choices: 'tmin', 'tmax', 'codes', and 'time'.) – Suppress adding given options.

add_squirrel_storage_scheme_arguments()

Set up command line options commonly used for saving.

This will add optional arguments --out-path, --out-sds-path, --out-storage-path, --out-storage-scheme, --out-format, --out-mseed-record-length and --out-mseed-steim.

Once finished with parsing, the pyrocko.squirrel.storage.StorageScheme is available as args.squirrel_effective_storage_scheme on the arguments returned from parse_args().

add_squirrel_selection_arguments(parser, without=[])

Set up command line options commonly used to configure a Squirrel instance.

This will optional arguments --add, --include, --exclude, --optimistic, --format, --add-only, --persistent, and --dataset to a given argument parser.

Once finished with parsing, call squirrel_from_selection_arguments() to finally instantiate and configure the Squirrel instance.

Parameters:

• parser (argparse.ArgumentParser) – The argument parser to be configured.

• without (list of str) – Suppress adding given options.

add_squirrel_selection_arguments_base(parser)

Set up command line options used to configure a Dataset instance.

This is adds a subset of the arguments added by add_squirrel_selection_arguments().

squirrel_from_selection_arguments(args, check_have_data=True)

Create a Squirrel instance from command line arguments.

Use add_squirrel_selection_arguments() to configure the parser with the necessary options.

Parameters:

args – Parsed command line arguments, as returned by argparse.ArgumentParser.parse_args().

Returns:

pyrocko.squirrel.base.Squirrel instance with paths, datasets and remote sources added.

dataset_from_selection_arguments(args)

Create a Dataset instance from command line arguments.

The set of supported arguments for the dataset is a subset of the data collection options. Use add_squirrel_selection_arguments_base() to configure the parser with the necessary options.

Parameters:

args – Parsed command line arguments, as returned by argparse.ArgumentParser.parse_args().

Returns:

pyrocko.squirrel.dataset.Dataset instance

add_squirrel_query_arguments(parser, without=[])

Set up command line options commonly used in squirrel queries.

This will add optional arguments --kinds, --codes, --tmin, --tmax, and --time.

Once finished with parsing, call squirrel_query_from_arguments() to get the parsed values.

Parameters:

• parser (argparse.ArgumentParser) – The argument parser to be configured.

• without (list of str) – Suppress adding given options.

ce(prefix, func, *args)

Convert Exceptions in to ToolError.

squirrel_query_from_arguments(args)

Get common arguments to be used in squirrel queries from command line.

Use add_squirrel_query_arguments() to configure the parser with the necessary options.

Parameters:

args – Parsed command line arguments, as returned by argparse.ArgumentParser.parse_args().

Returns:

dict with any parsed option values.

hint_codes_patterns_extra(source, patterns)

Warn about codes patterns which only fail because of the extra code.

A pattern with four elements, like NET.STA.LOC.CHA, only matches codes with an empty extra code. If such a pattern matches none of the codes available in source, but would match with any extra code, a hint is logged.

Parameters:

• source – Object providing the available codes through its get_codes() method, e.g. a Squirrel or an operator.

• patterns (list of Codes) – Codes patterns, as given in args.squirrel_query['codes'].

add_squirrel_storage_scheme_arguments(parser)

Set up command line options commonly used for saving.

This will add optional arguments --out-path, --out-sds-path, --out-storage-path, --out-storage-scheme, --out-format, --out-mseed-record-length and --out-mseed-steim.

Once finished with parsing, call squirrel_effective_storage_scheme_from_arguments() to get the configured pyrocko.squirrel.storage.StorageScheme instance.

Parameters:

parser (argparse.ArgumentParser) – The argument parser to be configured.

squirrel_effective_storage_scheme_from_arguments(args)

Get storage scheme from command line arguments.

Use add_squirrel_storage_scheme_arguments() to configure the parser with the necessary options.

Parameters:

args – Parsed command line arguments, as returned by argparse.ArgumentParser.parse_args().

Returns:

pyrocko.squirrel.storage.StorageScheme or None if neither --out-path nor --out-sds-path nor --out-storage-path is given.

class SquirrelCommand

Bases: object

Base class for Squirrel-based CLI programs and subcommands.

fail(message)

Raises ToolError.

SquirrelArgumentParser.run() catches ToolError, logs the error message and terminates with an error exit state.

make_subparser(subparsers)

To be implemented in subcommand. Create subcommand parser.

Must return a newly created parser obtained with subparsers.add_parser(...), e.g.:

def make_subparser(self, subparsers):
    return subparsers.add_parser(
        'plot', help='Draw a nice plot.')

setup(parser)

To be implemented in subcommand. Configure parser.

Parameters:

parser (argparse.ArgumentParser) – The argument parser to be configured.

Example:

def setup(self, parser):
    parser.add_squirrel_selection_arguments()
    parser.add_squirrel_query_arguments()
    parser.add_argument(
        '--fmin',
        dest='fmin',
        metavar='FLOAT',
        type=float,
        help='Corner of highpass [Hz].')

run(parser, args)

To be implemented in subcommand. Main routine of the command.

Parameters:

• parser (argparse.ArgumentParser) – The argument parser to be configured.

• args – Parsed command line arguments, as returned by argparse.ArgumentParser.parse_args().

Example:

def run(self, parser, args):
    print('User has selected fmin = %g Hz' % args.fmin)

    # args.make_squirrel() is available if
    # parser.add_squirrel_selection_arguments() was called during
    # setup().

    sq = args.make_squirrel()

    # args.squirrel_query is available if
    # praser.add_squirrel_query_arguments() was called during
    # setup().

    stations = sq.get_stations(**args.squirrel_query)