reviewboard.testing.scmtool¶

class TestTool(repository)[source]¶

Bases: GitTool

scmtool_id: str = 'test'[source]¶

A unique identifier for the SCMTool.

If not provided, this will be based on its key in the reviewboard.scmtools Python EntryPoint. This will become a required attribute in a future version.

New in version 3.0.16.

name: Optional[str] = 'Test'[source]¶

The human-readable name of the SCMTool.

Users will see this when they go to select a repository type. Some examples would be “Subversion” or “Perforce”.

diffs_use_absolute_paths: bool = False[source]¶

Whether filenames in diffs are stored using absolute paths.

This is used when uploading and validating diffs to determine if the user must supply the base path for a diff. Some types of SCMs (such as Subversion) store relative paths in diffs, requiring additional information in order to generate an absolute path for lookups.

By default, this is False. Subclasses must override this if their diff formats list absolute paths.

supports_post_commit: bool = True[source]¶

Whether existing commits can be browsed and posted for review.

If True, the New Review Request page and API will allow for browsing and posting existing commits and their diffs for review.

supports_history: bool = False[source]¶

Whether or not the SCMTool supports review requests with history.

get_repository_info()[source]¶

Return information on the repository.

The information will vary based on the repository. This data will be used in the API, and may be used by clients to better locate or match particular repositories.

It is recommended that it contain a uuid field containing a unique identifier for the repository, if available.

This is optional, and does not need to be implemented by subclasses.

Returns:

A dictionary containing information on the repository.

Return type:

dict

Raises:

NotImplementedError – Repository information retrieval is not implemented by this type of repository. Callers should specifically check for this, as it’s considered a valid result.

get_branches()[source]¶

Return a list of all branches on the repository.

This will fetch a list of all known branches for use in the API and New Review Request page.

Subclasses that override this must be sure to always return one (and only one) Branch result with default set to True.

Callers should check supports_post_commit before calling this.

Returns:

The list of branches in the repository. One (and only one) will be marked as the default branch.

Return type:

list of Branch

Raises:

• reviewboard.scmtools.errors.SCMError – The repository tool encountered an error.

• NotImplementedError – Branch retrieval is not available for this type of repository.

get_commits(branch=None, start=None)[source]¶

Return a list of commits backward in history from a given point.

This will fetch a batch of commits from the repository for use in the API and New Review Request page.

The resulting commits will be in order from newest to oldest, and should return upwards of a fixed number of commits (usually 30, but this depends on the type of repository and its limitations). It may also be limited to commits that exist on a given branch (if supported by the repository).

This can be called multiple times in succession using the Commit.parent of the last entry as the start parameter in order to paginate through the history of commits in the repository.

Callers should check supports_post_commit before calling this.

Parameters:

• branch (str, optional) – The branch to limit commits to. This may not be supported by all repositories.

• start (str, optional) – The commit to start at. If not provided, this will fetch the first commit in the repository.

Returns:

The list of commits, in order from newest to oldest.

Return type:

list of Commit

Raises:

• reviewboard.scmtools.errors.SCMError – The repository tool encountered an error.

• NotImplementedError – Commits retrieval is not available for this type of repository.

get_change(commit_id)[source]¶

Return an individual change/commit with the given revision.

This will fetch information on the given commit, if found, including its commit message and list of modified files.

Callers should check supports_post_commit before calling this.

Parameters:

revision (str) – The revision/ID of the commit.

Returns:

The resulting commit with the given revision/ID.

Return type:

Commit

Raises:

• reviewboard.scmtools.errors.SCMError – Error retrieving information on this commit.

• NotImplementedError – Commit retrieval is not available for this type of repository.

get_file(path, revision, **kwargs)[source]¶

Return a file from the repository.

This testing tool allows for special paths that allow callers to optionally define the data to return and the encoding to use for that data.

If the path starts with /data:, then what comes after will be returned as data (with a newline appended to the data). Otherwise, a standard Hello, world!\n will be returned.

If the path ends with ;encoding=..., then whatever is returned will be encoded in the specified encoding type.

If the path starts with bad:file-not-found, then this will simulate a reviewboard.scmtools.errors.FileNotFoundError.

If the path starts with bad:scm-error, then this will simulate a reviewboard.scmtools.errors.SCMError.

Changed in version 4.0.7: Added support for special bad:file-not-found and bad:scm-error paths.

Parameters:

• path (unicode) – The path to retrieve, optionally with custom data and an encoding.

• revision (unicode, unused) – The revision to retrieve. This is ignored.

• **kwargs (dict, unused) – Additional keyword arguments for the request.

Returns:

The resulting file contents.

Return type:

bytes

Raises:

• reviewboard.scmtools.errors.FileNotFoundError – The path started with bad:file-not-found.

• reviewboard.scmtools.errors.SCMError – The path started with bad:scm-error.

file_exists(path, revision, **kwargs)[source]¶

Return whether a particular file exists in a repository.

Like get_file(), this may take a base commit ID, which is the ID (SHA or revision number) of a commit changing or introducing the file. This depends on the type of repository, and may not be provided.

Subclasses should only override this if they have a more efficient way of checking for a file’s existence than fetching the file contents.

Changed in version 4.0.5: Added context, which deprecates base_commit_id and adds new capabilities for file lookups.

Parameters:

• path (str) – The path to the file in the repository.

• revision (Revision, optional) – The revision to fetch. Subclasses should default this to HEAD.

• base_commit_id (str, optional) –

  The ID of the commit that the file was changed in. This may not be provided, and is dependent on the type of repository.

  Deprecated since version 4.0.5: This will still be provided, but implementations should use FileLookupContext.base_commit_id` instead when running on Review Board 4.0.5+.

• context (FileLookupContext, optional) –

  Extra context used to help look up this file.

  This contains information about the HTTP request, requesting user, and parsed diff information, which may be useful as part of the repository lookup process.

  This is always provided on Review Board 4.0.5 and higher. Implementations should be careful to validate the presence and values of any metadata stored within this.

  New in version 4.0.5.

• **kwargs (dict) – Additional keyword arguments. This is not currently used, but is available for future expansion.

Returns:

True if the file exists in the repository. False if it does not (or the parameters supplied were invalid).

Return type:

bool

classmethod check_repository(path, *args, **kwargs)[source]¶

Check a repository configuration for validity.

This should check if a repository exists and can be connected to. This will also check if the repository requires an HTTPS certificate.

A failed result is returned as an exception. The exception may contain extra information, such as a human-readable description of the problem. If the repository is valid and can be connected to, no exception will be thrown.

Parameters:

• path (unicode) – The repository path.

• username (unicode, optional) – The optional username for the repository.

• password (unicode, optional) – The optional password for the repository.

• local_site_name (unicode, optional) – The name of the Local Site that owns this repository. This is optional.

• **kwargs (dict, unused) – Additional settings for the repository.

Raises:

• reviewboard.scmtools.errors.AuthenticationError – The provided username/password or the configured SSH key could not be used to authenticate with the repository.

• reviewboard.scmtools.errors.RepositoryNotFoundError – A repository could not be found at the given path.

• reviewboard.scmtools.errors.SCMError – There was a generic error with the repository or its configuration. Details will be provided in the error message.

• reviewboard.ssh.errors.BadHostKeyError – An SSH path was provided, but the host key for the repository did not match the expected key.

• reviewboard.ssh.errors.SSHError – An SSH path was provided, but there was an error establishing the SSH connection.

• reviewboard.ssh.errors.SSHInvalidPortError – An SSH path was provided, but the port specified was not a valid number.

• Exception – An unexpected exception has ocurred. Callers should check for this and handle it.

__annotations__ = {'auth_form': 'Optional[Type[BaseSCMToolAuthForm]]', 'class_name': 'ClassVar[Optional[str]]', 'commits_have_committer': 'bool', 'dependencies': 'Dict[str, List[str]]', 'diffs_use_absolute_paths': 'bool', 'diffs_use_commit_ids_as_revisions': 'bool', 'field_help_text': 'Dict[str, _StrOrPromise]', 'lookup_name': 'ClassVar[Optional[str]]', 'name': 'Optional[str]', 'prefers_mirror_path': 'bool', 'repository': 'Repository', 'repository_form': 'Optional[Type[BaseSCMToolRepositoryForm]]', 'scmtool_id': 'str', 'supports_history': 'bool', 'supports_pending_changesets': 'bool', 'supports_post_commit': 'bool', 'supports_raw_file_urls': 'bool', 'supports_ticket_auth': 'bool'}¶

class TestToolSupportsPendingChangeSets(repository)[source]¶

Bases: TestTool

scmtool_id: str = 'test-supports-pending-changesets'[source]¶

A unique identifier for the SCMTool.

If not provided, this will be based on its key in the reviewboard.scmtools Python EntryPoint. This will become a required attribute in a future version.

New in version 3.0.16.

name: Optional[str] = 'TestToolSupportsPendingChangeSets'[source]¶

The human-readable name of the SCMTool.

Users will see this when they go to select a repository type. Some examples would be “Subversion” or “Perforce”.

supports_pending_changesets: bool = True[source]¶

Whether server-side pending changesets are supported.

These are used by some types of repositories to track what changes are currently open by what developer, what files they touch, and what the commit message is. Basically, they work like server-side drafts for commits.

If True, Review Board will allow updating the review request’s information from the pending changeset, and will indicate in the UI if it’s pending or submitted.

get_changeset(changesetid, allow_empty=False)[source]¶

Return information on a server-side changeset with the given ID.

This only needs to be implemented if supports_pending_changesets is True.

Parameters:

• changesetid (str) – The server-side changeset ID.

• allow_empty (bool, optional) –

  Whether or not an empty changeset (one containing no modified files) can be returned.

  If True, the changeset will be returned with whatever data could be provided. If False, a reviewboard.scmtools.errors.EmptyChangeSetError will be raised.

  Defaults to False.

Returns:

The resulting changeset containing information on the commit and modified files.

Return type:

ChangeSet

Raises:

• NotImplementedError – Changeset retrieval is not available for this type of repository.

• reviewboard.scmtools.errors.EmptyChangeSetError – The resulting changeset contained no file modifications (and allow_empty was False).

__annotations__ = {'auth_form': 'Optional[Type[BaseSCMToolAuthForm]]', 'class_name': 'ClassVar[Optional[str]]', 'commits_have_committer': 'bool', 'dependencies': 'Dict[str, List[str]]', 'diffs_use_absolute_paths': 'bool', 'diffs_use_commit_ids_as_revisions': 'bool', 'field_help_text': 'Dict[str, _StrOrPromise]', 'lookup_name': 'ClassVar[Optional[str]]', 'name': 'Optional[str]', 'prefers_mirror_path': 'bool', 'repository': 'Repository', 'repository_form': 'Optional[Type[BaseSCMToolRepositoryForm]]', 'scmtool_id': 'str', 'supports_history': 'bool', 'supports_pending_changesets': 'bool', 'supports_post_commit': 'bool', 'supports_raw_file_urls': 'bool', 'supports_ticket_auth': 'bool'}¶

class TestToolDiffX(repository)[source]¶

Bases: TestTool

SCMTool that uses DiffX diffs.

New in version 4.0.6.

scmtool_id: str = 'test-diffx'[source]¶

A unique identifier for the SCMTool.

If not provided, this will be based on its key in the reviewboard.scmtools Python EntryPoint. This will become a required attribute in a future version.

New in version 3.0.16.

name: Optional[str] = 'TestToolDiffX'[source]¶

The human-readable name of the SCMTool.

Users will see this when they go to select a repository type. Some examples would be “Subversion” or “Perforce”.

get_parser(data)[source]¶

Return a diff parser used to parse diff data.

Parameters:

data (bytes) – The diff data to parse.

Returns:

The diff parser used to parse this data.

Return type:

reviewboard.diffviewer.diffparser.DiffXParser

__annotations__ = {'auth_form': 'Optional[Type[BaseSCMToolAuthForm]]', 'class_name': 'ClassVar[Optional[str]]', 'commits_have_committer': 'bool', 'dependencies': 'Dict[str, List[str]]', 'diffs_use_absolute_paths': 'bool', 'diffs_use_commit_ids_as_revisions': 'bool', 'field_help_text': 'Dict[str, _StrOrPromise]', 'lookup_name': 'ClassVar[Optional[str]]', 'name': 'Optional[str]', 'prefers_mirror_path': 'bool', 'repository': 'Repository', 'repository_form': 'Optional[Type[BaseSCMToolRepositoryForm]]', 'scmtool_id': 'str', 'supports_history': 'bool', 'supports_pending_changesets': 'bool', 'supports_post_commit': 'bool', 'supports_raw_file_urls': 'bool', 'supports_ticket_auth': 'bool'}¶