reviewbot.tools.base¶

Base support for code checking tools.

This module provides convenient imports for specific base classes:

• BaseTool

class BaseTool(settings=None, **kwargs)¶

Bases: object

The base class all Review Bot tools should inherit from.

This class provides base functionality specific to tools which process each file separately.

Most tools will override handle_file(), performing a code review on the provided file.

If a tool would like to perform a different style of analysis, it can override handle_files().

settings¶

Settings configured for this tool in Review Board, based on options.

Type:

dict

name = ''¶

The displayed name of the tool.

Type:

str

description = ''¶

A short description of the tool.

Type:

str

version = '1'¶

The compatibility version of the tool.

This should only be changed for major breaking updates. It will break compatibility with existing integration configurations, requiring manual updates to those configurations. Any existing configurations referencing the old version will not be run, unless an older version of the tool is being handled through another Review Bot worker providing the older tool.

Type:

str

exe_dependencies = []¶

A list of executable tools required by the tool.

Each is the name of an executable on the filesystem, either in the PATH or defined in the exe_paths configuration.

These will be checked when the worker starts. If a dependency for a tool is missing, the worker will not enable it.

New in version 3.0: Tools that previously implemented check_dependencies() may want to be updated to use this.

Type:

dict

file_patterns = []¶

A list of filename patterns this tool can process.

This is intended for tools that have a fixed list of file extensions or specific filenames they should process. Each entry is a glob file pattern (e.g., *.py, .config/*.xml, dockerfile, etc.), and must be lowercase (as filenames will be normalized to lowercase for comparison). See fnmatch for pattern rules.

Tools can leave this empty to process all files, or can override get_can_handle_file() to implement custom logic (e.g., basing matching off a tool’s settings, or providing case-sensitive matches).

New in version 3.0.

Type:

list of str

options = []¶

Configurable options defined for the tool.

Each item in the list is a dictionary representing a form field to display in the Review Board administration UI. Keys include:

field_type (str):

The full path as a string to a Django form field class to render.

name (str):

The name/ID of the field. This will map to the key in the settings provided to handle_files() and handle_file().

default (object, optional):

The default value for the field.

field_options (dict, optional):

Additional options to pass to the form field’s constructor.

widget (dict, optional):

Information on the Django form field widget class used to render the field. This dictionary includes the following keys:

type (str):

The full path as a string to a Django form field widget class.

attrs (dict, optional):

A dictionary of attributes passed to the widget’s constructor.

Type:

list

working_directory_required = False¶

Whether this tool requires a full checkout and working directory to run.

Type:

bool

timeout = None¶

Timeout for tool execution, in seconds.

Type:

int

__init__(settings=None, **kwargs)¶

Initialize the tool.

Changed in version 3.0: Added settings and **kwargs arguments. Subclasses must provide this by Review Bot 4.0.

Parameters:

• settings (dict, optional) – Settings provided to the tool.

• **kwargs (dict) – Additional keyword arguments, for future expansion.

property logger¶

The logger for the tool.

This logger will contain information on the process, the task (if it’s running in a task), and the tool name.

New in version 3.0.

Type:

logging.Logger

check_dependencies(**kwargs)¶

Verify the tool’s dependencies are installed.

By default, this will check exe_dependencies, ensuring each is available to the tool.

For each entry in exe_dependencies, PATH will be checked. If the dependency name is found in the exe_paths mapping in the Review Bot configuration, that path will be checked.

Subclasses can implement this if they need more advanced checks.

Parameters:

**kwargs (dict, unused) – Additional keyword arguments. This is intended for future expansion.

Returns:

True if all dependencies for the tool are satisfied. If this returns False, the worker will not listen for this Tool’s queue, and a warning will be logged.

Return type:

bool

get_can_handle_file(review_file, **kwargs)¶

Return whether this tool can handle a given file.

By default, this checks the full path of the destination file against the patterns in file_patterns. If the file path matches, or that list is empty, this will allow the file to be handled.

Subclasses can override this to provide custom matching logic.

New in version 3.0.

Parameters:

• review_file (reviewbot.processing.review.File) – The file to check.

• **kwargs (dict, unused) – Additional keyword arguments passed to execute(). This is intended for future expansion.

Returns:

True if the file can be handled. False if it cannot.

Return type:

bool

execute(review, repository=None, base_commit_id=None, **kwargs)¶

Perform a review using the tool.

Changed in version 3.0: settings is deprecated in favor of the settings attribute on the instance. It’s still provided in 3.0.

**kwargs is now expected.

Parameters:

• review (reviewbot.processing.review.Review) – The review object.

• repository (reviewbot.repositories.Repository, optional) – The repository.

• base_commit_id (str, optional) – The ID of the commit that the patch should be applied to.

• **kwargs (dict, unused) – Additional keyword arguments, for future expansion.

build_base_command(**kwargs)¶

Build the base command line used to review files.

This will be passed to handle_file() for each file. It’s useful for constructing a common command line and arguments that will apply to each file in a diff.

New in version 3.0.

Parameters:

**kwargs (dict, unused) – Additional keyword arguments, for future expansion.

Returns:

The base command line.

Return type:

list of str

handle_files(files, **kwargs)¶

Perform a review of all files.

This may be overridden by subclasses for tools that process all files at once.

Changed in version 3.0: settings is deprecated in favor of the settings attribute on the instance. It’s still provided in 3.0.

**kwargs is now expected.

These will be enforced in Review Bot 4.0.

Parameters:

• files (list of reviewbot.processing.review.File) – The files to process.

• **kwargs (dict) – Additional keyword arguments passed to execute(). This is intended for future expansion.

handle_file(f, path=None, base_command=None, **kwargs)¶

Perform a review of a single file.

This method may be overridden by subclasses to process an individual file.

Changed in version 3.0: settings is deprecated in favor of the settings attribute on the instance. It’s still provided in 3.0.

path is added, which is the result of a get_patched_file_path() command, and must be valid for this method to be called.

base_command is added, which would be the result of build_base_command().

**kwargs is now expected.

These will be enforced in Review Bot 4.0.

Parameters:

• f (reviewbot.processing.review.File) – The file to process.

• path (str, optional) –

  The local path to the patched file to review.

  This won’t be passed for legacy tools.

• base_command (list of str, optional) – The common base command line used for reviewing a file, if returned from build_base_command().

• **kwargs (dict) – Additional keyword arguments passed to handle_files(). This is intended for future expansion.

class FilePatternsFromSettingMixin(**kwargs)¶

Bases: object

Mixin to set file patterns based on a configured tool setting.

Subclasses can base file patterns off either a setting representing a comma-separated list of file patterns, or a setting representing a comma-separated list of file extensions. If both are provided, both will be checked, with the file patterns taking precedence over file extensions.

If neither are provided by the user, the default list of file patterns set by the subclass (if any) will be used.

New in version 3.0.

file_extensions_setting = None¶

The name of a tool setting for a comma-separated list of extensions.

Type:

str

file_patterns_setting = None¶

The name of a tool setting for a comma-separated list of patterns.

Type:

str

include_default_file_patterns = True¶

Whether to include default file patterns in the resulting list.

Type:

boolean

__init__(**kwargs)¶

Initialize the tool.

Parameters:

**kwargs (dict) – Keyword arguments for the tool.

class FullRepositoryToolMixin¶

Bases: object

Mixin for tools that need access to the entire repository.

This will take care of checking out a copy of the repository and applying patches from the diff being reviewed.

New in version 3.0: This replaced the legacy reviewbot.tools.RepositoryTool.

working_directory_required = True¶

execute(review, repository=None, base_commit_id=None, **kwargs)¶

Perform a review using the tool.

Parameters:

• review (reviewbot.processing.review.Review) – The review object.

• settings (dict, optional) – Tool-specific settings.

• repository (reviewbot.repositories.Repository, optional) – The repository.

• base_commit_id (str, optional) – The ID of the commit that the patch should be applied to.

class JavaToolMixin¶

Bases: object

Mixin for Java-based tools.

New in version 3.0.

java_main = None¶

Main class to call to run the Java application.

Type:

str

java_classpaths_key = None¶

The key identifying the classpaths to use.

Type:

str

exe_dependencies = ['java']¶

classmethod set_has_java_runtime(has_runtime)¶

Set whether there’s a Java runtime installed.

Parameters:

has_runtime (bool) – Whether there’s a runtime installed.

classmethod clear_has_java_runtime()¶

Clear whether there’s a Java runtime installed.

This will force the next dependency check to re-check for a runtime.

check_dependencies()¶

Verify the tool’s dependencies are installed.

This will invoke the base class’s dependency checking, ensuring that java is available, and will then attempt to run the configured Java class (java_main), checking that it could be found.

Returns:

True if all dependencies for the tool are satisfied. If this returns False, the worker will not listen for this Tool’s queue, and a warning will be logged.

Return type:

bool

build_base_command(**kwargs)¶

Build the base command line used to review files.

Parameters:

**kwargs (dict, unused) – Additional keyword arguments.

Returns:

The base command line.

Return type:

list of str