squirrel.tool

Building blocks for Squirrel-based CLI programs.

Code examples are given in section A complete example: 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: pyrocko.squirrel.tool.common.PyrockoArgumentParser

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, --kind, --persistent, --update, and --kind 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 options --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.