depthcharge.cmdline

The depthcharge.cmdline module provides functionality to help create consistent command line interfaces atop of the Depthcharge API. This includes a set of common argument flags and handlers.

This module includes Depthcharge’s own ArgumentParser class that wraps the standard Python argparse.Argumentparser as well as custom argparse.Action classes.

depthcharge.cmdline.create_depthcharge_ctx(args, **kwargs)

Create and return an initialized Depthcharge handle based upon command-line arguments. Examples of this function’s usage can be found in the Depthcharge scripts.

The args parameter should contain the results of ArgumentParser.parse_args().

The following must be included in the args Namespace, even if set to their unspecified (e.g. default, None) values.

The following items are optional:

ArgumentParser (Extension)

class depthcharge.cmdline.ArgumentParser(init_args='default', **kwargs)

This class is an extension of Python’s own argparse.ArgumentParser that adds Depthcharge-specific argument handler initializations.

The init_args parameter provides a simple way to configure the parser in situations where add_<x>_argument() methods would only be called with their default arguments. Instead, init_args can be provided as a list of strings, with each string corresponding to the <x> in add_<x>_argument.

When using this init_args approach, keyword arguments prefixed with <x>_ will be to the corresponding add_<x>_argument, sans prefix.

DEFAULT_ARGS = ['arch', 'config', 'interface', 'companion', 'monitor', 'extra', 'prompt', 'allow_deploy', 'skip_deploy', 'allow_reboot']

list : Default list used by ArgumentParser.__init__() unless otherwise overridden with a caller-provided list.

add_address_argument(**kwargs)

Add a memory address argument to the ArgumentParser.

add_arch_argument(**kwargs)

Add a CPU architecture argument to the ArgumentParser.

add_companion_argument(**kwargs)

Add an argument to the ArgumentParser that can be used to specify a Depthcharge Companion device and its corresponding settings.

add_config_argument(**kwargs)

Add the device configuration argument to the ArgumentParser.

add_data_argument(**kwargs)

Add an option to provide data as a hex string to the ArgumentParser.

The caller is required to provide help text in order to describe the nature of the data users must provide.

add_extra_argument(**kwargs)

Add an option to allow scripts to provide “extra” arguments via the command line, which translate directly to **kwargs passed to Depthcharge API calls.

add_file_argument(**kwargs)

Add a file argument to the ArgumentParser.

The caller must provide the help text in order to specify the purpose of this file, and whether it is an input or output file.

add_interface_argument(**kwargs)

Add a serial console interface option the the ArgumentParser.

add_op_argument(**kwargs)

Add an argument to allow desired depthcharge.Operation implementations to be requested, by name.

add_length_argument(**kwargs)

Add a length argument to the ArgumentParser.

Default help text describes a read operation, in bytes.

add_monitor_argument(**kwargs)

Add a serial port monitor argument to the ArgumentParser.

add_allow_reboot_argument(**kwargs)

Add and argument that allows the user to opt-in to functionality that necessitates crashing or rebooting the target platform.

add_outfile_argument(**kwargs)

Add an output file argument to the ArgumentParser.

If a script only outputs a file, use add_file_argument().

Otherwise, if a script both reads and writes different files, use add_file_argument() for the input file and this method for the output file.

The caller is required to provide the help argument.

add_prompt_argument(**kwargs)

Add an option to the ArgumentParser to allow for the expected U-Boot prompt to be supplied via the command line.

add_allow_deploy_argument(**kwargs)

Add an opt-in option to the ArgumentParser that specifies that the user wants to allow payload deployment and execution.

add_skip_deploy_argument(**kwargs)

Add an option to the ArgumentParser to allow payload deployment to be skipped in situations where a prior script or command has already done this. (They still want to execute payloads.)

add_stratagem_argument(**kwargs)

Add an option to the ArgumentParser to allow a user to supply a file containing a depthcharge.Stratagem JSON file.

The caller must provide help text specifying the purpose of the stratagem file (e.g. whether its being produced or is an input).

ArgumentParser Actions

class depthcharge.cmdline.AddressAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

ArgumentParser Action for validating memory and device addresses.

The following suffixes are supported:

  • kB = 1000

  • K or kiB = 1024

  • MB = 1000 * 1000

  • M or MiB = 1024 * 1024

  • GB = 1000 * 1000 * 1000

  • G or GiB = 1024 * 1024 * 1024

class depthcharge.cmdline.CompanionAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

ArgumentParser Action for handling Companion arguments.

This may be used to convert args.companion converted to a tuple in the form:

(device, params={key: value})

class depthcharge.cmdline.ListAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

ArgumentParser action for creating lists from comma-separated strings.

For example, --op foo,bar,baz --op fizz,buzz would result in the list [foo, bar, baz, fizz, buzz].

class depthcharge.cmdline.KeyValListAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

ArgumentParser Action for converting arguments of the form:

-X foo=bar,baz -X hello=world -X fortytwo

to a dictionary containing:

{'foo': 'bar', 'baz': True, 'hello': 'world', 'fortytwo': True }

class depthcharge.cmdline.LengthAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

ArgumentParser action for parsing length values with support for the same suffixes supported by AddressAction.