rbtools.commands¶

Base support for creating commands.

Functions

Classes

Exceptions

exception rbtools.commands.CommandExit(exit_code=0)[source]¶

Bases: Exception

__init__(exit_code=0)[source]¶

exception rbtools.commands.CommandError[source]¶

Bases: Exception

exception rbtools.commands.ParseError[source]¶

Bases: CommandError

class rbtools.commands.JSONOutput(output_stream)[source]¶

Bases: object

Output wrapper for JSON output.

JSON outputter class that stores Command outputs in python dictionary and outputs as JSON object to output stream object. Commands should add any structured output to this object. JSON output is then enabled with the –json argument.

New in version 3.0.

__init__(output_stream)[source]¶

Initialize JSONOutput class.

Parameters:

output_stream (Object) – Object to output JSON object to.

add(key, value)[source]¶

Add a new key value pair.

Parameters:

• key (unicode) – The key associated with the value to be added to dictionary.

• value (object) – The value to attach to the key in the dictionary.

append(key, value)[source]¶

Add new value to an existing list associated with key.

Parameters:

• key (unicode) – The key associated with the list to append to.

• value (object) – The value to append to the list associated with key.

Raises:

• KeyError – The key was not found in the state.

• AttributeError – The existing value was not a list.

add_error(error)[source]¶

Add new error to ‘errors’ key.

Append a new error to the errors key, creating one if needed.

Parameters:

error (unicode) – The error that will be added to errors.

add_warning(warning)[source]¶

Add new warning to ‘warnings’ key.

Append a new warning to the warnings key, creating one if needed.

Parameters:

warning (unicode) – The warning that will be added to warnings.

print_to_stream()[source]¶

Output JSON string representation to output stream.

class rbtools.commands.SmartHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]¶

Bases: HelpFormatter

Smartly formats help text, preserving paragraphs.

class rbtools.commands.OutputWrapper(output_stream)[source]¶

Bases: object

Wrapper for output of a command.

Wrapper around some output object that handles outputting messages. Child classes specify the default object. The wrapper can handle messages in either unicode or bytes.

New in version 3.0.

__init__(output_stream)[source]¶

Initialize with an output object to stream to.

Parameters:

output_stream (object) – The output stream to send command output to.

write(msg, end='\n')[source]¶

Write a message to the output stream.

Write a string to output stream object if defined, otherwise do nothing. end specifies a string that should be appended to the end of msg before being given to the output stream.

Parameters:

• msg (unicode) – String to write to output stream.

• end (unicode, optional) – String to append to end of msg. This defaults to \n`.

new_line()[source]¶

Pass a new line character to output stream object.

class rbtools.commands.Option(*opts, **attrs)[source]¶

Bases: object

Represents an option for a command.

The arguments to the constructor should be treated like those to argparse’s add_argument, with the exception that the keyword argument ‘config_key’ is also valid. If config_key is provided it will be used to retrieve the config value as a default if the option is not specified. This will take precedence over the default argument.

Serves as a wrapper around the ArgumentParser options, allowing us to specify defaults which will be grabbed from the configuration after it is loaded.

__init__(*opts, **attrs)[source]¶

add_to(parent, config={}, argv=[])[source]¶

Adds the option to the parent parser or group.

If the option maps to a configuration key, this will handle figuring out the correct default.

Once we’ve determined the right set of flags, the option will be added to the parser.

class rbtools.commands.OptionGroup(name=None, description=None, option_list=[])[source]¶

Bases: object

Represents a named group of options.

Each group has a name, an optional description, and a list of options. It serves as a way to organize related options, making it easier for users to scan for the options they want.

This works like argparse’s argument groups, but is designed to work with our special Option class.

__init__(name=None, description=None, option_list=[])[source]¶

add_to(parser, config={}, argv=[])[source]¶

Add the group and all its contained options to the parser.

Parameters:

• parser (argparse.ArgumentParser) – The command-line parser.

• config (dict) – The loaded RBTools configuration.

• argv (list, deprecated) – Unused legacy argument.

class rbtools.commands.LogLevelFilter(level)[source]¶

Bases: Filter

Filters log messages of a given level.

Only log messages that have the specified level will be allowed by this filter. This prevents propagation of higher level types to lower log handlers.

__init__(level)[source]¶

Initialize a filter.

Initialize with the name of the logger which, together with its children, will have its events allowed through the filter. If no name is specified, allow every event.

filter(record)[source]¶

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

class rbtools.commands.Command(transport_cls=<class 'rbtools.api.transport.sync.SyncTransport'>, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin=<_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>)[source]¶

Bases: object

Base class for rb commands.

This class will handle retrieving the configuration, and parsing command line options.

usage is a list of usage strings each showing a use case. These should not include the main rbt command or the command name; they will be added automatically.

api_client¶

The API client. This will be None if needs_api is False.

Type:

rbtools.api.client.RBClient

api_root¶

The API root resource. This will be None if needs_api is False.

Type:

rbtools.api.resource.RootResource

capabilities¶

The API capabilities object. This will be None if needs_api is False.

Type:

rbtools.api.capabilities.Capabilities

repository¶

The API resource corresponding to the repository.

Type:

rbtools.api.resource.ItemResource

repository_info¶

The repository info object. This will be None if needs_scm_client is False.

Type:

rbtools.clients.base.repository.RepositoryInfo

server_url¶

The URL to the Review Board server.

Type:

unicode

stdout¶

Standard unicode output wrapper that subclasses must write to.

Type:

OutputWrapper

stdout_is_atty¶

Whether stdout is connected to a TTY or similar device.

New in version 3.1.

Type:

bool

stderr¶

Standard unicode error output wrapper that subclasses must write to.

Type:

OutputWrapper

stderr_is_atty¶

Whether stderr is connected to a TTY or similar device.

New in version 3.1.

Type:

bool

stdin¶

Standard input.

New in version 3.1.

Type:

io.TextIOWrapper

stdin_is_atty¶

Whether stdin is connected to a TTY or similar device.

New in version 3.1.

Type:

bool

stdout_bytes¶

Standard byte output wrapper that subclasses must write to.

Type:

OutputWrapper

stderr_bytes¶

Standard byte error output wrapper that subclasses must write to.

Type:

OutputWrapper

tool¶

The SCM client. This will be None if needs_scm_client is False.

Type:

rbtools.clients.base.BaseSCMClient

name = ''[source]¶

The name of the command.

Type:

unicode

author = ''[source]¶

The author of the command.

Type:

unicode

description = ''[source]¶

A short description of the command, suitable for display in usage text.

Type:

unicode

needs_api = False[source]¶

Whether the command needs the API client.

If this is set, the initialization of the command will set api_client and api_root.

New in version 3.0.

Type:

bool

needs_diffs = False[source]¶

Whether the command needs to generate diffs.

If this is set, the initialization of the command will check for the presence of a diff tool compatible with the chosen type of repository.

This depends on needs_repository and needs_scm_client both being set to True.

New in version 4.0.

Type:

bool

needs_scm_client = False[source]¶

Whether the command needs the SCM client.

If this is set, the initialization of the command will set repository_info and tool.

New in version 3.0.

Type:

bool

needs_repository = False[source]¶

Whether the command needs the remote repository object.

If this is set, the initialization of the command will set repository.

New in version 3.0.

Type:

bool

args = ''[source]¶

Usage text for what arguments the command takes.

Arguments for the command are anything passed in other than defined options (for example, revisions passed to rbt post).

Type:

unicode

option_list = [][source]¶

Command-line options for this command.

Type:

list of Option or OptionGroup

server_options = <rbtools.commands.OptionGroup object>[source]¶

repository_options = <rbtools.commands.OptionGroup object>[source]¶

diff_options = <rbtools.commands.OptionGroup object>[source]¶

branch_options = <rbtools.commands.OptionGroup object>[source]¶

git_options = <rbtools.commands.OptionGroup object>[source]¶

perforce_options = <rbtools.commands.OptionGroup object>[source]¶

subversion_options = <rbtools.commands.OptionGroup object>[source]¶

tfs_options = <rbtools.commands.OptionGroup object>[source]¶

default_transport_cls[source]¶

alias of SyncTransport

__init__(transport_cls=<class 'rbtools.api.transport.sync.SyncTransport'>, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin=<_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>)[source]¶

Initialize the base functionality for the command.

Parameters:

• transport_cls (rbtools.api.transport.Transport, optional) – The transport class used for all API communication. By default, this uses the transport defined in default_transport_cls.

• stdout (io.TextIOWrapper, optional) –

  The standard output stream. This can be used to capture output programmatically.

  New in version 3.1.

• stderr (io.TextIOWrapper, optional) –

  The standard error stream. This can be used to capture errors programmatically.

  New in version 3.1.

• stdin (io.TextIOWrapper, optional) –

  The standard input stream. This can be used to provide input programmatically.

  New in version 3.1.

create_parser(config, argv=[])[source]¶

Create and return the argument parser for this command.

post_process_options()[source]¶

usage()[source]¶

Return a usage string for the command.

initialize()[source]¶

Initialize the command.

This will set up various prerequisites for commands. Individual command subclasses can control what gets done by setting the various needs_* attributes (as documented in this class).

create_arg_parser(argv)[source]¶

Create and return the argument parser.

Parameters:

argv (list of unicode) – A list of command line arguments

Returns:

Argument parser for commandline arguments

Return type:

argparse.ArgumentParser

run_from_argv(argv)[source]¶

Execute the command using the provided arguments.

The options and commandline arguments will be parsed from argv and the commands main method will be called.

initialize_scm_tool(client_name=None, require_repository_info=True)[source]¶

Initialize the SCM tool for the current working directory.

Parameters:

• client_name (unicode, optional) – A specific client name, which can come from the configuration. This can be used to disambiguate if there are nested repositories, or to speed up detection.

• require_repository_info (bool, optional) – Whether information on a repository is required. This is the default. If disabled, this will return None for the repository information if a matching repository could not be found.

Returns:

A 2-tuple, containing the repository info structure and the tool instance.

Return type:

tuple

setup_tool(tool, api_root=None)[source]¶

Performs extra initialization on the tool.

If api_root is not provided we’ll assume we want to initialize the tool using only local information

get_server_url(repository_info, tool)[source]¶

Return the Review Board server url.

Parameters:

• repository_info (rbtools.clients.base.repository.RepositoryInfo, optional) – Information about the current repository

• tool (rbtools.clients.base.BaseSCMClient, optional) – The repository client.

Returns:

The server URL.

Return type:

unicode

credentials_prompt(realm, uri, username=None, password=None, *args, **kwargs)[source]¶

Prompt the user for credentials using the command line.

This will prompt the user, and then return the provided username and password. This is used as a callback in the API when the user requires authorization.

otp_token_prompt(uri, token_method, *args, **kwargs)[source]¶

Prompt the user for a one-time password token.

Their account is configured with two-factor authentication. The server will have sent a token to their configured mobile device or application. The user will be prompted for this token.

get_api(server_url)[source]¶

Returns an RBClient instance and the associated root resource.

Commands should use this method to gain access to the API, instead of instantianting their own client.

get_capabilities(api_root: RootResource) → Capabilities[source]¶

Retrieve capabilities from the server and return them.

Parameters:

api_root (rbtools.api.resource.RootResource) – The root resource

Returns:

The server capabilities.

Return type:

rbtools.api.capabilities.Capabilities

main(*args)[source]¶

The main logic of the command.

This method should be overridden to implement the commands functionality.

class rbtools.commands.BaseSubCommand(options, config, *args, **kwargs)[source]¶

Bases: Command

Abstract base class for a subcommand.

help_text = ''[source]¶

The subcommand’s help text.

Type:

unicode

__init__(options, config, *args, **kwargs)[source]¶

Initialize the subcommand.

Parameters:

• options (argparse.Namespace) – The parsed options.

• config (dict) – The loaded RBTools configuration.

• *args (list) – Positional arguments to pass to the Command class.

• **kwargs (dict) – Keyword arguments to pass to the Command class.

class rbtools.commands.BaseMultiCommand(transport_cls=<class 'rbtools.api.transport.sync.SyncTransport'>, stdout=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin=<_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>)[source]¶

Bases: Command

Abstract base class for commands which offer subcommands.

Some commands (such as rbt review) want to offer many subcommands.

New in version 3.0.

subcommands = {}[source]¶

The available subcommands.

This is a list of BaseSubCommand sub classes.

Type:

list

common_subcommand_option_list = [][source]¶

Options common to all subcommands.

Type:

list

usage(command_cls=None)[source]¶

Return a usage string for the command.

Parameters:

command_cls (type, optional) – The subcommand class to generate usage information for.

Returns:

The usage string.

Return type:

unicode

create_parser(config, argv=[])[source]¶

Create and return the argument parser for this command.

Parameters:

• config (dict) – The loaded RBTools config.

• argv (list, optional) – The argument list.

Returns:

The argument parser.

Return type:

argparse.ArgumentParser

initialize()[source]¶

Initialize the command.

main()[source]¶

Run the command.

rbtools.commands.find_entry_point_for_command(command_name)[source]¶

Return an entry point for the given rbtools command.

If no entry point is found, None is returned.

rbtools.commands.command_exists(cmd_name)[source]¶

Determine if the given command exists.

This function checks for the existence of an RBTools command entry point with the given name and an executable named rbt-“cmd_name” on the path. Aliases are not considered.