reviewboard.reviews.ui.base¶

Base class for a Review UI.

class SerializedCommentUser[source]¶

Bases: TypedDict

Serialized user for comment data.

This must be kept in sync with the definitions in reviewboard/static/rb/js/reviews/models/commentData.ts.

New in version 7.0.

name: str¶

The user’s full name, if available.

username: str¶

The user’s username.

__annotations__ = {'name': ForwardRef('str', module='reviewboard.reviews.ui.base'), 'username': ForwardRef('str', module='reviewboard.reviews.ui.base')}¶

__closed__ = False¶

__extra_items__ = None¶

__mutable_keys__ = frozenset({'name', 'username'})¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__readonly_keys__ = frozenset({})¶

__required_keys__ = frozenset({'name', 'username'})¶

__total__ = True¶

class SerializedComment[source]¶

Bases: TypedDict

Serialized comment data to pass through to JavaScript.

This must be kept in sync with the definitions in reviewboard/static/rb/js/reviews/models/commentData.ts.

New in version 7.0.

comment_id: int¶

The ID of the comment.

html: str¶

The rendered HTML version of the comment text.

issue_opened: bool¶

Whether the comment opens an issue.

issue_status: str¶

The status of the issue, if one was opened.

localdraft: bool¶

Whether the comment is part of the user’s current draft review.

reply_to_id: int¶

The ID of the comment that this comment is a reply to.

review_id: int¶

The ID of the review that this comment is a part of.

review_request_id: int¶

The ID of the review request that this comment is on.

rich_text: bool¶

Whether the comment text should be rendered in Markdown.

text: str¶

The raw text of the comment.

url: str¶

The URL to link to for the comment.

user: SerializedCommentUser¶

Information about the author of the comment.

__annotations__ = {'comment_id': ForwardRef('int', module='reviewboard.reviews.ui.base'), 'html': ForwardRef('str', module='reviewboard.reviews.ui.base'), 'issue_opened': ForwardRef('bool', module='reviewboard.reviews.ui.base'), 'issue_status': ForwardRef('str', module='reviewboard.reviews.ui.base'), 'localdraft': ForwardRef('bool', module='reviewboard.reviews.ui.base'), 'reply_to_id': ForwardRef('int', module='reviewboard.reviews.ui.base'), 'review_id': ForwardRef('int', module='reviewboard.reviews.ui.base'), 'review_request_id': ForwardRef('int', module='reviewboard.reviews.ui.base'), 'rich_text': ForwardRef('bool', module='reviewboard.reviews.ui.base'), 'text': ForwardRef('str', module='reviewboard.reviews.ui.base'), 'url': ForwardRef('str', module='reviewboard.reviews.ui.base'), 'user': ForwardRef('SerializedCommentUser', module='reviewboard.reviews.ui.base')}¶

__closed__ = False¶

__extra_items__ = None¶

__mutable_keys__ = frozenset({'comment_id', 'html', 'issue_opened', 'issue_status', 'localdraft', 'reply_to_id', 'review_id', 'review_request_id', 'rich_text', 'text', 'url', 'user'})¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__readonly_keys__ = frozenset({})¶

__required_keys__ = frozenset({'comment_id', 'html', 'issue_opened', 'issue_status', 'localdraft', 'reply_to_id', 'review_id', 'review_request_id', 'rich_text', 'text', 'url', 'user'})¶

__total__ = True¶

ReviewableType[source]¶

A generic type for the reviewable object for a Review UI.

New in version 7.0.

alias of TypeVar(‘ReviewableType’)

CommentType[source]¶

A generic type for the type of comment used by a Review UI.

New in version 7.0.

alias of TypeVar(‘CommentType’, bound=BaseComment)

SerializedCommentType[source]¶

A generic type for the serialized comment data for a ReviewUI.

New in version 7.0.

alias of TypeVar(‘SerializedCommentType’, bound=SerializedComment)

SerializedCommentBlocks¶

A type for the serialized comments for a review UI.

New in version 7.0.

alias of Dict[str, List[SerializedCommentType]]

class ReviewUI(review_request: ReviewRequest, obj: ReviewableType)[source]¶

Bases: Generic[ReviewableType, CommentType, SerializedCommentType]

Base class for a Review UI.

Review UIs are interfaces for reviewing content of some type. They take a type of object and render a page around it, optionally allowing for the display of a diff view for the content. They can render context for comments made on the object, provide details for social media sharing (such as on a chat or social network).

A Review UI makes use of a JavaScript side for the interaction, defined using js_model_class and js_view_class. The JavaScript side should interface with the API to create/update reviews and comments for the object being reviewed.

diff_against_obj¶

The object being diffed against, if any.

Type:

object

obj¶

The object being reviewed.

Type:

object

request¶

The HTTP request from the client. This is only set once render_to_string() is called.

Type:

django.http.HttpRequest

review_request¶

The review request containing the object being reviewed.

Type:

reviewboard.reviews.models.review_request.ReviewRequest

name: ClassVar[str] = 'Unknown file type'¶

The display name for the Review UI.

template_name: ClassVar[str] = 'reviews/ui/default.html'¶

The template that renders the Review UI.

Generally, subclasses should use the default template and render the UI using JavaScript.

allow_inline: ClassVar[bool] = False¶

Whether the Review UI can be rendered inline in diffs and other places.

If set, the Review UI will be able to be displayed within the diff viewer (and potentially other locations).

supports_diffing: ClassVar[bool] = False¶

Whether this Review UI supports diffing two objects.

css_bundle_names: ClassVar[list[str]] = []¶

A list of CSS bundle names to include on the Review UI’s page.

js_bundle_names: ClassVar[list[str]] = []¶

A list of JavaScript bundle names to include on the Review UI’s page.

js_files: ClassVar[list[str]] = []¶

A list of specific JavaScript URLs to include on the page.

It is recommended that js_bundle_names be used instead where possible.

supported_mimetypes: ClassVar[list[str]] = []¶

The list of MIME types that this Review UI supports.

supports_file_attachments: ClassVar[bool] = False¶

Whether this Review UI supports reviewing FileAttachment objects.

diff_type_mismatch: ClassVar[bool] = False¶

Whether there’s a file type mismatch when showing diffs.

property js_model_class: str[source]¶

The name of the JavaScript model class to use for the Review UI.

Type:

str

property js_view_class: str[source]¶

The name of the JavaScript view class to use for the Review UI.

Type:

str

property object_key: str[source]¶

The key passed to the template representing the object.

Type:

str

property diff_object_key: str[source]¶

The key passed to the template for an object to diff against.

Type:

str

__init__(review_request: ReviewRequest, obj: ReviewableType) → None[source]¶

Initialize the Review UI.

Parameters:

• review_request (reviewboard.reviews.models.ReviewRequest) – The review request containing the object to review.

• obj (object) – The object being reviewed.

obj: ReviewableType¶

The object being reviewed.

diff_against_obj: Optional[ReviewableType]¶

The object being compared against, if present.

request: Optional[HttpRequest]¶

The current HTTP request.

set_diff_against(obj: ReviewableType) → None[source]¶

Set the object to generate a diff against.

This can only be called on Review UIs that support diffing, and must be called before rendering.

Parameters:

obj (object) – The object being diffed against.

is_enabled_for(user: Optional[User] = None, review_request: Optional[ReviewRequest] = None, obj: Optional[object] = None, **kwargs) → bool[source]¶

Return whether the Review UI is enabled under the given criteria.

This can enable or disable a Review UI’s functionality depending on the user, review request, or some state associated with one or more of those.

When this is called, the arguments are always passed as keyword arguments. Subclasses don’t need to accept all the arguments, as long as they take a **kwargs.

Parameters:

• user (django.contrib.auth.models.User, optional) – The user to check.

• review_request (reviewboard.reviews.models.ReviewRequest, optional) – The review request to check.

• obj (object, optional) – The object being reviewed.

• **kwargs (dict) – Additional keyword arguments, for future expansion.

Returns:

True if the Review UI is enabled for the given criteria. False otherwise.

By default, Review UIs are always enabled.

Return type:

bool

render_to_response(request: HttpRequest) → HttpResponse[source]¶

Render the Review UI to a response.

This is used to render a page dedicated to the Review UI, complete with the standard Review Board chrome.

Parameters:

request (django.http.HttpRequest) – The HTTP request from the client.

Returns:

The HTTP response containing the page for the Review UI.

Return type:

django.http.HttpResponse

render_to_string(request: HttpRequest, inline: bool = True) → SafeText[source]¶

Render the Review UI to an HTML string.

This renders the Review UI to a string for use in embedding into either an existing page or a new page.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• inline (bool, optional) – Whether to render this such that it can be embedded into an existing page, instead of as a standalone page.

Returns:

The HTML for the Review UI.

Return type:

django.utils.safestring.SafeText

build_render_context(request: HttpRequest, inline: bool = False, **kwargs) → dict[str, Any][source]¶

Build context for rendering the page.

This computes the standard template context to use when rendering the page. Generally, subclasses should override get_extra_context(), instead of this.

Parameters:

• request (django.http.HttpRequest) – The HTTP request from the client.

• inline (bool, optional) – Whether to render this such that it can be embedded into an existing page, instead of as a standalone page.

• **kwargs (dict, unused) – Keyword arguments, for future expansion.

Returns:

The context to use in the template.

Return type:

dict

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

Return the URL to an image used to depict this on other sites.

The returned image URL will be used for services like Facebook, Slack, Twitter, etc. when linking to the reviewable object. This may be anything from a standard thumbnail to a full-size image.

By default, no image URL is returned.

Returns:

The absolute URL to an image used to depict the reviewable object.

Return type:

str

get_comments() → Sequence[CommentType][source]¶

Return all existing comments on the reviewable object.

Subclasses must override this.

Returns:

The list of comments for the page.

Return type:

list of reviewboard.reviews.models.base_comment.BaseComment

get_caption(draft: Optional[ReviewRequestDraft] = None) → str[source]¶

Return the caption to show for the reviewable object.

This defaults to requiring caption and draft_caption attributes on the reviewable object. Subclasses can override this to use something else.

Parameters:

draft (reviewboard.reviews.models.ReviewRequestDraft, optional) – The active review request draft for the user, if any.

Returns:

The caption for the reviewable object.

Return type:

str

get_comment_thumbnail(comment: CommentType) → Optional[SafeText][source]¶

Return an HTML thumbnail for a comment.

If comment thumbnails are possible for the reviewable object, this function should return HTML for the thumbnail.

Parameters:

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to return a thumbnail for.

Returns:

The HTML for a thumbnail for the comment, or None if one can’t be generated (using the default thumbnailing for the comment type, if one exists).

Return type:

django.utils.safestring.SafeText

get_comment_link_url(comment: CommentType) → str[source]¶

Return a URL for linking to a comment.

Subclasses must override this.

Parameters:

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to return a link for.

Returns:

The URL to link to the comment.

Return type:

str

get_comment_link_text(comment: CommentType) → Optional[str][source]¶

Return the text to link to a comment.

This must be implemented by subclasses.

Parameters:

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to return text for.

Returns:

The text used to link to the comment.

Return type:

str

get_extra_context(request: HttpRequest) → dict[str, Any][source]¶

Return extra context to use when rendering the Review UI.

Parameters:

request (django.http.HttpRequest) – The HTTP request from the client.

Returns:

The context to provide to the template.

Return type:

dict

get_js_model_data() → JSONDict[source]¶

Return data to pass to the JavaScript Model during instantiation.

This data will be passed as attributes to the reviewable model when constructed.

Returns:

The attributes to pass to the model.

Return type:

dict

get_js_view_data() → JSONDict[source]¶

Return data to pass to the JavaScript View during instantiation.

This data will be passed as options to the reviewable view when constructed.

Returns:

The options to pass to the view.

Return type:

dict

get_comments_json() → str[source]¶

Return a JSON-serialized representation of comments for a template.

The result of this can be used directly in a template to provide comments to JavaScript functions.

Returns:

Serialized JSON content representing the comments on the reviewable object.

Return type:

str

serialize_comments(comments: Sequence[CommentType]) → Dict[str, List[SerializedCommentType]][source]¶

Serialize the comments for the Review UI target.

By default, this will return a “flat” array of comments, but it can be overridden in order to group comments by identifier or region.

Parameters:

comments (list of reviewboard.reviews.models.base_comment.BaseComment) – The list of objects to serialize. This will be the result of get_comments().

Returns:

The set of serialized comment data.

Return type:

SerializedCommentBlocks

flat_serialized_comments(comments: Sequence[CommentType]) → Iterator[SerializedCommentType][source]¶

Yield the serialized comments.

This will go through the list of comments and filter out any which should not be shown (ones which are in other users’ drafts), then yield the serialized form for each.

Yields:

SerializedComment – The serialized comment.

serialize_comment(comment: CommentType) → SerializedComment[source]¶

Serialize a comment.

This will provide information on the comment that may be useful to the JavaScript code.

Subclasses that want to add additional data should generally augment the result of this function and not replace it.

Parameters:

comment (reviewboard.reviews.models.base_comment.BaseComment) – The comment to serialize.

Returns:

The serialized comment data.

Return type:

SerializedComment

classmethod for_object(obj: object) → Optional[type[reviewboard.reviews.ui.base.ReviewUI]][source]¶

Return the Review UI that is the best fit for a given object.

Parameters:

obj (object) – The object to review.

Returns:

The Review UI class for the given object, or None if a suitable one could not be found.

Return type:

class

__annotations__ = {'allow_inline': 'ClassVar[bool]', 'css_bundle_names': 'ClassVar[list[str]]', 'diff_against_obj': 'Optional[ReviewableType]', 'diff_type_mismatch': 'ClassVar[bool]', 'js_bundle_names': 'ClassVar[list[str]]', 'js_files': 'ClassVar[list[str]]', 'name': 'ClassVar[str]', 'obj': 'ReviewableType', 'request': 'Optional[HttpRequest]', 'supported_mimetypes': 'ClassVar[list[str]]', 'supports_diffing': 'ClassVar[bool]', 'supports_file_attachments': 'ClassVar[bool]', 'template_name': 'ClassVar[str]'}¶

__orig_bases__ = (typing.Generic[~ReviewableType, ~CommentType, ~SerializedCommentType],)¶

__parameters__ = (~ReviewableType, ~CommentType, ~SerializedCommentType)¶

class FileAttachmentReviewUI(review_request: ReviewRequest, obj: ReviewableType)[source]¶

Bases: ReviewUI

Base class for Review UIs for file attachments.

Review UIs that deal with FileAttachment objects can subclass this to provide the common functionality for their Review UI.

This class handles fetching and serializing comments, locating a correct subclass for a given mimetype, and feeding data to the JavaScript RB.AbstractReviewable() model.

This also handles much of the work for diffing file attachments.

supports_file_attachments: ClassVar[bool] = True[source]¶

Whether this Review UI supports reviewing FileAttachment objects.

classmethod get_best_handler(mimetype: tuple[str, str, str]) → tuple[float, Optional[type[ReviewUI]]][source]¶

Return the Review UI and score that that best fit the mimetype.

Parameters:

mimetype (tuple) – A parsed mimetype to find the best review UI for. This is a 3-tuple of the type, subtype, and parameters as returned by mimeparse.parse_mime_type().

Returns:

A tuple of (best_score, review_ui), or (0, None) if one could not be found.

Return type:

tuple

classmethod for_type(attachment: FileAttachment) → Optional[ReviewUI][source]¶

Return the Review UI that is the best fit for a file attachment.

Parameters:

attachment (reviewboard.attachments.models.FileAttachments) – The file attachment to locate a Review UI for.

Returns:

The Review UI for the attachment, or None if a suitable one could not be found.

Return type:

FileAttachmentReviewUI

__annotations__ = {'allow_inline': 'ClassVar[bool]', 'css_bundle_names': 'ClassVar[list[str]]', 'diff_against_obj': 'Optional[ReviewableType]', 'diff_type_mismatch': 'ClassVar[bool]', 'js_bundle_names': 'ClassVar[list[str]]', 'js_files': 'ClassVar[list[str]]', 'name': 'ClassVar[str]', 'obj': 'ReviewableType', 'request': 'Optional[HttpRequest]', 'supported_mimetypes': 'ClassVar[list[str]]', 'supports_diffing': 'ClassVar[bool]', 'supports_file_attachments': 'ClassVar[bool]', 'template_name': 'ClassVar[str]'}¶

__parameters__ = ()¶

class DiffMismatchReviewUI(review_request: ReviewRequest, obj: ReviewableType)[source]¶

Bases: ReviewUI

A special review UI to show when the file types in a diff don’t match.

diff_type_mismatch: ClassVar[bool] = True[source]¶

Whether there’s a file type mismatch when showing diffs.

supports_diffing: ClassVar[bool] = True[source]¶

Whether this Review UI supports diffing two objects.

__annotations__ = {'allow_inline': 'ClassVar[bool]', 'css_bundle_names': 'ClassVar[list[str]]', 'diff_against_obj': 'Optional[ReviewableType]', 'diff_type_mismatch': 'ClassVar[bool]', 'js_bundle_names': 'ClassVar[list[str]]', 'js_files': 'ClassVar[list[str]]', 'name': 'ClassVar[str]', 'obj': 'ReviewableType', 'request': 'Optional[HttpRequest]', 'supported_mimetypes': 'ClassVar[list[str]]', 'supports_diffing': 'ClassVar[bool]', 'supports_file_attachments': 'ClassVar[bool]', 'template_name': 'ClassVar[str]'}¶

__parameters__ = ()¶

register_ui(review_ui: type[reviewboard.reviews.ui.base.ReviewUI]) → None[source]¶

Register a Review UI class.

This will register a Review UI. Review Board will use it to display a UI when reviewing a supported file attachment.

Parameters:

review_ui (type) – The Review UI to register. This must be a subclass of ReviewUI.

Raises:

TypeError – The provided Review UI class is not of a compatible type.

unregister_ui(review_ui: type[reviewboard.reviews.ui.base.ReviewUI]) → None[source]¶

Unregister a Review UI class.

This will unregister a previously registered Review UI.

Only ReviewUI subclasses are supported. The class must have been registered beforehand or a ValueError will be thrown.

Parameters:

review_ui (type) – The Review UI to unregister. This must be a subclass of ReviewUI, and must have been registered before.

Raises:

• TypeError – The provided Review UI class is not of a compatible type.

• ValueError – The provided Review UI was not previously registered.

is_review_ui_enabled_for(*, review_ui: ReviewUI[FileAttachment, FileAttachmentComment, SerializedComment], request: HttpRequest, review_request: ReviewRequest, file_attachment: FileAttachment) → bool[source]¶

Return whether a Review UI is enabled for the given object.

Deprecated since version 7.0.3: Use is_review_ui_accessible_by() instead. This function will be removed in 8.0.

New in version 7.0.2.

Parameters:

• review_ui (reviewboard.reviews.ui.base.ReviewUI) – The Review UI to check.

• request (django.http.HttpRequest) – The HTTP request from the client.

• review_request (reviewboard.reviews.models.ReviewRequest) – The review request.

• file_attachment (reviewboard.attachments.models.FileAttachment) – The file attachment.

Returns:

True if the review UI is enabled for the given attachment.

Return type:

bool