rbtools.diffs.tools.base.diff_tool¶

Base class for building diff tools.

New in version 4.0.

Classes

BaseDiffTool()

Base class for diff tools.

class rbtools.diffs.tools.base.diff_tool.BaseDiffTool[source]¶

Bases: object

Base class for diff tools.

This provides a standard interface for working with arbitrary diff tools.

New in version 4.0.

diff_tool_id: str = ''¶

The unique ID of this diff tool.

Type:: str

name: str = ''¶

The publicly-displayable name of this diff tool.

Type:: str

classmethod get_install_instructions() → str[source]¶

Return instructions for installing this tool.

This can be provided by subclasses to help users install any missing dependencies.

Returns:: The installation instructions, or an empty string (default) to avoid showing instructions.
Return type:: str

__init__() → None[source]¶: Initialize the tool.

available: Optional[bool]¶

Whether the diff tool is available for use.

This is set after calling setup(). If None, this hasn’t been set yet.

Type:: bool

exe_path: Optional[str]¶

The path to the executable used to run this tool.

If the diff tool is backed by an executable, this will be set after calling setup().

Type:: str

version_info: Optional[str]¶

The diff tool version information found when checking availability.

If the diff tool provides this information, then this will be set after calling setup().

Type:: str

setup() → None[source]¶

Set up the diff tool.

This will check for the tool’s availability, allowing it to be used.

This must be called before calling run_diff_file().

check_available() → bool[source]¶

Check whether the tool is available for use.

This must be implemented by subclasses. If appropriate, they should set exe_path and version_info.

Returns:: True if the tool is available. False if it’s not.
Return type:: bool

make_run_diff_file_cmdline(*, orig_path: str, modified_path: str, show_hunk_context: bool = False, treat_missing_as_empty: bool = True) → List[str][source]¶

Return the command line for running the diff tool.

This should generally be used by run_diff_file(), and can be useful to unit tests that need to check for the process being run.

Parameters:

orig_path (str) – The path to the original file.
modified_path (str) – The path to the modified file.
show_hunk_context (bool, optional) – Whether to show context on hunk lines, if supported by the diff tool.
treat_missing_as_empty (bool, optional) –
Whether to treat a missing orig_path or modified_path as an empty file, instead of failing to diff.

This must be supported by subclasses.

Returns:

The command line to run for the given flags.

Return type:

list of str

run_diff_file(*, orig_path: str, modified_path: str, show_hunk_context: bool = False, treat_missing_as_empty: bool = True) → DiffFileResult[source]¶

Return the result of a diff between two files.

Subclasses are responsible for generating a Unified Diff, and ensuring that the contents are in line with what’s expected for typical GNU Diff contents.

That is, text content must be in the following format:

--- <orig_filename>\t<extra info>
+++ <modified_filename>\t<extra info>
<unified diff hunks>

Binary file content must be in the following format:

Binary files <orig_filename> and <modified_filenames> differ

Parameters:

orig_path (str) – The path to the original file.
modified_path (str) – The path to the modified file.
show_hunk_context (bool, optional) – Whether to show context on hunk lines, if supported by the diff tool.
treat_missing_as_empty (bool, optional) –
Whether to treat a missing orig_path or modified_path as an empty file, instead of failing to diff.

This must be supported by subclasses.

Returns:

The result of the diff operation.

Return type:

rbtools.diffs.tools.base.diff_file_result.DiffFileResult

Raises:

rbtools.utils.process.RunProcessError – There was an error invoking the diff tool. Details are in the exception.