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

PyrockoArgumentParser([prog, usage, ...])	Tweaks and extends the standard argument parser to simplify the generation of the online docs.
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 PyrockoArgumentParser(prog=None, usage=None, description=None, epilog=None, **kwargs)

Bases: ArgumentParser

Tweaks and extends the standard argument parser to simplify the generation of the online docs.

We want to convert the --help outputs to rst for the html docs. Problem is that argparse’s HelpFormatter to date have no public interface which we could use to achieve this. The solution here is a bit clunky but works ok for our purposes. We allow markup like ``code`` which is kept when producing rst (by parsing the final --help output) but stripped out when doing normal --help. This leads to a problem with the internal output wrapping of argparse which it does before the stripping. To solve, we render with argparse to a very wide width and do the wrapping in post-processing. ``code`` is replaced with just code in normal output. ```code``` is replaced with 'code' in normal output and with ``code`` in rst output. rst output is selected with environment variable PYROCKO_RST_HELP=1. The script maintenance/argparse_help_to_rst.py extracts the rst help and generates the rst files for the docs.

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

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

Parameters:

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

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.

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)