rbtools.diffs.tools.base.diff_tool¶
Base class for building diff tools.
New in version 4.0.
Classes
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.
- 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:
- available: Optional[bool]¶
Whether the diff tool is available for use.
This is set after calling
setup()
. IfNone
, this hasn’t been set yet.- Type:
- 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:
- 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:
- 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
andversion_info
.- Returns:
True
if the tool is available.False
if it’s not.- Return type:
- 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
ormodified_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:
- 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
ormodified_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:
- Raises:
rbtools.utils.process.RunProcessError – There was an error invoking the diff tool. Details are in the exception.