rbtools.commands.base.commands¶

Base classes for commands.

Added in version 5.0.

Classes

`BaseCommand`(transport_cls, stdout, stderr, stdin)	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.BaseCommand(transport_cls: type[Transport] = <class 'rbtools.api.transport.sync.SyncTransport'>, stdout: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr: TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: TextIO = <_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.

__firstlineno__ = 143¶

__init__(transport_cls: type[Transport] = <class 'rbtools.api.transport.sync.SyncTransport'>, stdout: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr: TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: TextIO = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>) → None[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.

Added in version 3.1.
stderr (io.TextIOWrapper, optional) –
The standard error stream. This can be used to capture errors programmatically.

Added in version 3.1.
stdin (io.TextIOWrapper, optional) –
The standard input stream. This can be used to provide input programmatically.

Added in version 3.1.

__static_attributes__ = ('api_client', 'api_root', 'capabilities', 'config', 'json', 'log', 'needs_api', 'needs_scm_client', 'options', 'repository', 'repository_info', 'server_url', 'stderr', 'stderr_bytes', 'stderr_is_atty', 'stdin', 'stdin_is_atty', 'stdout', 'stdout_bytes', 'stdout_is_atty', 'tool', 'transport_cls')¶

api_client: RBClient | None¶

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: RootResource | None¶

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.

args: ClassVar[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

author: ClassVar[str] = ''¶

The author of the command.

Type:: str

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

capabilities: Capabilities | None¶

Capabilities set by the API.

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

config: RBToolsConfig | None¶: The loaded configuration for RBTools.

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

create_arg_parser(argv: list[str], *, color: bool = True) → argparse.ArgumentParser[source]¶

Create and return the argument parser.

Changed in version 6.0: Added the color argument.

Parameters:

argv (list of str) – A list of command line arguments
color (bool, optional) –
Whether to output color, if supported in the environment.

This will output color on Python 3.14 and higher by default.

Added in version 6.0.

Returns:

Argument parser for commandline arguments

Return type:

argparse.ArgumentParser

create_parser(config: RBToolsConfig, argv: list[str] | None = None, *, color: bool = True) → argparse.ArgumentParser[source]¶

Return a new argument parser for this command.

Changed in version 6.0: Added the color argument.

Parameters:

config (dict) – The loaded RBTools configuration.
argv (list of str) – The list of command line arguments.
color (bool, optional) –
Whether to output color, if supported in the environment.

This will output color on Python 3.14 and higher by default.

Added in version 6.0.

Returns:

The new argument parser for the command.

Return type:

argparse.ArgumentParser

credentials_prompt(realm: str, uri: str, username: str | None = None, password: str | None = None, *args, **kwargs) → tuple[str, str][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.

Parameters:

realm (str) – The HTTP realm.
uri (str) – The URI of the endpoint requiring authentication.
username (str, optional) – The default username for authentication.
password (str, optional) – The default password for authentication.
*args (tuple, unused) – Unused additional positional arguments.
**kwargs (dict, unused) – Unused additional keyword arguments.

Returns:

A 2-tuple of:

Tuple:

username (str) – The user-provided username.
password (str) – The user-provided password.

Return type:

tuple

Raises:

rbtools.commands.base.errors.CommandError – HTTP authentication failed.

default_transport_cls[source]¶: alias of SyncTransport

description: ClassVar[str] = ''¶

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

Type:: str

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

get_api(server_url: str) → tuple[RBClient, RootResource][source]¶

Return an RBClient instance and the associated root resource.

Commands should use this method to gain access to the API, instead of instantiating their own client. This will set the api_client attribute.

Changed in version 6.0: This now sets the api_client attribute as soon as the client is instantiated.

Parameters:

server_url (str) – The URL to the Review Board server.

Returns:

A 2-tuple of:

Tuple:

0 (rbtools.api.client.RBClient) – The new API client.
1 (rbtools.api.resource.RootResource) – The root resource for the API.

Return type:

tuple

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

get_options_flat() → Sequence[Option][source]¶

Return a list of all options for the command.

This returns a flat list of options, pulling out the options that are inside any option groups set on the command.

Added in version 6.0.

Returns:: The list of options for the command.
Return type:: list of rbtools.commands.base.options.Option

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

initialize() → None[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).

Raises:

rbtools.commands.base.errors.CommandError – An error occurred while initializing the command.
rbtools.commands.base.errors.NeedsReinitialize – The initialization process needs to be restarted (due to loading additional config).

initialize_scm_tool(client_name: str | None = None, *, tool_required: bool = True) → tuple[RepositoryInfo | None, BaseSCMClient | None][source]¶

Initialize the SCM tool for the current working directory.

Changed in version 5.0.3: Added the tool_required argument.

Changed in version 5.0: Removed deprecated require_repository_info argument.

Parameters:

client_name (str, 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.
tool_required (bool, optional) –
Whether a tool is required to be found or not.

Added in version 5.0.3.

Returns:

A 2-tuple:

Tuple:

0 (rbtools.clients.base.repository.RepositoryInfo) – The repository information.
1 (rbtools.clients.base.scmclient.BaseSCMClient) – The SCMTool client instance.

Return type:

tuple

json: JSONOutput¶

An output buffer for JSON results.

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

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

main(*args) → int[source]¶

Run the main logic of the command.

This method should be overridden to implement the commands functionality.

Parameters:: *args (tuple) – Positional arguments passed to the command.
Returns:: The resulting exit code.
Return type:: int

name: ClassVar[str] = ''¶

The name of the command.

Type:: str

needs_api: ClassVar[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.

Added in version 3.0.

Type:: bool

needs_diffs: ClassVar[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.

Added in version 4.0.

Type:: bool

needs_repository: ClassVar[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.

Added in version 3.0.

Type:: bool

needs_scm_client: ClassVar[bool] = False¶

Whether the command needs the SCM client.

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

Added in version 3.0.

Type:: bool

option_list: ClassVar[list[Option | OptionGroup]] = []¶

Command-line options for this command.

Type:: list of Option or OptionGroup

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

otp_token_prompt(uri: str, token_method: str, *args, **kwargs) → str[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.

Parameters:

uri (str) – The URI of the endpoint requiring authentication.
token_method (str) – The token method requested.
*args (tuple, unused) – Unused positional arguments.
**kwargs (dict, unused) – Unused keyword arguments.

Returns:

The user-provided token.

Return type:

str

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

post_process_options() → None[source]¶

Post-process options for the command.

This can validate and update options before the command is invoked.

Raises:: rbtools.commands.base.errors.CommandError – There was an error found with an option.

repository: RepositoryItemResource | None¶

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: RepositoryInfo | None¶

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.

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

run_from_argv(argv: list[str]) → None[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.

Parameters:: argv (list of str) – A list of command line arguments

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

server_url: str | None¶

The URL to the Review Board server.

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

stderr: OutputWrapper[str]¶

The stream for writing error output as Unicode strings.

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

stderr_bytes: OutputWrapper[bytes]¶

The stream for writing error output as byte strings.

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

stderr_is_atty: bool¶

Whether the stderr stream is from an interactive session.

This applies to stderr.

Added in version 3.1.

stdin: TextIO¶

The stream for reading standard input.

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

Added in version 3.1.

stdin_is_atty: bool¶

Whether the stdin stream is from an interactive session.

This applies to stdin.

Added in version 3.1.

stdout: OutputWrapper[str]¶

The stream for writing standard output as Unicode strings.

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

stdout_bytes: OutputWrapper[bytes]¶

The stream for writing standard output as byte strings.

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

stdout_is_atty: bool¶

Whether the stdout stream is from an interactive session.

This applies to stdout.

Added in version 3.1.

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

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

tool: BaseSCMClient | None¶

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.

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

usage() → str[source]¶

Return a usage string for the command.

Returns:: Usage text for the command.
Return type:: str

web_login_callback() → bool[source]¶

Attempt to authorize using web-based login.

This is used as a callback in the API when the user requires authorization.

Added in version 6.0.

Raises:: rbtools.utils.web_login.WebLoginNotAllowed – Web-based login is not available on the Review Board server.

class rbtools.commands.base.commands.BaseMultiCommand(transport_cls: type[Transport] = <class 'rbtools.api.transport.sync.SyncTransport'>, stdout: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, stderr: TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: TextIO = <_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.

Added in version 3.0.

__firstlineno__ = 1835¶

__static_attributes__ = ('subcommand', 'subcommand_parsers')¶

common_subcommand_option_list: list[Option | OptionGroup] = []¶

Options common to all subcommands.

Type:: list

create_parser(config: RBToolsConfig, argv: list[str] | None = None, *, color: bool = True) → argparse.ArgumentParser[source]¶

Create and return the argument parser for this command.

Changed in version 6.0: Added the color argument.

Parameters:

config (dict) – The loaded RBTools config.
argv (list, optional) – The argument list.
color (bool, optional) –
Whether to output color, if supported in the environment.

This will output color on Python 3.14 and higher by default.

Added in version 6.0.

Returns:

The argument parser.

Return type:

argparse.ArgumentParser

get_options_flat() → Sequence[Option][source]¶

Return a list of all options for the command.

This returns a flat list of options, pulling out the options that are inside any option groups set on the command, and in any subcommands.

Added in version 6.0.

Returns:: The list of options for the command.
Return type:: list of rbtools.commands.base.options.Option

initialize() → None[source]¶: Initialize the command.

main(*args) → int[source]¶

Run the command.

Parameters:: *args (tuple) – Positional arguments passed to the command.
Returns:: The resulting exit code.
Return type:: int

subcommand: BaseSubCommand¶: The currently-running subcommand.

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

subcommands: list[type[BaseSubCommand]] = []¶

The available subcommands.

This is a list of BaseSubCommand subclasses.

Type:: list

usage(command_cls: type[BaseSubCommand] | None = None) → str[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:: str

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

Bases: BaseCommand

Abstract base class for a subcommand.

__firstlineno__ = 1799¶

__init__(options: Namespace, config: RBToolsConfig, *args, **kwargs) → None[source]¶

Initialize the subcommand.

Parameters:

options (argparse.Namespace) – The parsed options.
config (rbtools.config.RBToolsConfigg) – The loaded RBTools configuration.
*args (list) – Positional arguments to pass to the Command class.
**kwargs (dict) – Keyword arguments to pass to the Command class.

__static_attributes__ = ('config', 'options')¶

help_text: str = ''¶

The subcommand’s help text.

Type:: str

class rbtools.commands.base.commands.LogLevelFilter(level: int)[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.

__annotations_cache__ = {}¶

__firstlineno__ = 63¶

__init__(level: int) → None[source]¶

Initialize the filter.

Parameters:: level (int) – The log level to filter for.

__static_attributes__ = ('level',)¶

filter(record: LogRecord) → bool[source]¶

Filter a log record.

Parameters:: record (logging.LogRecord) – The record to filter.
Returns:: True if the record’s log level matches the filter.
Return type:: bool

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

Bases: HelpFormatter

Smartly formats help text, preserving paragraphs.

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

__annotations_cache__ = {}¶

__firstlineno__ = 100¶

__static_attributes__ = ()¶