rbtools.commands.base.commands¶

Base classes for commands.

Classes

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.

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

Initialize the filter.

Parameters:

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

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)[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: 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.

name: ClassVar[str] = ''¶

The name of the command.

Type:

str

author: ClassVar[str] = ''¶

The author of the command.

Type:

str

description: ClassVar[str] = ''¶

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

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.

New 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.

New in version 4.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.

New in version 3.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.

New in version 3.0.

Type:

bool

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

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

  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: Optional[RBToolsConfig]¶

The loaded configuration for RBTools.

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

stdout: OutputWrapper[str]¶

The stream for writing standard output as Unicode strings.

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

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().

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_bytes: OutputWrapper[bytes]¶

The stream for writing standard output as byte strings.

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

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().

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.

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: RBToolsConfig, argv: Optional[list[str]] = None) → argparse.ArgumentParser[source]¶

Return a new argument parser for this command.

Parameters:

• config (dict) – The loaded RBTools configuration.

• argv (list of str) – The list of command line arguments.

Returns:

The new argument parser for the command.

Return type:

argparse.ArgumentParser

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.

usage() → str[source]¶

Return a usage string for the command.

Returns:

Usage text for the command.

Return type:

str

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).

create_arg_parser(argv: list[str]) → argparse.ArgumentParser[source]¶

Create and return the argument parser.

Parameters:

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

Returns:

Argument parser for commandline arguments

Return type:

argparse.ArgumentParser

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

initialize_scm_tool(client_name: Optional[str] = None, *, tool_required: bool = True) → tuple[Optional[RepositoryInfo], Optional[BaseSCMClient]][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.

  New 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

credentials_prompt(realm: str, uri: str, username: Optional[str] = None, password: Optional[str] = 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.

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

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 instantianting their own client.

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

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

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

Bases: BaseCommand

Abstract base class for a subcommand.

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.

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.

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.

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.

New in version 3.1.

stdin: TextIO¶

The stream for reading standard input.

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

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.

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.

New in version 3.1.

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.

transport_cls: type[Transport]¶

The transport class used for talking to the API.

help_text: str = ''¶

The subcommand’s help text.

Type:

str

__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.

options: argparse.Namespace¶

Options parsed for the command.

config: Optional[RBToolsConfig]¶

The loaded configuration for RBTools.

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

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.

New in version 3.0.

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.

config: Optional[RBToolsConfig]¶

The loaded configuration for RBTools.

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

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.

options: argparse.Namespace¶

Options parsed for the command.

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.

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.

New in version 3.1.

stdin: TextIO¶

The stream for reading standard input.

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

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.

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.

New in version 3.1.

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.

transport_cls: type[Transport]¶

The transport class used for talking to the API.

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: Optional[type[rbtools.commands.base.commands.BaseSubCommand]] = 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

create_parser(config: RBToolsConfig, argv: Optional[list[str]] = None) → argparse.ArgumentParser[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() → 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