rbtools.diffs.tools.base.diff_file_result¶

Classes for working with the result of a diff between files.

Classes

class rbtools.diffs.tools.base.diff_file_result.DiffFileHeaderDict(_typename, _fields=None, /, **kwargs)[source]¶

Bases: dict

Parsed information from a diff file header.

This represents information found in a ---` or +++ header in a Unified Diff file.

New in version 4.0.

marker: bytes¶

The marker at the start of the header line.

This will be --- or +++.

Type:

bytes

path: bytes¶

The path listed in the header line.

Type:

bytes

extra: bytes¶

Extra information shown after the filename.

This will be empty if not present.

Type:

bytes

static __new__(cls, _typename, _fields=None, /, **kwargs)¶

__optional_keys__ = frozenset({})¶

__required_keys__ = frozenset({'extra', 'marker', 'path'})¶

__total__ = True¶

class rbtools.diffs.tools.base.diff_file_result.DiffFileResult(*, orig_path: str, modified_path: str, diff: BytesIO, is_binary: bool = False, has_text_differences: bool = True, orig_file_header_line_num: int = 0, modified_file_header_line_num: int = 1, hunks_start_line_num: int = 2, file_header_re: Pattern = re.compile(b'^(?P<marker>---|\\+\\+\\+) (?P<path>.+?)((?:\\t| {2,})(?P<extra>.*))?$'))[source]¶

Bases: object

The result of diffing a file.

This contains the stream of diff contents, flags indicating what type of diff this is, and whether any changes were found.

There’s parsing helpers in here to extract the most relevant information from the diff, for use when assembling new SCM-specific diffs from the contents.

New in version 4.0.

__init__(*, orig_path: str, modified_path: str, diff: BytesIO, is_binary: bool = False, has_text_differences: bool = True, orig_file_header_line_num: int = 0, modified_file_header_line_num: int = 1, hunks_start_line_num: int = 2, file_header_re: Pattern = re.compile(b'^(?P<marker>---|\\+\\+\\+) (?P<path>.+?)((?:\\t| {2,})(?P<extra>.*))?$')) → None[source]¶

Initialize the diff result.

Parameters:

• orig_path (str) –

  The original filename passed to the diff tool.

  This may be different from the information shown in the diff itself.

• modified_path (str) –

  The modified filename passed to the diff tool.

  This may be different from the information shown in the diff itself.

• diff (io.BytesIO) – A stream containing the full diff content.

• is_binary (bool, optional) – Whether this represents a change to a binary file.

• has_text_differences (bool, optional) – Whether differences were found in a text file.

• orig_file_header_line_num (int, optional) –

  The line number containing the original line header.

  This is a hint for parsing. It shouldn’t need to be changed, but can be set by a diff tool if required.

• modified_file_header_line_num (int, optional) –

  The line number containing the modified line header.

  This is a hint for parsing. It shouldn’t need to be changed, but can be set by a diff tool if required.

• hunks_start_line_num (int, optional) –

  The starting line number containing the Unified Diff hunks.

  This is a hint for parsing. It shouldn’t need to be changed, but can be set by a diff tool if required.

• file_header_re (re.Pattern, optional) –

  A regex used to parse file headers.

  This must capture marker, path, and extra groups for a standard Unified Diff original/modified file header line.

orig_path: str¶

The original path passed to the diff tool.

This may be different from the information shown in orig_file_header.

Type:

str

modified_path: str¶

The modified path passed to the diff tool.

This may be different from the information shown in modified_file_header.

Type:

str

diff: BytesIO¶

A stream containing the full diff content.

Consumers can read directly from this, but it’s recommended that they use one of the many available properties or functions for fetching content instead.

Type:

io.BytesIO

is_binary: bool¶

Whether this represents a change to a binary file.

Type:

bool

has_text_differences: bool¶

Whether differences were found in a text file.

This will be True if there were any changes at all to the file.

This will be False if the files were identical, or if one or both files were binary.

Type:

bool

orig_file_header_line_num: int¶

The line number containing the original line header.

Type:

int

modified_file_header_line_num: int¶

The line number containing the modified line header.

Type:

int

hunks_start_line_num: int¶

The starting line number containing the Unified Diff hunks.

Type:

int

has_differences: bool¶

Whether any differences were found.

If diffing against a binary file, this will always be True. Otherwise, it depends on the value of has_text_differences.

Type:

bool

property orig_file_header: bytes[source]¶

The content of the original file header.

The format of this header may vary between diff tools.

Type:

bytes

property parsed_orig_file_header: Optional[DiffFileHeaderDict][source]¶

The extra contents on the file header.

This is usually a timestamp, but its presence and format may vary between diff tools.

See DiffFileHeaderDict for the contents of the dictionary.

Type:

dict

property modified_file_header: bytes[source]¶

The content of the modified file header.

The format of this header may vary between diff tools.

Type:

bytes

property parsed_modified_file_header: Optional[DiffFileHeaderDict][source]¶

The extra contents on the file header.

This is usually a timestamp, but its presence and format may vary between diff tools.

See DiffFileHeaderDict for the contents of the dictionary.

Type:

dict

property hunks: bytes[source]¶

The full content of the diff hunks.

This does not normalize line endings.

Type:

bytes

iter_hunk_lines(keep_newlines=False) → Iterator[bytes][source]¶

Iterate through all hunk lines.

Lines may optionally contain newlines.

Note that any CRCRLF newlines will be converted to CRLF. While uncommon, CRCRLF can happen with some SCMs if editing and diffing code across two different operating systems (usually Windows and either Linux or macOS).

Parameters:

keep_newlines (bool) – Whether to keep newlines in yielded lines.

Yields:

bytes – Each line of bytes in the hunk data.

seek_diff_hunks() → None[source]¶

Seek to the position of the diff hunks.

This can be used by consumers to place the read offset at the correct position in order to perform operations on the hunk portion of the diff.

If there are no text differences, this seeks to the beginning of the diff.