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.monitor - From
ArgumentParser.add_monitor_argument()
iface - From
ArgumentParser.add_interface_argument()
prompt - From
ArgumentParser.add_prompt_argument()
extra - From
ArgumentParser.add_extra_argument()
The following items are optional:
config - From
ArgumentParser.add_config_argument()
companion - From
ArgumentParser.add_companion_argument()
allow_deploy - From
ArgumentParser.add_allow_deploy_argument()
skip_deploy - From
ArgumentParser.add_skip_deploy_argument()
allow_reboot - From
ArgumentParser.add_allow_reboot_argument()
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>
inadd_<x>_argument
.When using this init_args approach, keyword arguments prefixed with
<x>_
will be to the correspondingadd_<x>_argument
, sans prefix.- DEFAULT_ARGS = ['arch', 'config', 'interface', 'companion', 'monitor', 'extra', 'prompt', 'allow_deploy', 'skip_deploy', 'allow_reboot']
list
: Default list used byArgumentParser.__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
.