squirrel.tool

Building blocks for Squirrel-based CLI programs.

Code examples are given in section Tutorial: writing a Squirrel based tool to calculate hourly RMS values.

run(args=None, command=None, subcommands=[], description='\nPyrocko Squirrel based script.\n\nRun with --help to get further help.', **kwargs)

Setup and run Squirrel-based application.

The implementation of the tool can be provided by one or multiple SquirrelCommand instances. This driver function sets up a SquirrelArgumentParser, and processes command line arguments, and dispatches execution to the selected command or subcommand. The program is set up to provide and automatically handle --help, --loglevel, and --progress. If an exception of type pyrocko.squirrel.error.SquirrelError or pyrocko.squirrel.error.ToolError is caught, the error is logged and the program is terminated with exit code 1.

Parameters:

• args (list of str) – Arguments passed to argv().

• command (SquirrelCommand or module) – Implementation of the command. It must provide setup(parser) and run(parser, args).

• subcommands (list of SquirrelCommand instances or modules) – Configures the program to offer multiple subcommands. The command to execute is selected with the first argument passed to args. Implementations must provide make_subparser(subparsers), setup(parser), and run(parser, args).

• description (str) – Description of the program.

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 othewise.

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()

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.

Call args.make_squirrel() on the arguments returned from parse_args() to finally instantiate and configure the Squirrel 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 prase_args().

Parameters:

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

class SquirrelCommand

Bases: object

Base class for Squirrel-based CLI programs and subcommands.

fail(message)

Raises ToolError.

from_command() 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 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)

add_squirrel_selection_arguments(parser)

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.

squirrel_from_selection_arguments(args)

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.

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.

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.