crash.commands package¶
The crash.commands module is the interface for implementing commands in crash-python.
The only mandatory part of implementing a command is to derive a class
from Command
, implement the Command.execute()
method,
and instantiate it. If the command should have multiple aliases,
accept a name in the constructor and instantiate it multiple times.
Optional extensions:
- Adding a parser (derived from
ArgumentParser
) that parses arguments. If not provided, an empty parser will be used. - Adding a module docstring to be used as help text. If not provided, the argparse generic help text will be used instead.
The module docstring will be placed automatically in the command reference section of the user guide and will also be converted into plaintext help for use in command execution. It should be in reStructuredText format.
Example:
"""
NAME
----
helloworld
SYNOPSYS
--------
``helloworld`` -- a command that prints hello world
"""
import crash.commands
class HelloWorld(crash.commands.Command):
def __init__(self) -> None:
parser = crash.commands.ArgumentParser(prog='helloworld')
super().__init__('helloworld', parser)
def execute(self, args: argparse.Namespace) -> None:
print("hello world")
HelloWorld()
-
class
crash.commands.
ArgumentParser
(*args, **kwargs)[source]¶ Bases:
argparse.ArgumentParser
A simple extension to
argparse.ArgumentParser
that:- Requires a command name be set
- Loads help text automatically from files
- Handles errors by raising
CommandLineError
-
error
(message: str) → Any[source]¶ An error callback that raises the
CommandLineError
exception.
-
class
crash.commands.
Command
(name: str, parser: crash.commands.ArgumentParser = None)[source]¶ Bases:
gdb.Command
The Command class is the starting point for implementing a new command.
The
Command.execute()
method will be invoked when the user invokes the command.Once the constructor returns, the command will be registered with
gdb
and the command will be available for use.Parameters: - name – The name of the command. The string
py
will be prefixed to it. - parser – The parser to use to handle the arguments. It must be derived
from the
ArgumentParser
class.
Raises: ArgumentTypeError
– The parser is not derived fromArgumentParser
.-
execute
(args: argparse.Namespace) → None[source]¶ This method implements the command functionality.
Each command has a derived class associated with it that, minimally, implements this method.
Parameters: args – The arguments to this command already parsed by the commmand’s parser.
-
format_help
() → str[source]¶ Used by the
help
module, it delegates the help formatting to the parser object.
-
invoke
(argstr: str, from_tty: bool = False) → None[source]¶ Invokes the command directly and translates exceptions.
This method is called by
gdb
to implement the command.It translates the
CommandError
,CommandLineError
, andDelayedAttributeError
exceptions into readable error messages.Unless you are doing something special, see
execute()
instead.Parameters: - argstr – The command arguments
- from_tty (default=False) – Whether the command was invoked from a tty.
-
invoke_uncaught
(argstr: str, from_tty: bool = False) → None[source]¶ Invokes the command directly and does not catch exceptions.
This is used mainly for unit testing to ensure proper exceptions are raised.
Unless you are doing something special, see
execute()
instead.Parameters: - argstr – The command arguments
- from_tty (default=False) – Whether the command was invoked from a tty.
- name – The name of the command. The string
-
exception
crash.commands.
CommandError
[source]¶ Bases:
RuntimeError
An error occured while executing this command