Coverage for /usr/local/lib/python3.11/dist-packages/pyrocko/squirrel/tool/cli.py: 92%

1# http://pyrocko.org - GPLv3 

2# 

3# The Pyrocko Developers, 21st Century 

4# ---|P------/S----------~Lg---------- 

5 

6''' 

7Squirrel command line tool main program. 

8''' 

9 

10import logging 

11 

12from . import common 

13from .commands import command_modules 

14 

15 

16logger = logging.getLogger('psq.cli') 

17 

18 

19g_program_name = 'squirrel' 

20 

21 

22def main(args=None): 

23 run( 

24 args=args, 

25 prog=g_program_name, 

26 subcommands=command_modules, 

27 description=''' 

28Pyrocko Squirrel - Prompt seismological data access with a fluffy tail. 

29 

30This is ```squirrel```, a command-line front-end to the Squirrel data access 

31infrastructure. The Squirrel infrastructure offers meta-data caching, blazingly 

32fast data lookup for large datasets and transparent online data download to 

33applications building on it. 

34 

35In most cases, the Squirrel does its business discretely under the hood and 

36does not require human interaction or awareness. However, using this tool, some 

37aspects can be configured for the benefit of greater performance or 

38convenience, including (1) using a separate (isolated, local) environment for a 

39specific project, (2) using named selections to speed up access to very large 

40datasets, (3), pre-scanning/indexing of file collections. It can also be used 

41to inspect various aspects of a data collection. 

42 

43This tool's functionality is available through several subcommands. Run 

44```squirrel SUBCOMMAND --help``` to get further help.''') 

45 

46 

47def run( 

48 args=None, 

49 command=None, 

50 subcommands=[], 

51 description=''' 

52Pyrocko Squirrel based script. 

53 

54Run with --help to get further help.''', 

55 **kwargs): 

56 

57 ''' 

58 Setup and run Squirrel-based application. 

59 

60 The implementation of the tool can be provided by one or multiple 

61 :py:class:`~pyrocko.squirrel.tool.common.SquirrelCommand` instances. This 

62 driver function sets up a 

63 :py:class:`~pyrocko.squirrel.tool.common.SquirrelArgumentParser`, and 

64 processes command line arguments, and dispatches execution to the selected 

65 command or subcommand. The program is set up to provide and automatically 

66 handle ``--help``, ``--loglevel``, and ``--progress``. If an exception of 

67 type :py:exc:`pyrocko.squirrel.error.SquirrelError` or 

68 :py:exc:`pyrocko.squirrel.error.ToolError` is caught, the error is logged 

69 and the program is terminated with exit code 1. 

70 

71 :param args: 

72 Arguments passed to 

73 :py:meth:`~pyrocko.squirrel.tool.common.SquirrelArgumentParser.parse_args`. 

74 By default uses py:attr:`sys.argv`. 

75 :type args: 

76 :py:class:`list` of :py:class:`str` 

77 

78 :param command: 

79 Implementation of the command. It must provide ``setup(parser)`` and 

80 ``run(parser, args)``. 

81 :type command: 

82 :py:class:`~pyrocko.squirrel.tool.common.SquirrelCommand` or module 

83 

84 :param subcommands: 

85 Configures the program to offer multiple subcommands. The command to 

86 execute is selected with the first argument passed to ``args``. 

87 Implementations must provide ``make_subparser(subparsers)``, 

88 ``setup(parser)``, and ``run(parser, args)``. 

89 :type subcommands: 

90 :py:class:`list` of 

91 :py:class:`~pyrocko.squirrel.tool.common.SquirrelCommand` instances or 

92 modules 

93 

94 :param description: 

95 Description of the program. 

96 :type description: 

97 str 

98 ''' 

99 

100 parser = common.SquirrelArgumentParser( 

101 command=command, 

102 subcommands=subcommands, 

103 description=description, **kwargs) 

104 

105 return parser.run(args) 

106 

107 

108__all__ = [ 

109 'main', 

110 'run', 

111]