rbtools.utils.review_request¶

Utilities for matching review requests.

Functions

rbtools.utils.review_request.get_draft_or_current_value(field_name, review_request)[source]¶

Returns the draft or current field value from a review request.

If a draft exists for the supplied review request, return the draft’s field value for the supplied field name, otherwise return the review request’s field value for the supplied field name.

rbtools.utils.review_request.get_possible_matches(review_requests, summary, description, limit=5)[source]¶

Return a sorted list of tuples of score and review request.

Each review request is given a score based on the summary and description provided. The result is a sorted list of tuples containing the score and the corresponding review request, sorted by the highest scoring review request first.

Deprecated since version 3.1: This will be removed in RBTools 4.0.

Parameters:

• review_requests (list of rbtools.api.resource.ReviewRequestResource) – The list of review requests to match against.

• summary (unicode) – The summary to match.

• description (unicode) – The description to match.

• limit (int, optional) – The maximum number of results to return.

Returns:

A list of matches. Each match is a 2-tuple in the form of:

1. The match score (rbtools.utils.match_score.Score)

2. The review request (rbtools.api.resource.ReviewRequestResource)

Return type:

list of tuple

rbtools.utils.review_request.get_revisions(tool, cmd_args)[source]¶

Returns the parsed revisions from the command line arguments.

These revisions are used for diff generation and commit message extraction. They will be cached for future calls.

rbtools.utils.review_request.get_pending_review_requests(api_root, username, repository_id=None, additional_fields=None)[source]¶

Return pending review requests for a user.

Each review request will contain a pre-fetched list of fields:

• absolute_url

• bugs_closed

• commit_id

• description

• draft

• extra_data

• id

• public

• status

• summary

• url

If needed, additional fields can be requested by passing in additional_fields.

This requires a valid existing login session.

New in version 3.1.

Parameters:

• api_root (rbtools.api.resource.RootResource) – The root resource of the Review Board server.

• username (unicode) –

  The username owning the review requests.

  The authenticated user will need to have access to this user’s pending review requests. For instance, it would need to be a superuser, a special user with the can_submit_as permission, or the user itself.

• repository_id (int, optional) –

  The repository ID that all matching review requests must be posted against.

  If not provided, only review requests not backed by a repository will be matched.

• additional_fields (list of unicode, optional) – Additional fields to fetch for the review request payload.

rbtools.utils.review_request.find_review_request_by_change_id(api_client, api_root, repository_info=None, repository_name=None, revisions=None, repository_id=None)[source]¶

Ask Review Board for the review request ID for the tip revision.

Note that this function calls the Review Board API with the only_fields parameter, thus the returned review request will contain only the fields specified by the only_fields variable.

If no review request is found, None will be returned instead.

Changed in version 3.0: The repository_info and repository_name arguments were deprecated in favor of adding the new repository_id argument.

Parameters:

• api_client (rbtools.api.client.RBClient) – The API client.

• api_root (rbtools.api.resource.RootResource) – The root resource of the Review Board server.

• repository_info (rbtools.clients.base.repository.RepositoryInfo, deprecated) – The repository info object.

• repository_name (unicode, deprecated) – The repository name.

• revisions (dict) – The parsed revision information, including the tip key.

• repository_id (int, optional) – The repository ID to use.

rbtools.utils.review_request.find_review_request_matches(review_requests, tool=None, revisions=None, commit_id=None, summary=None, description=None, max_review_requests=50)[source]¶

Find review requests that match the provided criteria.

This will iterate through a provided list of review request resources, comparing the contained information against the provided criteria in order to generate matches.

There are two possible types of results: An exact match, or a list of fuzzy matches.

If only one exact match is found, it will be in the results, and any fuzzy matches will be discarded.

If more than one exact match is found, they’ll be converted to fuzzy matches, with higher precedence than any actual fuzzy matches.

If an exact match is not found, a list of fuzzy matches will be provided, each with a score (a floating point number between 0.0 and 1.0) indicating how close it matched the criteria.

The following criteria is checked for a match:

1. Matching commit_id.

   This would be considered an exact match.

2. Matching SCMClient-specific extra_data.

   A BaseSCMClient can provide its own matching logic, comparing state stored on a review request with information from the local clone/checkout. The result may be an exact match or a fuzzy match.

3. Matching a summary/description, if provided.

   The provided summary/description will be compared against the review request. If the strings are both equal, then this will be an exact match. Otherwise, it’s a fuzzy match.

New in version 3.1.

Parameters:

• review_requests (list or rbtools.api.resource.ListResource) –

  Either a list resource for review requests (in which case all pages will be searched for matches), or a list of rbtools.api.resource.ReviewRequestResource instances.

  Note

  It’s expected that these will all be backed by the same repository. Otherwise, commit ID matching will not be reliable. This is the responsibility of the caller.

• tool (rbtools.clients.base.BaseSCMClient, optional) – An optional client tool used to perform tool-specific matches.

• revisions (dict, optional) – The parsed revisions from the tool.

• summary (unicode, optional) – An optional summary to match against.

• description (unicode, optional) – An optional description to match against.

• max_review_requests (int, optional) – The maximum number of review requests to check. This avoids iterating through too many pages of review requests on the server.

Returns:

A dictionary of results, containing:

Keys:

• exact (rbtools.api.resource.ReviewRequestResource) – An exact review request match. This may be None.

• fuzzy (list of dict) – A list of fuzzy matches. Each contains:

  Keys:

  • review_request (rbtools.api.resource.ReviewRequestResource) – The review request match candidate.

  • score (float) – The match score (between 0.0 and 1.0), indicating the confidence of the match.

Return type:

dict

rbtools.utils.review_request.guess_existing_review_request(repository_info=None, repository_name=None, api_root=None, api_client=None, tool=None, revisions=None, guess_summary=False, guess_description=False, is_fuzzy_match_func=None, no_commit_error=None, submit_as=None, additional_fields=None, repository_id=None, commit_id=None)[source]¶

Try to guess the existing review request ID if it is available.

The existing review request is guessed by comparing the existing summary and description to the current post’s summary and description, respectively. The current post’s summary and description are guessed if they are not provided.

If the summary and description exactly match those of an existing review request, that request is immediately returned. Otherwise, the user is prompted to select from a list of potential matches, sorted by the highest ranked match first.

Note that this function calls the ReviewBoard API with the only_fields paramater, thus the returned review request will contain only the fields specified by the only_fields variable.

Changed in version 3.1:

• Added the commit_id argument.

• The guess_summary and guess_description arguments are deprecated and will be removed in RBTools 4.0.

• submit_as should now be provided, and will be required in RBTools 4.0.

Changed in version 3.0: The repository_info and repository_name arguments were deprecated in favor of adding the new repository_id argument.

Parameters:

• repository_info (rbtools.clients.base.repository.RepositoryInfo, deprecated) –

  The repository info object.

  Deprecated since version 3.0: repository_id must be provided instead.

• repository_name (unicode, deprecated) –

  The repository name.

  Deprecated since version 3.0: repository_id must be provided instead.

• api_root (rbtools.api.resource.RootResource) – The root resource of the Review Board server.

• api_client (rbtools.api.client.RBClient) – The API client.

• tool (rbtools.clients.base.BaseSCMClient) – The SCM client.

• revisions (dict) – The parsed revisions object.

• guess_summary (bool) –

  Whether to attempt to guess the summary for comparison.

  Deprecated since version 3.1: In future versions, summaries will automatically be queried from the SCMClient and matched. Internally, this has been the default behavior regardless of settings for many years.

  This will be removed in RBTools 4.0.

• guess_description (bool) –

  Whether to attempt to guess the description for comparison.

  Deprecated::

  3.1: In future versions, summaries will automatically be queried from the SCMClient and matched. Internally, this has been the default behavior regardless of settings for many years.

  This will be removed in RBTools 4.0.

• is_fuzzy_match_func (callable, optional) – A function which can check if a review request is a match for the data being posted.

• no_commit_error (callable, optional) – A function to be called when there’s no local commit.

• submit_as (unicode, optional) –

  A username on the server which is used for posting review requests. If provided, review requests owned by this user will be matched.

  Changed in version 3.1: This will be required in RBTools 4.0.

• additional_fields (list of unicode, optional) – A list of additional fields to include in the fetched review request resource.

• repository_id (int, optional) – The ID of the repository to match.

• commit_id (unicode, optional) –

  The ID of the commit to match.

  New in version 3.1.

Returns:

The resulting review request, if a match was made, or None if no review request could be matched.

Return type:

rbtools.api.resource.ReviewRequestResource

Raises:

• rbtools.utils.errors.MatchReviewRequestError – Error fetching the user session or review requests from the API. This will replace the ValueError exception for API issues in RBTools 4.0.

• ValueError – Error fetching review requests from the API.

rbtools.utils.review_request.num_exact_matches(possible_matches)[source]¶

Return the number of exact matches in the possible match list.

Deprecated since version 3.1: This will be removed in RBTools 4.0.

Parameters:

possible_matches (list of tuple) – The list of possible matches from get_possible_matches().

Returns:

The number of exact matches found.

Return type:

int

rbtools.utils.review_request.parse_review_request_url(url)[source]¶

Parse a review request URL and return its component parts.

Parameters:

url (unicode) – The URL to parse.

Returns:

A 3-tuple consisting of the server URL, the review request ID, and the diff revision.

Return type:

tuple