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.

format_help() → str[source]

A help formatter that loads the parsed rST documentation from disk or returns the generic help text otherwise.

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 from ArgumentParser.
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, and DelayedAttributeError 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.
exception crash.commands.CommandError[source]

Bases: RuntimeError

An error occured while executing this command

exception crash.commands.CommandLineError[source]

Bases: RuntimeError

An error occured while handling the command line for this command

crash.commands.discover() → None[source]