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.

bugs_closed

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

Type:list of unicode
files

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

Type:list of unicode
pending

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

Type:bool
__init__()[source]

Initialize the changeset.

changenum

The changeset number/ID.

summary

The summary of the change.

description

The description of the change.

testing_done

Testing information for the change.

branch

The destination branch.

username

The username of the user who made the change.

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.

__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.
Raises:TypeError – The provided name was not a Unicode string.
name

The name/ID of the revision.

__bytes__()[source]

Return a byte string representation of the revision.

This is equivalent to fetching name and encoding to UTF-8.

Returns:The name/ID of the revision.
Return type:bytes
__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 Unicode 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.

default

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.

Type:bool
__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.
id

The ID of the branch.

name

The name of the branch.

commit

The latest commit ID on the branch.

__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)[source]

Bases: object

A commit in a repository.

__init__(author_name=u'', id=u'', date=u'', message=u'', parent=u'', diff=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.
author_name

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

id

The ID of the commit.

This should be its SHA/revision.

date

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

message

The commit message.

parent

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.

diff

The contents of the commit’s diff.

This may be None, depending on how the commit is fetched.

__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

The repository owning an instance of this SCMTool.

Type:reviewboard.scmtools.models.Repository
scmtool_id = None[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 = 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_history = False[source]

Whether or not the SCMTool supports review requests with history.

commits_have_committer = False[source]

Whether or not commits in this SCMTool require the committer fields.

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.

diffs_use_absolute_paths = 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.

prefers_mirror_path = False[source]

Whether this prefers the Mirror Path value for communication.

This will affect which field the repository configuration form will use for repository validation and for accepting certificates.

This should generally not be set by new SCMTools. It exists for backwards-compatibility with Perforce.

New in version 3.0.18.

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.

auth_form = None[source]

A custom form used to collect authentication details.

This allows subclasses to remove, change, or augment the standard fields for collecting a repository’s username and password.

New in version 3.0.16.

repository_form = None[source]

A custom form used to collect repository details.

This allows subclasses to remove, change, or augment the standard fields for collecting a repository’s path, mirror path, and other common information.

New in version 3.0.16.

static __new__(cls, *args, **kwargs)[source]

Construct a new instance of the SCMTool.

This will perform some checks for deprecated function signatures on the class, fix them up and emit deprecation warnings if found, and then construct and initialize the instance.

Parameters:
  • *args (tuple) – Positional arguments passed in during construction.
  • **kwargs (dict) – Keyword arguments passed in during construction.
Returns:

The new instance.

Return type:

SCMTool

__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.
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 (bytes) – The filename as represented in the diff.
  • revision_str (bytes) – 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:

  1. The normalized filename as a byte string.
  2. The normalized revision as a byte string or 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:
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:
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:
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, extra_data=None, **kwargs)[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.

Changed in version 3.0.19: Added extra_data and kwargs arguments. Subclasses that don’t accept at least kwargs will result in a deprecation warning.

Parameters:
  • filename (unicode) – The filename/path to normalize.
  • extra_data (dict, optional) – Extra data stored for the diff this file corresponds to. This may be empty or None. Subclasses should not assume the presence of anything here.
  • **kwargs (dict, unused) – Additional keyword arguments.
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 create_auth_form(**kwargs)[source]

Return a form for configuring repository authentication details.

This defaults to returning an instance of auth_form (or StandardSCMToolAuthForm, if not explicitly set).

Subclasses can override this to customize creation of the form.

Parameters:**kwargs (dict) – Keyword arguments to pass to the form’s constructor.
Returns:The repository form instance.
Return type:reviewboard.scmtools.forms.BaseSCMToolAuthForm
classmethod create_repository_form(**kwargs)[source]

Return a form for configuring repository information.

This defaults to returning an instance of repository_form (or StandardSCMToolRepositoryForm, if not explicitly set).

Subclasses can override this to customize creation of the form.

Parameters:**kwargs (dict) – Keyword arguments to pass to the form’s constructor.
Returns:The repository form instance.
Return type:reviewboard.scmtools.forms.BaseSCMToolRepositoryForm
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

The repository path.

Type:unicode
username

The username used for the repository.

Type:unicode, optional
password

The password used for the repository.

Type:unicode, optional
__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: