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
- get_review_request()[source]¶
Return this comment’s review request.
- Returns
The review request that this comment was made on.
- Return type
- get_review()[source]¶
Return this comment’s review.
- Returns
The review containing this comment.
- Return type
- 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
- 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
- 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
- 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
- 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
- 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.
- 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_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).
- 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!” andFalse
otherwise.- Return type
- 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
- 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 toSHIP_IT_TEXT
, then it will replaced withREVOKED_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_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
- 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
- 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.
- 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
isFalse
, 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 withReviewRequestDraft.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.
- 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
- 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
- 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
- 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
- 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_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
- 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.
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.
- 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
- 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
orDISCARDED
.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 ofAttributeError
when theclose_type
has an incorrect value.
- 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
- 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.
- 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
- 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 fieldnew
: The new value of the field
For the
diff
field, there is only ever anadded
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
- 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
- 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
.- 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.
- 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.
- 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.
- 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.
- 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 eitherDONE_SUCCESS
orDONE_FAILURE
once complete. If the service encountered some error which prevented completion, this should be set toERROR
.
- 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.
- 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 thetimestamp
field),effective_state
will beTIMEOUT
.
- 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