rbtools.diffs.patches¶

Patch information and support for applying patches.

Classes

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.

__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.

full_name: str¶

The full name of the author.

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

email: str¶

The e-mail address of the author.

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

__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

__repr__() → str[source]¶

Return a string representation of this object.

New in version 5.1.

Returns:

The string representation.

Return type:

str

__hash__ = None¶

class rbtools.diffs.patches.Patch(*, author: Optional[PatchAuthor] = None, base_dir: Optional[str] = None, content: Optional[bytes] = None, message: Optional[str] = None, path: Optional[Path] = None, prefix_level: Optional[int] = None)[source]¶

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).

New in version 5.1.

__init__(*, author: Optional[PatchAuthor] = None, base_dir: Optional[str] = None, content: Optional[bytes] = None, message: Optional[str] = None, path: Optional[Path] = None, prefix_level: Optional[int] = None) → None[source]¶

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.

Raises:

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

author: Optional[PatchAuthor]¶

The author of the patch.

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

base_dir: Optional[str]¶

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.

message: Optional[str]¶

The commit message describing the patch.

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

prefix_level: Optional[int]¶

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>.

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 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.

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.

__repr__() → str[source]¶

Return a string representation of the object.

Returns:

The string representation.

Return type:

str

class rbtools.diffs.patches.PatchResult(*, applied: bool, has_conflicts: bool = False, conflicting_files: list[str] = [], patch_output: Optional[bytes] = None, patch: Optional[Patch] = None, patch_range: Optional[tuple[int, int]] = 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.

__init__(*, applied: bool, has_conflicts: bool = False, conflicting_files: list[str] = [], patch_output: Optional[bytes] = None, patch: Optional[Patch] = None, patch_range: Optional[tuple[int, int]] = 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.

  New 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.

  New in version 5.1.

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.

conflicting_files: list[str]¶

A list of the filenames containing conflicts.

has_conflicts: bool¶

Whether the applied patch included conflicts.

patch: Optional[Patch]¶

The patch that was being applied.

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

New in version 5.1.

patch_output: Optional[bytes]¶

The output of the patch command.

patch_range: Optional[tuple[int, int]]¶

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.

New in version 5.1.

property success: bool[source]¶

Whether this was a successful patch application.

__repr__() → str[source]¶

Return a string representation of the object.

Returns:

The string representation.

Return type:

str