tracktable.script_helpers.argument_groups module

Submodules

Module contents

These are the predefined argument groups that come with Tracktable.

Argument groups: sets of co-occurring command line arguments

The various capabilities in Tracktable tend to have several arguments. If we want to expose those in scripts we wind up making a lot of calls to argparse and then spending a lot of time handling the arguments. This file collects utilities for

  1. defining sets of arguments for later use,

(2) creating example ‘response files’ (text files that contain lots of ‘–arg value’ pairs) for the user to customize,

(3) performing initial parsing of a set of arguments to recursively expand response files.

Here is an example of how to create and populate an argument group:

create_argument_group('example', title='Sample Argument Group', description='This argument group exists to demonstrate what response files look like.')
add_argument('example', [ '--string-arg', '-s' ], help='An argument with a string value', default='Foo!')
add_argument('example', [ '--integer-arg', '-i' ], help='An integer argument', default=3)
add_argument('example', [ '--other' ], help='A required other argument with no default', required=Tru)
tracktable.script_helpers.argument_groups.add_argument(group_name, option_names, **kwargs)

Add a single command-line argument to a group.

Parameters

  • group_name (string) – Name for conceptual group of arguments (such as ‘movie’ for movie-making parameters)

  • option_names (list) – A list of command-line options that can be used to specify this argument (such as [ ‘–frame-rate’, ‘-f’ ])

  • requested. (All other arguments will be passed straight to argparse.add_argument() when this argument group is) –

Returns

The name of the argument just added.

Raises

KeyError – the specified argument group does not exist.

Examples

>>> add_argument('movies', [ '--frame-rate', '-f' ],
                 help='Desired frame rate for movie',
                 type=int,
                 default=30)
'--frame-rate'

>>> add_argument('nonexistent_group', [ '--foo', '-g' ])
XXX INSERT ERROR MESSAGES
tracktable.script_helpers.argument_groups.available_argument_groups()

Return a list of all available argument groups.

Parameters

None –

Returns

A list of strings, each the name of a registered argument group

tracktable.script_helpers.argument_groups.create_argument_group(group_name, title=None, description=None)

Register a new, empty group of arguments

Arguments to configure different capabilities tend to come in groups. For example, movie-making includes frames per second, movie duration, encoder type and encoder options. This function lets you create such subject-related groups.

Note that this function only creates the group. You still have to populate it using register_argument (q.v.).

Parameters

  • group_name (string) – Name of the group you want to add.

  • title (string) – Title of the group. Not required but highly recommended.

  • description (string) – Description / help text. Not required but highly recommended.

Returns

The name of the group just added.

tracktable.script_helpers.argument_groups.extract_arguments(group_name, parsed_args, switch_character='-')

Extract a group of arguments from a Namespace into a dict

Argument groups make it easy to include a batch of options all at once. This function is the next step: after you’ve used argparse.ArgumentParser to parse a set of command-line arguments, you use extract_arguments to extract a group of arguments into a dict. This dict can then be passed on to a function as a set of keyword arguments.

The difference between this and calling vals() on the namespace returned by parse_args() is that this pulls out just the arguments associated with the specified group.

Parameters

  • group_name – A string naming the group to extract

  • parsed_args – A Namespace object returned from argparse.ArgumentParser.parse_args()

  • switch_character – Character used to prefix switches, e.g. ‘-’ for options like ‘–foo’ and ‘-f’

Returns

A dict() whose names are the destinations (*) associated with the command-line arguments and whose values are the values from the command line

Raises

KeyError – The desired argument group doesn’t exist

tracktable.script_helpers.argument_groups.use_argument_group(group_name, parser)

Add a group of arguments to a parser.

Parameters

  • group_name – Name of the desired group of arguments

  • parser – An instance of argparse.ArgumentParser

Returns

Parser after the arguments have been added

Raises

KeyError – the desired argument group does not exist

Once you have registered one or more arguments in a group, call use_arguments to add them to a parser. They will be added to a group in that parser.

Examples: XXX TODO