tbot.error

exception tbot.error.TbotException

Bases: Exception

Base-class for all exceptions which are specific to tbot.

exception tbot.error.ApiViolationError

Bases: TbotException, RuntimeError

Base-class for all exceptions that are raised due to wrong use of tbot’s API.

Seeing this exception means that the calling code has a bug and needs to be fixed. This is in contrast to tbot.error.MachineError which is the base-class for exceptions raised due to unexpected occurrences on the remote side during a test-run.

The subclasses of ApiViolationError should detail in their documentation how to fix them.

New in version 0.10.2.

exception tbot.error.MachineError

Bases: TbotException

Base-class for exceptions raised due to remote machine errors.

Usually, this indicates something is wrong with the remote systems that tbot was interacting with. This is in contrast to tbot.error.ApiViolationError which is raised when downstream code has a bug and/or misuses the tbot API.

New in version 0.10.2.

exception tbot.error.AbstractMethodError(method: str | None = None)

Bases: ApiViolationError, NotImplementedError

A method which needs to be overwritten was called from code. This shouldn’t ever really happen in practice hopefully …

exception tbot.error.WrongHostError(arg: Any, host: machine.Machine)

Bases: ApiViolationError, ValueError

A method was called with arguments that reference a different host.

exception tbot.error.ContextError

Bases: ApiViolationError, RuntimeError

A forbidden or wrong kind of interaction with tbot’s context was attempted.

The exception message will include more details. As an example, this exception is raised when requesting an instance that is currently exclusively requested elsewhere.

New in version 0.10.2.

exception tbot.error.MachineNotFoundError

Bases: ApiViolationError, IndexError

The requested machine was not found in the tbot context.

The most likely cause for this is that the selected configuration did not register a machine for the requested role.

New in version 0.10.2.

exception tbot.error.CommandFailure(host: machine.Machine, cmd: Any, *, repr: str | None = None)

Bases: MachineError

A command exited with non-zero exit code.

This exception is raised by exec0() methods to indicate command failures.

New in version 0.10.2.

repr: str

String representation of the command which failed.

Should only be used for diagnostic purposes.

host: machine.Machine

The host where the failed command was executed.

This host may or may not be available at the time of catching the exception, depending on how far the exception was bubbled up.

cmd: Any

The original form of the command, usually a list of arguments.

For a readable and displayable version, use the repr field instead.

exception tbot.error.ChannelClosedError

Bases: MachineError

Error type for exceptions when a channel was closed unexpectedly.

This error is raised when interaction with a channel is attemped which was either closed explicitly beforehand or which was closed unexpectedly by the remote end.

New in version 0.10.2.

exception tbot.error.UncleanShellError(host: machine.Machine)

Bases: MachineError

While trying to prepare the remote shell, tbot detected unexpected behavior.

This error means that the shell responded with unexpected output during setup. tbot cannot proceed to interact, as it cannot be certain about the state of the remote shell.

If you encounter this error, enable verbose channel logging to see what unexpected output was received. You need to ensure that the remote system does not send this additional output.

New in version 0.10.8.

exception tbot.error.InvalidRetcodeError(host: machine.Machine, retcode_str: str)

Bases: MachineError

While trying to fetch the return code of a command, unexpected output was received.

This error usually indicates some deeper issue with the machine connection. For example, there could be kernel log messages being printed in between command output.

New in version 0.10.7.

exception tbot.error.MissingToolError(host: machine.Machine, need_one_of: List[str], message: str | None = None)

Bases: MachineError

A tool that is needed for a testcase is not installed on the respective machine.

The usual solution is to install one of the listed tools.

New in version 0.10.8.

exception tbot.error.ChannelBorrowedError

Bases: ApiViolationError

Error type for exceptions when accessing a channel which is currently borrowed.

This error will be raised when an attempt is made to interact with a channel which is currently borrowed. As an example, when an interactive command is started with LinuxShell.run(), while this command is running, the channel of the LinuxShell is borrowed and cannot be used. So a call to, for example, exec0() during this time would raise ChannelBorrowedError.

New in version 0.10.2.

exception tbot.error.ChannelTakenError

Bases: ApiViolationError

Error type for exceptions when accessing a channel which was “taken”.

This error will be raised when an attempt is made to interact with a channel which is was “taken”. The channel docs contain more details about this concept. Essentially, a different machine now uses the channel so it can no longer be accessed from its previous “owner”.

New in version 0.10.2.

exception tbot.error.IllegalDataException

Bases: ApiViolationError

Raised when attempting to write illegal data to a channel.

Some channels cannot deal with all byte sequences. For example, certain escape sequences will mess up the connection. If an attempt is made to send such data, this exception is raised. The exact set of illegal sequences depends on the specific machine configuration.

In most situations, the shell implementation will escape such data correctly. This error should only become relevant when directly interacting with a channel.

New in version 0.10.2.

exception tbot.error.UnboundedPatternError(pattern: bytes)

Bases: ApiViolationError, ValueError

Raised when a regex pattern is used which does not have a bounded length.

tbot requires the use of patterns with a bounded length to keep track of incoming data efficiently. A bounded pattern is one which does not use any infinitely repeating expressions.

For example, r".*" is unbounded, but r".{0,80}" is.

New in version 0.10.8.