rbtools.diffs.patches¶

Patch information and support for applying patches.

Added in version 5.1: PatchAuthor and PatchResult were moved from rbtools.scmclients.base.patch.

Module Attributes

BinaryFileStatus

Type for the status of a binary file change.

Classes

`BinaryFilePatch`(*, old_path, new_path, ...)	Represents a binary file in a patch with lazy content loading.
`Patch`(*[, author, base_dir, content, ...])	A patch to a repository that can be applied.
`PatchAuthor`(*, full_name, email)	The author of a patch or commit.
`PatchResult`(*, applied[, has_conflicts, ...])	The result of a patch operation.

class rbtools.diffs.patches.BinaryFilePatch(*, old_path: str | None, new_path: str | None, status: BinaryFileStatus, file_attachment: FileAttachmentItemResource | None)[source]¶

Bases: object

Represents a binary file in a patch with lazy content loading.

Added in version 6.0.

__firstlineno__ = 47¶

__init__(*, old_path: str | None, new_path: str | None, status: BinaryFileStatus, file_attachment: FileAttachmentItemResource | None) → None[source]¶

Initialize the binary file.

Parameters:

old_path (str) – Original file path relative to the repository root.
new_path (str) – Modified file path relative to the repository root.
status (str) – File operation (‘added’, ‘deleted’, ‘modified’, or ‘moved’).
file_attachment (rbtools.api.resource.FileAttachmentItemResource) – Source for downloading content.

__repr__() → str[source]¶

Return a string representation of the object.

Returns:: The string representation.
Return type:: str

__static_attributes__ = ('_attachment', '_content', '_content_loaded', 'download_error', 'new_path', 'old_path', 'status')¶

property content: bytes | None[source]¶: Lazy-loaded binary content.

download_error: str | None¶: Download error if any.

new_path: str | None¶: Modified file path relative to the repository root.

old_path: str | None¶: Original file path relative to the repository root.

property path: str[source]¶: The path of the file, for display purposes.

status: BinaryFileStatus¶: File operation.

rbtools.diffs.patches.BinaryFileStatus¶

Type for the status of a binary file change.

Added in version 6.0.

alias of Literal[‘added’, ‘deleted’, ‘modified’, ‘moved’]

Bases: object

A patch to a repository that can be applied.

This consolidates metadata on the patch (the author and description) along with information needed to apply a patch (the base directory within the repository in which to apply the patch, the patch level, and the patch contents).

Added in version 5.1.

__firstlineno__ = 283¶

Initialize the patch.

Parameters:

author (PatchAuthor, optional) – The author of the patch.
base_dir (str, optional) –
The directory in the repository where the patch was generated.

This is dependent on the SCM and the method used to generate the patch.
content (bytes, optional) –
The contents of the patch.

Either this or path must be provided.
message (str, optional) – The commit message describing the patch.
path (pathlib.Path, optional) –
The file path where the patch resides.

Either this or content must be provided.
prefix_level (int, optional) –
The path prefix stripping level to use when applying the patch.

This is the number of path components to strip from the beginning of each filename in the patch. It’s the equivalent of patch -p<X>.

If not provided, the patching code will determine a default. This default may not be correct for the patch.
binary_files (list of BinaryFilePatch, optional) –
List of binary files associated with this patch.

Added in version 6.0.

Raises:

ValueError – One or more parameters or parameter combinations were invalid.

__repr__() → str[source]¶

Return a string representation of the object.

Returns:: The string representation.
Return type:: str

__static_attributes__ = ('_content', '_opened', '_path', 'author', 'base_dir', 'binary_files', 'message', 'prefix_level')¶

author: PatchAuthor | None¶

The author of the patch.

This will generally be available if generating a patch from an existing commit.

base_dir: str | None¶

The base directory in the repository where the patch was generated.

This is dependent on the SCM and the method used to generate the patch.

binary_files: Sequence[BinaryFilePatch]¶: List of binary files in this patch.

Added in version 6.0.

property content: bytes[source]¶

The raw content of the patch.

The patch must be opened before this is called.

Returns:: The raw patch contents.
Return type:: bytes
Raises:: IOError – The patch was not opened for reading or could not be read from disk.

message: str | None¶

The commit message describing the patch.

This will generally be available if generating a patch from an existing commit.

open() → Iterator[None][source]¶

Open the patch for reading.

Once upon, either the content or the file path can be directly read. Any temporary state will be cleaned up once the patch is no longer open.

This must be called before accessing :py:attr;`content` or path.

Context:: The patch will be available for reading.

property path: Path[source]¶

A path to the patch content.

The returned path may be a temporary file path, which would be automatically deleted once the patch is closed for reading.

The patch must be opened before this is called.

Returns:: The raw patch contents.
Return type:: bytes
Raises:: IOError – The patch was not opened for reading or a temporary file could not be written to disk.

prefix_level: int | None¶

The path prefix stripping level to use when applying the patch.

This is the number of path components to strip from the beginning of each filename in the patch. It’s the equivalent of patch -p<X>.

class rbtools.diffs.patches.PatchAuthor(*, full_name: str, email: str)[source]¶

Bases: object

The author of a patch or commit.

This wraps the full name and e-mail address of a commit or patch’s author primarily for use in BaseSCMClient.apply_patch().

Changed in version 5.1:

Moved from rbtools.clients.base.patch. That module will provide compatibility imports until RBTools 7.

Changed in version 4.0:

Moved from rbtools.clients. That module still provides compatibility imports until RBTools 7.

__eq__(other: object) → bool[source]¶

Return whether this author is equal to another.

Parameters:: other (object) – The other object to compare to.
Returns:: True if the other object is equal to this one. False if it is not.
Return type:: bool

__firstlineno__ = 165¶

__hash__() → int[source]¶

Return a hash of the object.

Returns:: A hash for the object.
Return type:: int

__init__(*, full_name: str, email: str) → None[source]¶

Initialize the author information.

Changed in version 5.1: This now requires keyword-only arguments. Support for positional arguments will be removed in RBTools 7.

Parameters:

full_name (str) – The full name of the author.
email (str) – The e-mail address of the author.

__repr__() → str[source]¶

Return a string representation of this object.

Added in version 5.1.

Returns:: The string representation.
Return type:: str

__static_attributes__ = ('email', 'full_name')¶

email: str¶: The e-mail address of the author.

full_name: str¶: The full name of the author.

Added in version 5.1: This was added as a replacement for fullname.

property fullname: str[source]¶

The full name of this author.

Deprecated since version 5.1: This is deprecated in favor of full_name. It will be removed in RBTools 7.

Returns:: The full name of the author.
Return type:: bool

class rbtools.diffs.patches.PatchResult(*, applied: bool, has_conflicts: bool = False, conflicting_files: list[str] | None = None, patch_output: bytes | None = None, patch: Patch | None = None, patch_range: tuple[int, int] | None = None, binary_applied: Sequence[str] | None = None, binary_failed: Mapping[str, str] | None = None)[source]¶

Bases: object

The result of a patch operation.

This stores state on whether the patch could be applied (fully or partially), whether there are conflicts that can be resolved (as in conflict markers, not reject files), which files conflicted, and the patch output.

Changed in version 5.1:

Moved from rbtools.clients.base.patch. That module will provide compatibility imports until RBTools 7.

Changed in version 4.0:

Moved from rbtools.clients. That module will provide compatibility imports until RBTools 7.

__firstlineno__ = 551¶

__init__(*, applied: bool, has_conflicts: bool = False, conflicting_files: list[str] | None = None, patch_output: bytes | None = None, patch: Patch | None = None, patch_range: tuple[int, int] | None = None, binary_applied: Sequence[str] | None = None, binary_failed: Mapping[str, str] | None = None) → None[source]¶

Initialize the object.

Changed in version 5.1:

This now requires keyword-only arguments. Support for positional arguments will be removed in RBTools 7.
Added the patch and patch_range arguments.

Parameters:

applied (bool) – Whether the patch was applied.
has_conflicts (bool, optional) – Whether the applied patch included conflicts.
conflicting_files (list of str, optional) – A list of the filenames containing conflicts.
patch_output (bytes, optional) – The output of the patch command.
patch (Patch, optional) –
The patch that was being applied, if available.

Added in version 5.1.
patch_range (tuple, optional) –
The range of patches represented by this result.

This is in the form of:
Tuple:
- 0 (int) – The 1-based starting patch number.
- 1 (int) – The 1-based ending patch number.
Added in version 5.1.
binary_applied (list of str, optional) –
Binary files that were successfully applied.

Added in version 6.0.
binary_failed (dict, optional) –
Binary files that failed to apply, mapped to failure reason.

Added in version 6.0.

__repr__() → str[source]¶

Return a string representation of the object.

Returns:: The string representation.
Return type:: str

__static_attributes__ = ('applied', 'binary_applied', 'binary_failed', 'conflicting_files', 'has_conflicts', 'patch', 'patch_output', 'patch_range')¶

applied: bool¶

Whether the patch was applied.

This will be True whether the patch was fully applied without issues, or partially applied. Callers sohuld check success to check for a successful application, and has_conflicts to check for conflicts.

binary_applied: Sequence[str]¶: Binary files that were successfully applied.

Added in version 6.0.

binary_failed: Mapping[str, str]¶: Binary files that failed to apply, mapped to failure reason.

Added in version 6.0.

conflicting_files: list[str]¶: A list of the filenames containing conflicts.

has_conflicts: bool¶: Whether the applied patch included conflicts.

patch: Patch | None¶

The patch that was being applied.

This may be None, depending on the method used to apply the patch.

Added in version 5.1.

patch_output: bytes | None¶: The output of the patch command.

patch_range: tuple[int, int] | None¶

The range of patches represented by this result.

This is in the form of:

Tuple:

0 (int) – The 1-based starting patch number.
1 (int) – The 1-based ending patch number.

Added in version 5.1.

property success: bool[source]¶: Whether this was a successful patch application.