rbtools.diffs.writers¶

Writers to help programmatically generate new diffs.

Classes

class rbtools.diffs.writers.UnifiedDiffWriter(stream: BufferedIOBase, encoding: str = 'utf-8', newline: bytes = b'\n')[source]¶

Bases: object

Writer for generating Unified Diff files.

This can be used to incrementally build up one or more Unified Diff files from any provided input or from results from a diff tool.

It takes care of ensuring proper newlines at the end of the file.

This is the preferred interface for programmatically generating Unified Diff payloads, whether for DiffX or otherwise, starting in RBTools 4.0.

New in version 4.0.

__init__(stream: BufferedIOBase, encoding: str = 'utf-8', newline: bytes = b'\n') → None[source]¶

Initialize the writer.

Parameters:

• stream (io.BufferedIOBase) – The stream to write to.

• encoding (str, optional) –

  The encoding to use to encode Unicode strings.

  This defaults to encoding as UTF-8. It should generally not be changed.

• newline (bytes, optional) –

  The newline character(s) to use at the end of each line.

  This defaults to UNIX newlines.

encoding: str¶

The encoding to use to encode Unicode strings.

Type:

str

newline: bytes¶

The newline character(s) to use at the end of each line.

Type:

bytes

write_orig_file_header(path: Union[bytes, str], extra: Optional[Union[bytes, str]] = None) → None[source]¶

Write a header for the original file.

This will write the --- file header in a standard form, optionally containing extra data after the filename.

String arguments will be encoded using the default encoding for the writer. Byte string arguments are expected to already be in the proper encoding.

Parameters:

• path (bytes or str) – The path to include in the header.

• extra (bytes or str, optional) – Optional extra detail to include after the filename.

write_modified_file_header(path: Union[bytes, str], extra: Optional[Union[bytes, str]] = None) → None[source]¶

Write a header for the modified file.

This will write the +++ file header in a standard form, optionally containing extra data after the filename.

String arguments will be encoded using the default encoding for the writer. Byte string arguments are expected to already be in the proper encoding.

Parameters:

• path (bytes or str) – The path to include in the header.

• extra (bytes or str, optional) – Optional extra detail to include after the filename.

write_file_headers(*, orig_path: Union[bytes, str], modified_path: Union[bytes, str], orig_extra: Optional[Union[bytes, str]] = None, modified_extra: Optional[Union[bytes, str]] = None) → None[source]¶

Write both original and modified file headers.

This will write headers for the original and modified files, basing them on provided data.

String arguments will be encoded using the default encoding for the writer. Byte string arguments, or byte strings from the diff result, are expected to already be in the proper encoding.

Parameters:

• orig_path (bytes or str) – The file path to use for the original file header.

• modified_path (bytes or str) – The file path to use for the modified file header.

• orig_extra (bytes or str, optional) – Extra details for the original file header.

• modified_extra (bytes or str, optional) – Extra details for the modified file header.

write_index(contents: Union[bytes, str]) → None[source]¶

Write a standard Index line.

This is used by some Unified Diff variants to separate sections for different files, regardless of contents.

This is in the form of Index content, followed by a line with 67 = characters.

Parameters:

contents (bytes or str) – The contents to write after Index:.

write_hunks(hunks: Union[bytes, Iterable[bytes]]) → None[source]¶

Write hunks.

This takes either a byte string of hunks to write, or an iterator yielding lines of hunks.

If taking a byte string, the bytes are expected to have the proper encoding and newlines for the diff.

If taking an iterator, the iterator is expected to yield byte strings in the proper encoding without any newlines.

Parameters:

hunks (bytes or iterable) – The hunks to write.

write_binary_files_differ(*, orig_path: Union[bytes, str], modified_path: Union[bytes, str]) → None[source]¶

Write a marker indicating that binary files differ.

This provides the standard text used when diffing binary files without showing an actual difference between those files.

Parameters:

• orig_path (bytes or str) – The original file path.

• modified_path (bytes or str) – The modified file path.

write_diff_file_result_headers(diff_file_result: DiffFileResult, *, orig_path: Optional[Union[bytes, str]] = None, modified_path: Optional[Union[bytes, str]] = None, orig_extra: Optional[Union[bytes, str]] = None, modified_extra: Optional[Union[bytes, str]] = None) → None[source]¶

Write file headers based on the result from a diff tool.

This will write headers for the original and modified files, basing them on provided data or that found in the result of a diff operation.

Provided arguments take precedence.

String arguments will be encoded using the default encoding for the writer. Byte string arguments, or byte strings from the diff result, are expected to already be in the proper encoding.

Parameters:

• diff_file_result (rbtools.diffs.tools.base.diff_file_result.DiffFileResult) – The result of a diff operation, used to provide defaults for the headers.

• orig_path (bytes or str, optional) – An explicit file path to use for the original file header.

• modified_path (bytes or str, optional) – An explicit file path to use for the modified file header.

• orig_extra (bytes or str, optional) – Explicit extra details for the original file header.

• modified_extra (bytes or str, optional) – Explicit extra details for the modified file header.

write_diff_file_result_hunks(diff_file_result: DiffFileResult) → None[source]¶

Write hunks from the result of a diff tool.

This is the most optimal way of writing hunks based on a diff result from a diff tool. Each line will be written with any original newlines stripped and the writer’s configured newlines appended.

Parameters:

diff_file_result (rbtools.diffs.tools.base.diff_file_result.DiffFileResult) – The result of a diff operation, used to provide hunks.

write_line(line: Union[bytes, str]) → None[source]¶

Write a line to the diff.

This must not have a newline appended. The writer’s configured newline will be used instead.

String arguments will be encoded using the default encoding for the writer. Byte string arguments are expected to already be in the proper encoding.

Parameters:

line (bytes or str) – The line to write, without a trailing newline.