Jump to >

reviewboard.scmtools.core

Data structures and classes for defining and using SCMTools.

class ChangeSet[source]

Bases: object

A server-side changeset.

This represents information on a server-side changeset, which tracks the information on a commit and modified files for some types of repositories (such as Perforce).

Not all data may be provided by the server.

changenum

unicode – The changeset number/ID.

summary

unicode – The summary of the change.

description

unicode – The description of the change.

testing_done

unicode – Testing information for the change.

branch

unicode – The destination branch.

bugs_closed

list of unicode – A list of bug IDs that were closed by this change.

files

list of unicode – A list of filenames added/modified/deleted by the change.

username

unicode – The username of the user who made the change.

pending

bool – Whether or not the change is pending (not yet committed).

__init__()[source]

Initialize the changeset.

class Revision(name)[source]

Bases: object

A revision in a diff or repository.

This represents a specific revision in a tree, or a specialized indicator that can have special meaning.

name

unicode – The name/ID of the revision.

__init__(name)[source]

Initialize the Revision.

Parameters:name (unicode) – The name of the revision. This may be a special name (which should be in all-uppercase) or a revision ID.
__str__()[source]
__eq__(other)[source]

Return whether this revision equals another.

Parameters:other (Revision) – The revision to compare to.
Returns:True if the two revisions are equal. False if they are not equal.
Return type:bool
__ne__(other)[source]

Return whether this revision is not equal to another.

Parameters:other (Revision) – The revision to compare to.
Returns:True if the two revisions are not equal. False if they are equal.
Return type:bool
__repr__()[source]

Return a string representation of this revision.

Returns:The string representation.
Return type:unicode
__unicode__()[source]

Return a string representation of the revision.

This is equivalent to fetching name.

Returns:The name/ID of the revision.
Return type:unicode
class Branch(id, name=None, commit=u'', default=False)[source]

Bases: object

A branch in a repository.

id

unicode – The ID of the branch.

name

unicode – The name of the branch.

commit

unicode – The latest commit ID on the branch.

default

bool – Whether or not this is the default branch for the repository.

One (and only one) branch in a list of returned branches should have this set to True.

__init__(id, name=None, commit=u'', default=False)[source]

Initialize the branch.

Parameters:
  • id (unicode) – The ID of the branch.
  • name (unicode, optional) – The name of the branch. If not specified, this will default to the ID.
  • commit (unicode, optional) – The latest commit ID on the branch.
  • default (bool, optional) – Whether or not this is the default branch for the repository.
__eq__(other)[source]

Return whether this branch is equal to another branch.

Parameters:other (Branch) – The branch to compare to.
Returns:True if the two branches are equal. False if they are not.
Return type:bool
__repr__()[source]

Return a string representation of this branch.

Returns:The string representation.
Return type:unicode
class Commit(author_name=u'', id=u'', date=u'', message=u'', parent=u'', diff=None, base_commit_id=None)[source]

Bases: object

A commit in a repository.

author_name

unicode – The name or username of the author who made the commit.

id

unicode – The ID of the commit. This should be its SHA/revision.

parent

unicode – The ID of the commit’s parent. This should be its SHA/revision. If this is the first commit, this should be None or an empty string.

date

unicode – The timestamp of the commit as a string in ISO 8601 format.

message

unicode – The commit message.

diff[source]

bytes – The contents of the commit’s diff. This may be None, depending on how the commit is fetched.

base_commit_id

unicode – Equivalent to parent.

This is equivalent to parent, but can be left unset.

Deprecated since version 2.5.7: This will be removed in the future. Callers should use parent instead.

__init__(author_name=u'', id=u'', date=u'', message=u'', parent=u'', diff=None, base_commit_id=None)[source]

Initialize the commit.

All arguments are optional, and can be set later.

Parameters:
  • author_name (unicode, optional) – The name of the author who made this commit. This should be the full name, if available, but can be the username or other identifier.
  • id (unicode, optional) – The ID of the commit. This should be its SHA/revision.
  • date (unicode, optional) – The timestamp of the commit as a string in ISO 8601 format.
  • message (unicode, optional) – The commit message.
  • parent (unicode, optional) – The ID of the commit’s parent. This should be its SHA/revision.
  • diff (bytes, optional) – The contents of the commit’s diff.
  • base_commit_id (unicode, optional) –

    This is equivalent to parent, but can be left unset.

    Deprecated since version 2.5.7: This will be removed in the future. Callers should stop providing this argument.

diff[source]

The diff contents for the commit.

__eq__(other)[source]

Return whether this commit is equal to another commit.

Parameters:other (Commit) – The commit to compare to.
Returns:True if the two commits are equal. False if they are not.
Return type:bool
__repr__()[source]

Return a string representation of this commit.

Returns:The string representation.
Return type:unicode
split_message()[source]

Return a split version of the commit message.

This will separate the commit message into a summary and body, if possible.

Returns:A tuple containing two string items: The summary and the commit message.

If the commit message is only a single line, both items in the tuple will be that line.

Return type:tuple
HEAD = <Revision: HEAD>[source]

Latest revision in the tree (or branch).

UNKNOWN = <Revision: UNKNOWN>[source]

Unknown revision.

This is used to indicate that a revision could not be found or parsed.

PRE_CREATION = <Revision: PRE-CREATION>[source]

Revision representing a new file (prior to entering the repository).

class SCMTool(repository)[source]

Bases: object

A backend for talking to a source code repository.

This is responsible for handling all the communication with a repository and working with data provided by a repository. This includes validating repository configuration, fetching file contents, returning log information for browsing commits, constructing a diff parser for the repository’s supported diff format(s), and more.

repository

reviewboard.scmtools.models.Repository – The repository owning an instance of this SCMTool.

name = None[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 = False[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.

supports_post_commit = False[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_raw_file_urls = False[source]

Whether custom URL masks can be defined to fetching file contents.

Some systems (such as Git) have no way of accessing an individual file in a repository over a network without having a complete up-to-date checkout accessible to the Review Board server. For those, Review Board can offer a field for specifying a URL mask (a URL with special strings acting as a template) that will be used when pulling down the contents of a file referenced in a diff.

If True, this field will be shown in the repository configuration. It’s up to the SCMTool to handle and parse the value.

supports_ticket_auth = False[source]

Whether ticket-based authentication is supported.

Ticket-based authentication is an authentication method where the SCMTool requests an authentication ticket from the repository, in order to access repository content. For these setups, the SCMTool must handle determining when it needs a new ticket and requesting it, generally based on the provided username and password.

If True, an option will be shown for enabling this when configuring the repository. It’s up to the SCMTool to make use of it.

field_help_text = {u'path': _(u'The path to the repository. This will generally be the URL you would use to check out the repository.')}[source]

Overridden help text for the configuration form fields.

This allows the form fields to have custom help text for the SCMTool, providing better guidance for configuration.

dependencies = {u'executables': [], u'modules': []}[source]

A dictionary containing lists of dependencies needed for this SCMTool.

This should be overridden by subclasses that require certain external modules or binaries. It has two keys: executables and modules. Each map to a list of names.

The list of Python modules go in modules, and must be valid, importable modules. If a module is not available, the SCMTool will be disabled.

The list of executables shouldn’t contain a file extensions (e.g., .exe), as Review Board will automatically attempt to use the right extension for the platform.

__init__(repository)[source]

Initialize the SCMTool.

This will be initialized on demand, when first needed by a client working with a repository. It will generally be bound to the lifetime of the repository instance.

Parameters:repository (reviewboard.scmtools.models.Repository) – The repository owning this SCMTool.
diffs_use_absolute_paths[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.

get_file(path, revision=<Revision: HEAD>, base_commit_id=None, **kwargs)[source]

Return the contents of a file from a repository.

This attempts to return the raw binary contents of a file from the repository, given a file path and revision.

It may also take a base commit ID, which is the ID (SHA or revision number) of a commit changing or introducing the file. This may differ from the revision for some types of repositories, where different IDs are used for a file content revision and a commit revision.

Subclasses must implement this.

Parameters:
  • path (unicode) – The path to the file in the repository.
  • revision (Revision, optional) – The revision to fetch. Subclasses should default this to HEAD.
  • base_commit_id (unicode, 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.
  • **kwargs (dict) – Additional keyword arguments. This is not currently used, but is available for future expansion.
Returns:

The returned file contents.

Return type:

bytes

Raises:
file_exists(path, revision=<Revision: HEAD>, base_commit_id=None, **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.

Parameters:
  • path (unicode) – The path to the file in the repository.
  • revision (Revision, optional) – The revision to fetch. Subclasses should default this to HEAD.
  • base_commit_id (unicode, 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.
  • **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

parse_diff_revision(file_str, revision_str, moved=False, copied=False, **kwargs)[source]

Return a parsed filename and revision as represented in a diff.

A diff may use strings like (working copy) as a revision. This function will be responsible for converting this to something Review Board can understand.

Parameters:
  • file_str (unicode) – The filename as represented in the diff.
  • revision_str (unicode) – The revision as represented in the diff.
  • moved (bool, optional) – Whether the file was marked as moved in the diff.
  • copied (bool, optional) – Whether the file was marked as copied in the diff.
  • **kwargs (dict) – Additional keyword arguments. This is not currently used, but is available for future expansion.
Returns:

A tuple containing two items: The normalized filename string, and a Revision.

Return type:

tuple

Raises:

reviewboard.scmtools.errors.InvalidRevisionFormatError – The revision or base_commit_id arguments were in an invalid format.

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 (unicode) – 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:
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: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 (unicode, optional) – The branch to limit commits to. This may not be supported by all repositories.
  • start (unicode, 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:

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

get_change(revision)[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 (unicode) – 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.
get_parser(data)[source]

Return a diff parser used to parse diff data.

The diff parser will be responsible for parsing the contents of the diff, and should expect (but validate) that the diff content is appropriate for the type of repository.

Subclasses should override this.

Parameters:data (bytes) – The diff data to parse.
Returns:The diff parser used to parse this data.
Return type:reviewboard.diffviewer.diffparser.DiffParser
normalize_path_for_display(filename)[source]

Normalize a path from a diff for display to the user.

This can take a path/filename found in a diff and normalize it, stripping away unwanted information, so that it displays in a better way in the diff viewer.

By default, this returns the path as-is.

Parameters:filename (unicode) – The filename/path to normalize.
Returns:The resulting filename/path.
Return type:unicode
normalize_patch(patch, filename, revision)[source]

Normalize a diff/patch file before it’s applied.

This can be used to take an uploaded diff file and modify it so that it can be properly applied. This may, for instance, uncollapse keywords or remove metadata that would confuse patch.

By default, this returns the contents as-is.

Parameters:
  • patch (bytes) – The diff/patch file to normalize.
  • filename (unicode) – The name of the file being changed in the diff.
  • revision (unicode) – The revision of the file being changed in the diff.
Returns:

The resulting diff/patch file.

Return type:

bytes

classmethod popen(command, local_site_name=None, env={})[source]

Launch an application and return its output.

This wraps subprocess.Popen() to provide some common parameters and to pass environment variables that may be needed by rbssh (if used).

Parameters:
  • command (list of unicode) – The command to execute.
  • local_site_name (unicode, optional) – The name of the Local Site being used, if any.
  • env (dict, optional) – Extra environment variables to provide. Each key and value must be byte strings.
Returns:

The combined output (stdout and stderr) from the command.

Return type:

bytes

Raises:

OSError – Error when invoking the command. See the subprocess.Popen() documentation for more details.

classmethod check_repository(path, username=None, password=None, local_site_name=None)[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.

The result, if the repository configuration is invalid, is returned as an exception. The exception may contain extra information, such as a human-readable description of the problem. Many types of errors can be returned, based on issues with the repository, authentication, HTTPS certificate, or SSH keys.

If the repository configuration is valid and a connection can be established, this will simply return.

Subclasses should override this to provide more specific validation logic.

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.
Raises:
classmethod get_auth_from_uri(path, username)[source]

Return the username and hostname from the given repository path.

This is used to separate out a username and a hostname from a path, given a string containing username@hostname.

Subclasses do not need to provide this in most cases. It’s used as a convenience method for check_repository(). Subclasses that need special parsing logic will generally just replace the behavior in that method.

Parameters:
  • path (unicode) – The repository path to parse.
  • username (unicode) – The existing username provided in the repository configuration.
Returns:

A tuple containing 2 string items: The username, and the hostname.

Return type:

tuple

classmethod accept_certificate(path, username=None, password=None, local_site_name=None, certificate=None)[source]

Accept the HTTPS certificate for the given repository path.

This is needed for repositories that support HTTPS-backed repositories. It should mark an HTTPS certificate as accepted so that the user won’t see validation errors in the future.

The administration UI will call this after a user has seen and verified the HTTPS certificate.

Subclasses must override this if they support HTTPS-backed repositories and can offer certificate verification and approval.

Parameters:
  • path (unicode) – The repository path.
  • username (unicode, optional) – The username provided for the repository.
  • password (unicode, optional) – The password provided for the repository.
  • local_site_name (unicode, optional) – The name of the Local Site used for the repository, if any.
  • certificate (reviewboard.scmtools.certs.Certificate) – The certificate to accept.
Returns:

Serialized information on the certificate.

Return type:

dict

Raises:

reviewboard.scmtools.errors.SCMError – There was an error accepting the certificate.

class SCMClient(path, username=None, password=None)[source]

Bases: object

Base class for client classes that interface with an SCM.

Some SCMTools, rather than calling out to a third-party library, provide their own client class that interfaces with a command-line tool or HTTP-backed repository.

While not required, this class contains functionality that may be useful to such client classes. In particular, it makes it easier to fetch files from an HTTP-backed repository, handling authentication and errors.

path

unicode – The repository path.

username

unicode, optional – The username used for the repository.

password

unicode, optional – The password used for the repository.

__init__(path, username=None, password=None)[source]

Initialize the client.

Parameters:
  • path (unicode) – The repository path.
  • username (unicode, optional) – The username used for the repository.
  • password (unicode, optional) – The password used for the repository.
get_file_http(url, path, revision, mime_type=None)[source]

Return the contents of a file from an HTTP(S) URL.

This is a convenience for looking up the contents of files that are referenced in diffs through an HTTP(S) request.

Authentication is performed using the username and password provided (if any).

Parameters:
  • url (unicode) – The URL to fetch the file contents from.
  • path (unicode) – The path of the file, as referenced in the diff.
  • revision (Revision) – The revision of the file, as referenced in the diff.
  • mime_type (unicode) – The expected content type of the file. If not specified, this will default to accept everything.
Returns:

The contents of the file if content type matched, otherwise None.

Return type:

bytes

Raises: