rbtools.commands.base.commands¶

Base classes for commands.

New in version 5.0.

Classes

`BaseCommand`([transport_cls, stdout, stderr, ...])	Base class for RBTools commands.
`BaseMultiCommand`([transport_cls, stdout, ...])	Abstract base class for commands which offer subcommands.
`BaseSubCommand`(options, config, args, *kwargs)	Abstract base class for a subcommand.
`LogLevelFilter`(level)	Filters log messages of a given level.
`SmartHelpFormatter`(prog[, indent_increment, ...])	Smartly formats help text, preserving paragraphs.

class rbtools.commands.base.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.base.commands.SmartHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]¶

Bases: HelpFormatter

Smartly formats help text, preserving paragraphs.

Changed in version 5.0: This moved from rbtools.commands to rbtools.commands.base.commands.

class rbtools.commands.base.commands.BaseCommand(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 RBTools 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.

Changed in version 5.0: This moved from rbtools.commands to rbtools.commands.base.commands.

name: str = ''¶

The name of the command.

Type:: str

author: str = ''¶

The author of the command.

Type:: str

description: str = ''¶

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

Type:: str

needs_api: bool = False¶

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: bool = False¶

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: bool = False¶

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: bool = False¶

Whether the command needs the remote repository object.

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

Setting this will imply setting both needs_api and needs_scm_client to True.

New in version 3.0.

Type:: bool

args: str = ''¶

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:: str

option_list: List[Union[Option, OptionGroup]] = []¶

Command-line options for this command.

Type:: list of Option or OptionGroup

options: argparse.Namespace¶: Options parsed for the command.

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

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

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

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

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

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

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

tfs_options = <rbtools.commands.base.options.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.

log: logging.Logger¶: A logger for the command.

transport_cls: Type[Transport]¶: The transport class used for talking to the API.

api_client: Optional[RBClient]¶

The client used to connect to the API.

This will be set when the command is run if needs_api is True. Otherwise it will be None.

api_root: Optional[RootResource]¶

The root of the API tree.

This will be set when the command is run if needs_api is True. Otherwise it will be None.

capabilities: Optional[Capabilities]¶

Capabilities set by the API.

This will be set when the command is run if needs_api is True. Otherwise it will be None.

repository: Optional[Resource]¶

The resource for the matching repository.

This will be set when the command is run if both needs_api and needs_repository are True.

repository_info: Optional[RepositoryInfo]¶

Information on the local repository.

This will be set when the command is run if needs_scm_client is run. Otherwise it will be None.

server_url: Optional[str]¶

The URL to the Review Board server.

This will be set when the command is run if needs_api is True.

tool: Optional[BaseSCMClient]¶

The client/tool used to communicate with the repository.

This will be set when the command is run if needs_scm_client is run. Otherwise it will be None.

config: RBToolsConfig¶: The loaded configuration for RBTools.

Changed in version 5.0: This is now a RBToolsConfig instance, instead of a plain dictionary.

stdout: OutputWrapper¶

The stream for writing standard output as Unicode strings.

Commands should write text using this instead of print() or sys.stdout().

stderr: OutputWrapper¶

The stream for writing error output as Unicode strings.

Commands should write error text using this instead of print() or sys.stderr().

stdin: TextIO¶

The stream for reading standard input.

Commands should read input from here instead of using sys.stdin().

New in version 3.1.

stdout_is_atty: bool¶

Whether the stdout stream is from an interactive session.

This applies to stdout.

New in version 3.1.

stderr_is_atty: bool¶

Whether the stderr stream is from an interactive session.

This applies to stderr.

New in version 3.1.

stdin_is_atty: bool¶

Whether the stdin stream is from an interactive session.

This applies to stdin.

New in version 3.1.

stderr_bytes: OutputWrapper¶

The stream for writing error output as byte strings.

Commands should write error text using this instead of print() or sys.stderr().

stdout_bytes: OutputWrapper¶

The stream for writing standard output as byte strings.

Commands should write text using this instead of print() or sys.stdout().

json: JSONOutput¶

An output buffer for JSON results.

Commands can set this to return data used when a command is passed --json.

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.base.commands.BaseSubCommand(options, config, *args, **kwargs)[source]¶

Bases: BaseCommand

Abstract base class for a subcommand.

help_text: str = ''¶

The subcommand’s help text.

Type:: str

__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.base.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: BaseCommand

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: List[Type[BaseSubCommand]] = []¶

The available subcommands.

This is a list of BaseSubCommand subclasses.

Type:: list

common_subcommand_option_list: List[Union[Option, OptionGroup]] = []¶

Options common to all subcommands.

Type:: list

subcommand: BaseSubCommand¶: The currently-running subcommand.

subcommand_parsers: Dict[str, argparse.ArgumentParser]¶: A mapping of subcommand names to argument parsers.

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.