reviewboard.reviews.models¶

class BaseComment(*args, **kwargs)[source]¶

The base class for all comment types.

static issue_status_to_string(status)[source]¶

Return a string representation of the status field.

Parameters: status (unicode) – The value of the issue_status field.
Returns: A string representation of the status used for the API and other interfaces.
Return type: unicode

static issue_string_to_status(status)[source]¶

Return a DB representation of the given status string.

Parameters: status (unicode) – The status string to convert.
Returns: A value suitable for storing in the issue_status field.
Return type: unicode

property require_verification[source]¶: Whether this comment requires verification before closing.

get_review_request()[source]¶

Return this comment’s review request.

Returns: The review request that this comment was made on.
Return type: reviewboard.reviews.models.review_request.ReviewRequest

get_review()[source]¶

Return this comment’s review.

Returns: The review containing this comment.
Return type: reviewboard.reviews.models.review.Review

get_review_url()[source]¶

Return the URL to view this comment.

Returns: The absolute URL to view this comment in the web UI.
Return type: unicode

is_reply()[source]¶

Return whether this comment is a reply to another comment.

Returns: True if the comment is a reply.
Return type: bool

is_accessible_by(user)[source]¶

Return whether the user can access this comment.

Parameters: user (django.contrib.auth.models.User) – The user being checked.
Returns: True if the given user can access this comment.
Return type: bool

is_mutable_by(user)[source]¶

Return whether the user can modify this comment.

Parameters: user (django.contrib.auth.models.User) – The user being checked.
Returns: True if the given user can modify this comment.
Return type: bool

public_replies(user=None)[source]¶

Return the public replies to this comment.

Parameters: user (django.contrib.auth.models.User, optional) – A user to filter by, if desired. If specified, only replies authored by this user will be returned.
Returns: The public replies to this comment.
Return type: list of reviewboard.reviews.models.base_comment.BaseComment

can_change_issue_status(user)[source]¶

Return whether the user can change the issue status.

Currently, this is allowed for: - The user who owns the review request. - The user who opened the issue (posted the comment).

Parameters: user (django.contrib.auth.models.User) – The user being checked.
Returns: True if the given user is allowed to change the issue status.
Return type: bool

can_verify_issue_status(user)[source]¶

Return whether the user can verify the issue status.

Currently this is allowed for:

The user who opened the issue.
Administrators.

Parameters: user (django.contrib.auth.models.User) – The user being checked.
Returns: True if the given user is allowed to verify the issue status.
Return type: bool

save(**kwargs)[source]¶

Save the comment.

Parameters: **kwargs (dict) – Keyword arguments passed to the method (unused).

class Comment(*args, **kwargs)[source]¶

A comment made on a diff.

A comment can belong to a single filediff or to an interdiff between two filediffs. It can also have multiple replies.

property base_filediff_id[source]¶: The base FileDiff ID for the cumulative diff this comment is on.

class DefaultReviewer(*args, **kwargs)[source]¶

Represents reviewers automatically added to review requests.

A default reviewer entry automatically adds default reviewers to a review request when the diff modifies a file matching the file_regex pattern specified.

This is useful when different groups own different parts of a codebase. Adding DefaultReviewer entries ensures that the right people will always see the review request and discussions.

A file_regex of ".*" will add the specified reviewers by default for every review request.

Note that this is keyed off the same LocalSite as its “repository” member.

is_accessible_by(user)[source]¶: Returns whether the user can access this default reviewer.

is_mutable_by(user)[source]¶

Returns whether the user can modify or delete this default reviewer.

Only those with the default_reviewer.change_group permission (such as administrators) can modify or delete default reviewers not bound to a LocalSite.

LocalSite administrators can modify or delete them on their LocalSites.

class FileAttachmentComment(*args, **kwargs)[source]¶

A comment on a file attachment.

review_ui[source]¶

Return a ReviewUI appropriate for this comment.

If a ReviewUI is available for this type of file, an instance of one will be returned that’s associated with this comment’s FileAttachment and the one being diffed against (if any).

property thumbnail[source]¶

Returns the thumbnail for this comment, if any, as HTML.

The thumbnail will be generated from the appropriate ReviewUI, if there is one for this type of file.

get_absolute_url()[source]¶: Returns the URL for this comment.

get_link_text()[source]¶: Returns the text for the link to the file.

class GeneralComment(*args, **kwargs)[source]¶

A comment on a review request that is not tied to any code or file.

A general comment on a review request is used when a comment is not tied to specific lines of code or a special file attachment, and an issue is opened. Examples include suggestions for testing or pointing out errors in the change description.

class Group(*args, **kwargs)[source]¶

A group of people who can be targetted for review.

This is usually used to separate teams at a company or components of a project.

Each group can have an e-mail address associated with it, sending all review requests and replies to that address. If that e-mail address is blank, e-mails are sent individually to each member of that group.

is_accessible_by(user, request=None, silent=False)[source]¶: Returns true if the user can access this group.

is_mutable_by(user)[source]¶

Returns whether or not the user can modify or delete the group.

The group is mutable by the user if they are an administrator with proper permissions, or the group is part of a LocalSite and the user is in the admin list.

clean()[source]¶

Clean method for checking null unique_together constraints.

Django has a bug where unique_together constraints for foreign keys aren’t checked properly if one of the relations is null. This means that users who aren’t using local sites could create multiple groups with the same name.

class Review(*args, **kwargs)[source]¶

A review of a review request.

ship_it_only[source]¶

Return if the review only contains a “Ship It!”.

Returns: True if the review is only a “Ship It!” and False otherwise.
Return type: bool

can_user_revoke_ship_it(user)[source]¶

Return whether a given user can revoke a Ship It.

Parameters: user (django.contrib.auth.models.User) – The user to check permissions for.
Returns: True if the user has permissions to revoke a Ship It. False if they don’t.
Return type: bool

revoke_ship_it(user)[source]¶

Revoke the Ship It status on this review.

The Ship It status will be removed, and the ReviewRequest.shipit_count counter will be decremented.

If the body_top text is equal to SHIP_IT_TEXT, then it will replaced with REVOKED_SHIP_IT_TEXT.

Callers are responsible for checking whether the user has permission to revoke Ship Its by using can_user_revoke_ship_it().

Raises: reviewboard.reviews.errors.RevokeShipItError – The Ship It could not be revoked. Details will be in the error message.

all_participants[source]¶

Return all participants in the review’s discussion.

This will always contain the user who filed the review, plus every user who has published a reply to the review.

The result is cached. Repeated calls will return the same result.

Returns: The users who participated in the discussion.
Return type: set of django.contrib.auth.models.User

is_accessible_by(user)[source]¶: Returns whether the user can access this review.

is_mutable_by(user)[source]¶: Returns whether the user can modify this review.

is_reply()[source]¶: Returns whether or not this review is a reply to another review.

is_new_for_user(user, last_visited)[source]¶

Return whether this review is new for a user.

The review is considered new if their last visited time is older than the review’s published timestamp and the user is not the one who created the review.

Parameters

user (django.contrib.auth.models.User) – The user accessing the review.
last_visited (datetime.datetime) – The last time the user accessed a page where the review would be shown.

Returns

True if the review is new to this user. False if it’s older than the last visited time or the user created it.

Return type

bool

public_replies()[source]¶: Returns a list of public replies to this review.

public_body_top_replies(user=None)[source]¶: Returns a list of public replies to this review’s body top.

public_body_bottom_replies(user=None)[source]¶: Returns a list of public replies to this review’s body bottom.

get_pending_reply(user)[source]¶

Return the pending reply owned by the specified user.

Parameters: user (django.contrib.auth.models.User) – The user to find the reply for.
Returns: The pending reply object, if present. None if there is no pending reply.
Return type: reviewboard.reviews.models.review.Review

save(**kwargs)[source]¶

Saves the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

publish(user=None, trivial=False, to_owner_only=False, request=None)[source]¶

Publishes this review.

This will make the review public and update the timestamps of all contained comments.

delete()[source]¶

Deletes this review.

This will enforce that all contained comments are also deleted.

get_all_comments(**kwargs)[source]¶: Return a list of all contained comments of all types.

has_comments(only_issues=False)[source]¶

Return whether the review contains any comments/issues.

Parameters: only_issues (bool, optional) – Whether or not to check for comments where issue_opened is True. True to check for issues, or False to check for comments only. Defaults to False.
Returns: True if the review contains any comments/issues and False otherwise.
Return type: bool

class ReviewRequest(*args, **kwargs)[source]¶

A review request.

This is one of the primary models in Review Board. Most everything is associated with a review request.

The ReviewRequest model contains detailed information on a review request. Some fields are user-modifiable, while some are used for internal state.

static status_to_string(status)[source]¶

Return a string representation of a review request status.

Parameters: status (unicode) – A single-character string representing the status.
Returns: A longer string representation of the status suitable for use in the API.
Return type: unicode

static string_to_status(status)[source]¶

Return a review request status from an API string.

Parameters: status (unicode) – A string from the API representing the status.
Returns: A single-character string representing the status, suitable for storage in the status field.
Return type: unicode

property approved[source]¶

Returns whether or not a review request is approved by reviewers.

On a default installation, a review request is approved if it has at least one Ship It!, and doesn’t have any open issues.

Extensions may customize approval by providing their own ReviewRequestApprovalHook.

property approval_failure[source]¶

Returns the error indicating why a review request isn’t approved.

If approved is False, this will provide the text describing why it wasn’t approved.

Extensions may customize approval by providing their own ReviewRequestApprovalHook.

property owner[source]¶

The owner of a review request.

This is an alias for submitter. It provides compatibilty with ReviewRequestDraft.owner, for functions working with either method, and for review request fields, but it cannot be used for queries.

property created_with_history[source]¶

Whether or not this review request was created with commit support.

This property can only be changed before the review request is created (i.e., before save() is called and it has a primary key assigned).

property review_participants[source]¶

Return the participants in reviews on the review request.

This will contain the users who published any reviews or replies on the review request. The list will be in username sort order and will not contain duplicates.

This will only contain the owner of the review request if they’ve filed a review or reply.

Returns: The users who filed reviews or replies.
Return type: set of django.contrib.auth.models.User

get_new_reviews(user)[source]¶

Returns all new reviews since last viewing this review request.

This will factor in the time the user last visited the review request, and find any reviews that have been added or updated since.

get_display_id()[source]¶: Returns the ID that should be exposed to the user.

property display_id[source]¶: Returns the ID that should be exposed to the user.

get_public_reviews()[source]¶: Returns all public top-level reviews for this review request.

is_accessible_by(user, local_site=None, request=None, silent=False)[source]¶

Returns whether or not the user can read this review request.

This performs several checks to ensure that the user has access. This user has access if:

The review request is public or the user can modify it (either by being an owner or having special permissions).
The repository is public or the user has access to it (either by being explicitly on the allowed users list, or by being a member of a review group on that list).
The user is listed as a requested reviewer or the user has access to one or more groups listed as requested reviewers (either by being a member of an invite-only group, or the group being public).

is_mutable_by(user)[source]¶

Return whether the user can modify this review request.

Parameters: user (django.contrib.auth.models.User) – The user to check.
Returns: Whether the user can modify this review request.
Return type: bool

is_status_mutable_by(user)[source]¶

Return whether the user can modify this review request’s status.

Parameters: user (django.contrib.auth.models.User) – The user to check.
Returns: Whether the user can modify this review request’s status.
Return type: bool

is_deletable_by(user)[source]¶

Return whether the user can delete this review request.

Parameters: user (django.contrib.auth.models.User) – The user to check.
Returns: Whether the user can delete this review request.
Return type: bool

get_draft(user=None)[source]¶

Returns the draft of the review request.

If a user is specified, than the draft will be returned only if owned by the user. Otherwise, None will be returned.

get_pending_review(user)[source]¶

Returns the pending review owned by the specified user, if any.

This will return an actual review, not a reply to a review.

get_last_activity_info(diffsets=None, reviews=None)[source]¶

Return the last public activity information on the review request.

Parameters

diffsets (list of reviewboard.diffviewer.models.DiffSet, optional) –
The list of diffsets to compare for latest activity.

If not provided, this will be populated with the last diffset.
reviews (list of reviewboard.reviews.models.Review, optional) –
The list of reviews to compare for latest activity.

If not provided, this will be populated with the latest review.

Returns

A dictionary with the following keys:

timestamp:

The datetime that the object was updated.

updated_object:

The object that was updated. This will be one of the following:

The ReviewRequest itself.
A Review.
A DiffSet.

changedesc:

The latest ChangeDescription, if any.

Return type

dict

changeset_is_pending(commit_id)[source]¶

Returns whether the associated changeset is pending commit.

For repositories that support it, this will return whether the associated changeset is pending commit. This requires server-side knowledge of the change.

get_diffsets()[source]¶

Returns a list of all diffsets on this review request.

This will also fetch all associated FileDiffs, as well as a count of the number of files (stored in DiffSet.file_count).

get_latest_diffset()[source]¶: Returns the latest diffset for this review request.

get_close_info()[source]¶

Return metadata of the most recent closing of a review request.

This is a helper which is used to gather the data which is rendered in the close description boxes on various pages.

Returns

A dictionary with the following keys:

'close_description' (unicode):: Description of review request upon closing.
'is_rich_text' (bool):: Boolean whether description is rich text.
'timestamp' (datetime.datetime):: Time of review requests last closing.

Return type

dict

get_blocks()[source]¶

Returns the list of review request this one blocks.

The returned value will be cached for future lookups.

save(update_counts=False, old_submitter=None, **kwargs)[source]¶

Saves the current instance. Override this in a subclass if you want to control the saving process.

can_add_default_reviewers()[source]¶

Return whether default reviewers can be added to the review request.

Default reviewers can only be added if the review request supports repositories and doesn’t yet have any published diffs.

Returns: True if new default reviewers can be added. False if they cannot.
Return type: bool

close(close_type=None, user=None, description=None, rich_text=False, **kwargs)[source]¶

Closes the review request.

Parameters

close_type (unicode) – How the close occurs. This should be one of SUBMITTED or DISCARDED.
user (django.contrib.auth.models.User) – The user who is closing the review request.
description (unicode) – An optional description that indicates why the review request was closed.
rich_text (bool) – Indicates whether or not that the description is rich text.

Raises

ValueError – The provided close type is not a valid value.
PermissionError – The user does not have permission to close the review request.
TypeError – Keyword arguments were supplied to the function.

Changed in version 3.0: The type argument is deprecated: close_type should be used instead.

This method raises ValueError instead of AttributeError when the close_type has an incorrect value.

reopen(user=None)[source]¶: Reopens the review request for review.

publish(user, trivial=False, validate_fields=True)[source]¶

Publishes the current draft attached to this review request.

The review request will be mark as public, and signals will be emitted for any listeners.

determine_user_for_changedesc(changedesc)[source]¶

Determine the user associated with the change description.

Parameters: changedesc (reviewboard.changedescs.models.ChangeDescription) – The change description.
Returns: The user associated with the change description.
Return type: django.contrib.auth.models.User

get_review_request()[source]¶

Returns this review request.

This is provided so that consumers can be passed either a ReviewRequest or a ReviewRequestDraft and retrieve the actual ReviewRequest regardless of the object.

class ReviewRequestDraft(*args, **kwargs)[source]¶

A draft of a review request.

When a review request is being modified, a special draft copy of it is created containing all the details of the review request. This copy can be modified and eventually saved or discarded. When saved, the new details are copied back over to the originating ReviewRequest.

get_latest_diffset()[source]¶: Returns the diffset for this draft.

is_accessible_by(user)[source]¶: Returns whether or not the user can access this draft.

is_mutable_by(user)[source]¶: Returns whether or not the user can modify this draft.

static create(review_request, changedesc=None)[source]¶

Create a draft based on a review request.

This will copy over all the details of the review request that we care about. If a draft already exists for the review request, the draft will be returned.

Parameters

review_request (reviewboard.reviews.models.review_request.ReviewRequest) – The review request to fetch or create the draft from.
changedesc (reviewboard.changedescs.models.ChangeDescription) – A custom change description to set on the draft. This will always be set, overriding any previous one if already set.

Returns

The resulting draft.

Return type

ReviewRequestDraft

publish(review_request=None, user=None, trivial=False, send_notification=True, validate_fields=True, timestamp=None)[source]¶

Publish this draft.

This is an internal method. Programmatic publishes should use reviewboard.reviews.models.review_request.ReviewRequest.publish() instead.

This updates and returns the draft’s ChangeDescription, which contains the changed fields. This is used by the e-mail template to tell people what’s new and interesting.

The keys that may be saved in fields_changed in the ChangeDescription are:

submitter
summary
description
testing_done
bugs_closed
depends_on
branch
target_groups
target_people
screenshots
screenshot_captions
diff
Any custom field IDs

Each field in ‘fields_changed’ represents a changed field. This will save fields in the standard formats as defined by the ‘ChangeDescription’ documentation, with the exception of the ‘screenshot_captions’ and ‘diff’ fields.

For the ‘screenshot_captions’ field, the value will be a dictionary of screenshot ID/dict pairs with the following fields:

old: The old value of the field
new: The new value of the field

For the diff field, there is only ever an added field, containing the ID of the new diffset.

Parameters

review_request (reviewboard.reviews.models.review_request.ReviewRequest, optional) – The review request associated with this diff. If not provided, it will be looked up.
user (django.contrib.auth.models.User, optional) – The user publishing the draft. If not provided, this defaults to the review request submitter.
trivial (bool, optional) –
Whether or not this is a trivial publish.

Trivial publishes do not result in e-mail notifications.
send_notification (bool, optional) –
Whether or not this will emit the reviewboard.reviews.signals.review_request_published signal.

This parameter is intended for internal use only.
validate_fields (bool, optional) –
Whether or not the fields should be validated.

This should only be False in the case of programmatic publishes, e.g., from close as submitted hooks.
timestamp (datetime.datetime, optional) – The datetime that should be used for all timestamps for objects published (DiffSet, ChangeDescription) over the course of the method.

Returns

The change description that results from this publish (if any).

If this is an initial publish, there will be no change description (and this function will return None).

Return type

reviewboard.changedescs.models.ChangeDescription

update_from_commit_id(commit_id)[source]¶

Update the data from a server-side changeset.

If the commit ID refers to a pending changeset on an SCM which stores such things server-side (like Perforce), the details like the summary and description will be updated with the latest information.

If the change number is the commit ID of a change which exists on the server, the summary and description will be set from the commit’s message, and the diff will be fetched from the SCM.

Parameters

commit_id (unicode) – The commit ID or changeset ID that the draft will update from.

Returns

The list of draft fields that have been updated from the commit.

Return type

list of unicode

Raises

reviewboard.hostingsvcs.errors.HostingServiceError – The hosting service backing the repository encountered an error.
reviewboard.scmtools.errors.InvalidChangeNumberError – The commit ID could not be found in the repository.
reviewboard.scmtools.errors.SCMError – The repository tool encountered an error.
NotImplementedError – The repository does not support fetching information from commit IDs.

update_from_pending_change(commit_id, changeset)[source]¶

Update the data from a server-side pending changeset.

This will fetch the metadata from the server and update the fields on the draft.

Parameters

commit_id (unicode) – The changeset ID that the draft will update from.
changeset (reviewboard.scmtools.core.ChangeSet) – The changeset information to update from.

Returns

The list of draft fields that have been updated from the change.

Return type

list of unicode

update_from_committed_change(commit_id)[source]¶

Update from a committed change present on the server.

Fetches the commit message and diff from the repository and sets the relevant fields.

Parameters: commit_id (unicode) – The commit ID to update from.
Returns: The list of draft fields that have been updated from the commit message.
Return type: list of unicode

copy_fields_to_request(review_request)[source]¶: Copies the draft information to the review request and updates the draft’s change description.

get_review_request()[source]¶: Returns the associated review request.

class Screenshot(*args, **kwargs)[source]¶

A screenshot associated with a review request.

Like diffs, a screenshot can have comments associated with it. These comments are of type reviewboard.reviews.models.ScreenshotComment.

property filename[source]¶: Returns the filename for display purposes.

get_comments()[source]¶: Returns all the comments made on this screenshot.

get_thumbnail_url()[source]¶: Returns the URL for the thumbnail, creating it if necessary.

thumb()[source]¶: Creates and returns HTML for this screenshot’s thumbnail.

save(**kwargs)[source]¶

Saves the current instance. Override this in a subclass if you want to control the saving process.

class ScreenshotComment(*args, **kwargs)[source]¶

A comment on a screenshot.

get_image_url()[source]¶: Returns the URL for the thumbnail, creating it if necessary.

image()[source]¶

Returns HTML for a section of the screenshot for this comment.

This will generate the cropped part of the screenshot referenced by this comment and returns the HTML markup embedding it.

class StatusUpdate(*args, **kwargs)[source]¶

A status update from a third-party service or extension.

This status model allows external services (such as continuous integration services, Review Bot, etc.) to provide an update on their status. An example of this would be a CI tool which does experimental builds of changes. While the build is running, that tool would set its status to pending, and when it was done, would set it to one of the done states, and potentially associate it with a review containing issues.

PENDING = 'P'[source]¶: The pending state.

DONE_SUCCESS = 'S'[source]¶: The completed successfully state.

DONE_FAILURE = 'F'[source]¶: The completed with reported failures state.

ERROR = 'E'[source]¶: The error state.

TIMEOUT = 'T'[source]¶: Timeout state.

NOT_YET_RUN = 'R'[source]¶: Not yet run state.

service_id[source]¶

An identifier for the service posting this status update.

This ID is self-assigned, and just needs to be unique to that service. Possible values can be an extension ID, webhook URL, or a script name.

user[source]¶: The user who created this status update.

timestamp[source]¶: The timestamp of the status update.

summary[source]¶

A user-visible short summary of the status update.

This is typically the name of the integration or tool that was run.

description[source]¶

A user-visible description on the status update.

This is shown in the UI adjacent to the summary. Typical results might be things like “running.” or “failed.”. This should include punctuation.

url[source]¶

An optional link.

This is used in case the tool has some external page, such as a build results page on a CI system.

url_text[source]¶: Text for the link. If url is empty, this will not be used.

state[source]¶

The current state of this status update.

This should be set to PENDING while the service is processing the update, and then to either DONE_SUCCESS or DONE_FAILURE once complete. If the service encountered some error which prevented completion, this should be set to ERROR.

review_request[source]¶: The review request that this status update is for.

change_description[source]¶

The change to the review request that this status update is for.

If this is None, this status update refers to the review request as a whole (for example, the initial diff that was posted).

review[source]¶

An optional review created for this status update.

This allows the third-party service to create comments and open issues.

extra_data[source]¶: Any extra data that the service wants to store for this status update.

timeout[source]¶: An (optional) timeout, in seconds. If this is non-None and the state has been PENDING for longer than this period (computed from the timestamp field), effective_state will be TIMEOUT.

static state_to_string(state)[source]¶

Return a string representation of a status update state.

Parameters: state (unicode) – A single-character string representing the state.
Returns: A longer string representation of the state suitable for use in the API.
Return type: unicode

static string_to_state(state)[source]¶

Return a status update state from an API string.

Parameters: state (unicode) – A string from the API representing the state.
Returns: A single-character string representing the state, suitable for storage in the state field.
Return type: unicode

is_mutable_by(user)[source]¶

Return whether the user can modify this status update.

Parameters: user (django.contrib.auth.models.User) – The user to check.
Returns: True if the user can modify this status update.
Return type: bool

property effective_state[source]¶: The state of the status update, taking into account timeouts.

drop_open_issues()[source]¶: Drop any open issues associated with this status update.

property can_run[source]¶

Whether or not the checker associated can be run.

Type:: bool

property action_name[source]¶

The name of the action to use for running or re-running the check.

Type:: unicode

run()[source]¶: Run the tool associated with this StatusUpdate.

Review Board Manual

reviewboard.reviews.models¶