reviewbot.processing.review¶

Utilities for processing files and creating reviews.

Module Attributes

logger

The logger for the module.

Classes

`BaseCommentData`	Base class for comment data.
`DiffChunk`	Data for a diff chunk.
`DiffCommentData`	Data for a diff comment.
`File`(review, api_filediff)	Represents a file in the review.
`GeneralCommentData`	Data for a general comment.
`Review`(api_root, review_request_id, ...)	An object which orchestrates the creation of a review.
`ReviewFileStatus`(value[, names, module, ...])	The change status of a file.

logger = <Logger reviewbot.processing.review (WARNING)>[source]¶: The logger for the module.

New in version 3.0.

class BaseCommentData[source]¶

Bases: TypedDict

Base class for comment data.

New in version 5.0.

issue_opened: bool¶: Whether an issue should be opened.

rich_text: bool¶: Whether the comment text should be formatted using Markdown.

text: str¶: The text of the comment.

__annotations__ = {'issue_opened': ForwardRef('bool', module='reviewbot.processing.review'), 'rich_text': ForwardRef('bool', module='reviewbot.processing.review'), 'text': ForwardRef('str', module='reviewbot.processing.review')}¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__required_keys__ = frozenset({'issue_opened', 'rich_text', 'text'})¶

__total__ = True¶

class GeneralCommentData[source]¶

Bases: BaseCommentData

Data for a general comment.

New in version 5.0.

__annotations__ = {'issue_opened': ForwardRef('bool', module='reviewbot.processing.review'), 'rich_text': ForwardRef('bool', module='reviewbot.processing.review'), 'text': ForwardRef('str', module='reviewbot.processing.review')}¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<class 'reviewbot.processing.review.BaseCommentData'>,)¶

__required_keys__ = frozenset({'issue_opened', 'rich_text', 'text'})¶

__total__ = True¶

issue_opened: bool¶

rich_text: bool¶

text: str¶

class DiffCommentData[source]¶

Bases: BaseCommentData

Data for a diff comment.

New in version 5.0.

filediff_id: int¶: The ID of the FileDiff that the comment is on.

first_line: int¶: The row number that the comment starts on.

num_lines: int¶: The number of lines that the comment spans.

__annotations__ = {'filediff_id': ForwardRef('int', module='reviewbot.processing.review'), 'first_line': ForwardRef('int', module='reviewbot.processing.review'), 'issue_opened': ForwardRef('bool', module='reviewbot.processing.review'), 'num_lines': ForwardRef('int', module='reviewbot.processing.review'), 'rich_text': ForwardRef('bool', module='reviewbot.processing.review'), 'text': ForwardRef('str', module='reviewbot.processing.review')}¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<class 'reviewbot.processing.review.BaseCommentData'>,)¶

__required_keys__ = frozenset({'filediff_id', 'first_line', 'issue_opened', 'num_lines', 'rich_text', 'text'})¶

__total__ = True¶

issue_opened: bool¶

rich_text: bool¶

text: str¶

class DiffChunk[source]¶

Bases: TypedDict

Data for a diff chunk.

This corresponds with the data created in reviewboard.diffviewer.chunk_generator. This definition includes types for the keys we use, but omits anything that Review Bot doesn’t need, so it is not a complete representation of what comes back through the API.

New in version 5.0.

change: Literal['delete', 'equal', 'insert', 'replace']¶: The type of change for the chunk.

index: int¶: The 0-based index of the chunk.

lines: list[list[Any]]¶: The rendered list of lines.

meta: dict[str, Any]¶: Metadata for the chunk.

numlines: int¶: The number of lines in the chunk.

__annotations__ = {'change': ForwardRef("Literal['delete', 'equal', 'insert', 'replace']", module='reviewbot.processing.review'), 'index': ForwardRef('int', module='reviewbot.processing.review'), 'lines': ForwardRef('list[list[Any]]', module='reviewbot.processing.review'), 'meta': ForwardRef('dict[str, Any]', module='reviewbot.processing.review'), 'numlines': ForwardRef('int', module='reviewbot.processing.review')}¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__required_keys__ = frozenset({'change', 'index', 'lines', 'meta', 'numlines'})¶

__total__ = True¶

class ReviewFileStatus(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: str, Enum

The change status of a file.

New in version 3.0.

CREATED = 'created'[source]¶

DELETED = 'deleted'[source]¶

MODIFIED = 'modified'[source]¶

MOVED = 'moved'[source]¶

COPIED = 'copied'[source]¶

classmethod for_filediff(filediff: FileDiffItemResource) → ReviewFileStatus[source]¶

Return a status for a FileDiff.

Parameters:: filediff (rbtools.api.resource.FileDiffItemResource) – The filediff resource.
Returns:: The resulting status.
Return type:: ReviewFileStatus
Raises:: ValueError – The status for the FileDiff is unknown/unsupported.

__format__(format_spec)¶: Return a formatted version of the string as described by format_spec.

__new__(value)¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

class File(review: Review, api_filediff: FileDiffItemResource)[source]¶

Bases: object

Represents a file in the review.

Information about the file can be retrieved through this class, including retrieving the actual body of the original or patched file.

Allows comments to be made to the file in the review.

COMMENT_MAX_LINES: Final[int] = 10¶

The maximum number of lines allowed for a comment.

If a comment exceeds this count, it will be capped and a line range will be provided in the comment.

__init__(review: Review, api_filediff: FileDiffItemResource) → None[source]¶

Initialize the File.

Parameters:

review (Review) – The review object.
api_filediff (rbtools.api.resource.FileDiffItemResource) – The filediff resource.

review: Review¶: The review that owns this file.

id: int¶: Tde ID of the FileDiff.

diff_data: ItemResource¶: The diff data from the server.

status: ReviewFileStatus¶: The status of the file in the diff.

patched_file_path: Optional[str]¶: The path to the patched file.

source_file: str¶: The name of the original version of the file.

dest_file: str¶: The name of the patched version of the file.

filename: str¶: The name of the file (without the extension).

file_extension: str¶: The file extension.

property patched_file_contents: Optional[bytes][source]¶

The patched contents of the file.

Returns:: The contents of the patched file.
Return type:: bytes

property original_file_contents: Optional[bytes][source]¶

The original contents of the file.

Returns:: The contents of the original file.
Return type:: bytes

get_patched_file_path() → Optional[str][source]¶

Fetch the patched file and return the filename of it.

Changed in version 3.0: Empty files no longer return None.

Returns:: The filename of a new temporary file containing the patched file contents. If the file is deleted, this will return None.
Return type:: str

get_original_file_path() → Optional[str][source]¶

Fetch the original file and return the filename of it.

Changed in version 3.0: Empty files no longer return None.

Returns:: The filename of a new temporary file containing the original file contents. If the file is new, this will return None.
Return type:: str

get_lines(first_line: int, num_lines: int = 1, original: bool = False) → list[str][source]¶

Return the lines from the file in the given range.

This can be used to extract lines from the original or modified file, as represented in the diff data. Some tool implementations can use this to provide more informative results (e.g., by providing suggested fixes to lines based on diffed/delta information coming from the program backing the tool).

Parameters:

first_line (int) – The first line in the range.
num_lines (int, optional) – The maximum number of lines to return.
original (bool, optional) – Whether to return lines from the original (unmodified) file.

Returns:

The list of lines, up to the maximum requested. This will be empty if the lines could not be found.

Return type:

list of str

apply_patch(root_target_dir: str) → None[source]¶

Apply the patch for this file to the filesystem.

The file will be written relative to the current directory.

New in version 3.0.

Parameters:: root_target_dir (str) – The root directory for the project. No files are allowed to be created, modified, deleted, or linked to outside of this path.
Raises:: reviewbot.errors.SuspiciousFilePath – The patch tried to work with a file outside of root_target_dir.

comment(text: str, first_line: Optional[int], num_lines: int = 1, start_column: Optional[int] = None, error_code: Optional[str] = None, issue: Optional[bool] = None, rich_text: Optional[bool] = False, original: Optional[bool] = False, text_extra: Optional[list[tuple[str, str]]] = None, severity: Optional[str] = None) → None[source]¶

Make a comment on the file.

Changed in version 3.0: Added error_code, severity, start_column, and text_extra arguments.

Parameters:

text (str) – The text of the comment.
first_line (int) – The line number that the comment starts on. If None, the comment is considered to be for the entire file.
num_lines (int, optional) – The number of lines that the comment should span.
start_column (int, optional) – The starting column within the code line where an error applied, as reported by a linter. If provided, this will be appended to the text.
error_code (str, optional) – An error code for the error being reported. If provided, this will be appended to the text.
issue (bool, optional) – Whether an issue should be opened.
rich_text (bool, optional) – Whether the comment text should be formatted using Markdown.
original (bool, optional) – If True, the first_line argument corresponds to the line number in the original file, instead of the patched file.
text_extra (list of tuple, optional) – Additional data to append to the text in Key: Value form. Each item is an ordered tuple of (Key, Value). These will be placed after the default items (“Column” and “Error code”).
severity (str, optional) – A tool-specific, human-readable indication of the severity of this comment.

__annotations__ = {'COMMENT_MAX_LINES': 'Final[int]', '_api_filediff': 'FileDiffItemResource', 'dest_file': 'str', 'diff_data': 'ItemResource', 'file_extension': 'str', 'filename': 'str', 'id': 'int', 'patched_file_path': 'Optional[str]', 'review': 'Review', 'source_file': 'str', 'status': 'ReviewFileStatus'}¶

class Review(api_root: RootResource, review_request_id: int, diff_revision: int, settings: dict[str, Any])[source]¶

Bases: object

An object which orchestrates the creation of a review.

__annotations__ = {'_VALID_FILEDIFF_STATUS_TYPES': 'Final[set[str]]', 'api_root': 'RootResource', 'body_bottom': 'str', 'body_top': 'str', 'comments': 'list[DiffCommentData]', 'diff_revision': 'int', 'files': 'list[File]', 'general_comments': 'list[GeneralCommentData]', 'patch': 'Optional[str]', 'review_request_id': 'int', 'settings': 'dict[str, Any]'}¶

patch: Optional[str]¶: The patch contents.

__init__(api_root: RootResource, review_request_id: int, diff_revision: int, settings: dict[str, Any]) → None[source]¶

Initialize the review.

Parameters:

api_root (rbtools.api.resource.RootResource) – The API root.
review_request_id (int) – The ID of the review request being reviewed (ID for use in the API, which is the “display_id” field).
diff_revision (int) – The diff revision being reviewed.
settings (dict) – The settings provided by the extension when triggering the task.

body_top: str¶: Additional text to show above the comments in the review.

body_bottom: str¶: Additional text to show below the comments in the review.

api_root: RootResource¶: The API root for the Review Board server.

settings: dict[str, Any]¶: The settings provided by the extension.

review_request_id: int¶: The ID of the review request being reviewed.

diff_revision: int¶: The diff revision being reviewed.

comments: list[DiffCommentData]¶: The diff comments in the review.

general_comments: list[GeneralCommentData]¶: The general comments in the review.

files: list[File]¶: The files to be reviewed.

general_comment(text: str, issue: Optional[bool] = None, rich_text: bool = False) → None[source]¶

Make a general comment.

Parameters:

text (str) – The text of the comment.
issue (bool, optional) – Whether an issue should be opened.
rich_text (bool, optional) – Whether the comment text should be formatted using Markdown.

publish() → ReviewItemResource[source]¶: Upload the review to Review Board.

property has_comments: bool[source]¶

Whether the review has comments.

Type:: bool

property patch_contents: Optional[str][source]¶

The contents of the patch.

Type:: str

get_patch_file_path() → Optional[str][source]¶

Fetch the patch and return the filename of it.

Returns:: The filename of a new temporary file containing the patch contents. If the patch is empty, return None.
Return type:: str