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.

__init__()[source]¶

Initialize the changeset.

branch: _StrProperty¶

The destination branch.

Type:

str

bugs_closed: List[str]¶

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

Type:

list of str

changenum: _IntProperty¶

The changeset number/ID.

Type:

int

description: _StrProperty¶

The description of the change.

Type:

str

extra_data: JSONDict¶

Extra data to store in the draft.

These may map to custom fields.

New in version 5.0.5.

files: List[str]¶

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

Type:

list of str

pending: bool¶

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

Type:

bool

summary: _StrProperty¶

The summary of the change.

Type:

str

testing_done: _StrProperty¶

Testing information for the change.

Type:

str

username: _StrProperty¶

The username of the user who made the change.

Type:

str

__annotations__ = {'branch': '_StrProperty', 'bugs_closed': 'List[str]', 'changenum': '_IntProperty', 'description': '_StrProperty', 'extra_data': 'JSONDict', 'files': 'List[str]', 'pending': 'bool', 'summary': '_StrProperty', 'testing_done': '_StrProperty', 'username': '_StrProperty'}¶

class Revision(name: str)[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: str) → None[source]¶

Initialize the Revision.

Parameters:

name (str) – 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: TypedProperty[str, str]¶

The name/ID of the revision.

Type:

str

__bytes__() → 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__() → str[source]¶

Return a Unicode string representation of the revision.

This is equivalent to fetching name.

Returns:

The name/ID of the revision.

Return type:

str

__eq__(other: Any) → bool[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: Any) → bool[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__() → str[source]¶

Return a string representation of this revision.

Returns:

The string representation.

Return type:

str

__annotations__ = {'name': '_StrRequiredProperty'}¶

__hash__ = None¶

class Branch(id: str, name: Optional[str] = None, commit: str = '', default: bool = False)[source]¶

Bases: object

A branch in a repository.

__init__(id: str, name: Optional[str] = None, commit: str = '', default: bool = False) → None[source]¶

Initialize the branch.

Parameters:

• id (str) – The ID of the branch.

• name (str, optional) – The name of the branch. If not specified, this will default to the ID.

• commit (str, optional) – The latest commit ID on the branch.

• default (bool, optional) – Whether or not this is the default branch for the repository.

id: TypedProperty[str, str]¶

The ID of the branch.

Type:

str

name: TypedProperty[Optional[str], Optional[str]]¶

The name of the branch.

Type:

str

commit: TypedProperty[Optional[str], Optional[str]]¶

The latest commit ID on the branch.

Type:

str

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.

Type:

bool

__eq__(other: Any) → bool[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__() → str[source]¶

Return a string representation of this branch.

Returns:

The string representation.

Return type:

str

__annotations__ = {'commit': '_StrProperty', 'default': 'bool', 'id': '_StrRequiredProperty', 'name': '_StrProperty'}¶

__hash__ = None¶

class Commit(author_name: str = '', id: str = '', date: str = '', message: str = '', parent: str = '', diff: Optional[bytes] = None)[source]¶

Bases: object

A commit in a repository.

__init__(author_name: str = '', id: str = '', date: str = '', message: str = '', parent: str = '', diff: Optional[bytes] = None) → None[source]¶

Initialize the commit.

All arguments are optional, and can be set later.

Parameters:

• author_name (str, 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 (str, optional) – The ID of the commit. This should be its SHA/revision.

• date (str, optional) – The timestamp of the commit as a string in ISO 8601 format.

• message (str, optional) – The commit message.

• parent (str, 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: TypedProperty[Optional[str], Optional[str]]¶

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

Type:

str

id: TypedProperty[Optional[str], Optional[str]]¶

The ID of the commit.

This should be its SHA/revision.

Type:

str

date: TypedProperty[Optional[str], Optional[str]]¶

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

Type:

str

message: TypedProperty[Optional[str], Optional[str]]¶

The commit message.

Type:

str

parent: TypedProperty[Optional[str], Optional[str]]¶

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.

Type:

str

diff: TypedProperty[Optional[bytes], Optional[bytes]]¶

The contents of the commit’s diff.

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

__eq__(other: Any) → bool[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__() → str[source]¶

Return a string representation of this commit.

Returns:

The string representation.

Return type:

str

split_message() → Tuple[str, str][source]¶

Return a split version of the commit message.

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

Returns:

A 2-tuple containing:

Tuple:

• 0 (str) – The summary of the commit.

• 1 (str) – The commit message.

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

Return type:

tuple

__annotations__ = {'author_name': '_StrProperty', 'date': '_StrProperty', 'diff': '_BytesProperty', 'id': '_StrProperty', 'message': '_StrProperty', 'parent': '_StrProperty'}¶

__hash__ = None¶

class FileLookupContext(request: Optional[HttpRequest] = None, user: Optional[Union[AbstractBaseUser, AnonymousUser]] = None, base_commit_id: Optional[str] = None, diff_extra_data: JSONDict = {}, commit_extra_data: JSONDict = {}, file_extra_data: JSONDict = {})[source]¶

Bases: object

Information available to aid in looking up files from a repository.

This is a container for several pieces of data that a SCM may need in order to look up content or details about a file from a repository.

New in version 4.0.5.

__init__(request: Optional[HttpRequest] = None, user: Optional[Union[AbstractBaseUser, AnonymousUser]] = None, base_commit_id: Optional[str] = None, diff_extra_data: JSONDict = {}, commit_extra_data: JSONDict = {}, file_extra_data: JSONDict = {}) → None[source]¶

Initialize the context.

Parameters:

• request (django.http.HttpRequest, optional) – The HTTP request from the client that triggered the file lookup. This may be None.

• user (django.contrib.auth.models.User, optional) –

  The user triggering the repository lookup. This defaults to the user from request.

  This is not the user that’s communicating with the repository.

• base_commit_id (str, optional) – The ID of the commit that the file was changed in. This may be None. The contents and interpretation are dependent on the type of the repository.

• diff_extra_data (dict, optional) –

  General metadata stored about the parsed diff.

  This is generally the data in DiffSet.extra_data or ParsedDiff.extra_data.

• commit_extra_data (dict, optional) –

  Metadata stored about the parsed commit from the diff.

  This is generally the data in DiffCommit.extra_data or ParsedDiffChange.extra_data.

• file_extra_data (dict, optional) –

  General metadata stored about the parsed file from the diff.

  This is generally the data in FileDiff.extra_data or ParsedDiffFile.extra_data.

Raises:

TypeError – A provided attribute is of an incorrect type.

base_commit_id: Optional[str]¶

The ID of the commit that the file was changed in.

This may be None. The contents and interpretation are dependent on the of the repository.

commit_extra_data: JSONDict¶

Metadata stored about the parsed commit from the diff.

This is generally the data in DiffCommit.extra_data or ParsedDiffChange.extra_data.

diff_extra_data: JSONDict¶

General metadata stored about the parsed diff.

This is generally the data in DiffSet.extra_data or ParsedDiff.extra_data.

file_extra_data: JSONDict¶

General metadata stored about the parsed file from the diff.

This is generally the data in FileDiff.extra_data or ParsedDiffFile.extra_data.

request: Optional[HttpRequest]¶

The HTTP request from the client that triggered the file lookup.

This may be None.

user: Optional[Union[AbstractBaseUser, AnonymousUser]]¶

The user triggering the repository lookup.

This is not the user that’s communicating with the repository.

__annotations__ = {'base_commit_id': 'Optional[str]', 'commit_extra_data': 'JSONDict', 'diff_extra_data': 'JSONDict', 'file_extra_data': 'JSONDict', 'request': 'Optional[HttpRequest]', 'user': 'Optional[Union[AbstractBaseUser, AnonymousUser]]'}¶

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).

RevisionID¶

A type indicating either a revision constant or repository-specific ID.

New in version 5.0.5.

alias of Union[Revision, str]

class SCMTool(repository: 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.

scmtool_id: str = None¶

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] = None¶

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”.

lookup_name: ClassVar[Optional[str]] = None¶

The name used for SCMTool registration and lookup.

This allows a SCMTool to specify the name used for both registration and lookup in both the SCMTool registry and database. It defaults to name, and should be changed in subcalsses if setting a new name for display purposes.

New in version 6.0.3.

class_name: ClassVar[Optional[str]] = None¶

The class name for the tool.

This is populated automatically once the tool is registered, and should not be set by subclasses.

New in version 5.0.

supports_history: bool = False¶

Whether or not the SCMTool supports review requests with history.

commits_have_committer: bool = False¶

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

supports_pending_changesets: bool = False¶

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: bool = False¶

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: bool = False¶

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: bool = False¶

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: bool = False¶

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.

diffs_use_commit_ids_as_revisions: bool = False¶

Whether diff files use a defined commit ID as file revisions.

This is used for SCMs where diffs use commit IDs to look up file contents rather than individual revisions, and those commit IDs are defined as metadata in the diff without necessarily being listed along with each file.

When enabled, diff parsing will expect to find parent commit IDs in the diff, and those parent commit IDs will be used if the parser doesn’t find a suitable revision associated with an individual file. This particularly applies when a file is present in a diff but not in a parent diff, and the parent diff’s parent commit ID needs to be used to look up the file.

By default, this is False. Subclasses must override this is if they need this behavior.

New in version 4.0.5.

prefers_mirror_path: bool = False¶

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: Dict[str, _StrOrPromise] = {'path': 'The path to the repository. This will generally be the URL you would use to check out the repository.'}¶

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: Dict[str, List[str]] = {'executables': [], 'modules': []}¶

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.

__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'}¶

auth_form: Optional[Type[BaseSCMToolAuthForm]] = None¶

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: Optional[Type[BaseSCMToolRepositoryForm]] = None¶

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.

__init__(repository: Repository) → None[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.

repository: Repository¶

The repository owning an instance of this SCMTool.

get_file(path: str, revision: ~typing.Union[~reviewboard.scmtools.core.Revision, str] = <Revision: HEAD>, base_commit_id: ~typing.Optional[str] = None, context: ~typing.Optional[~reviewboard.scmtools.core.FileLookupContext] = None, **kwargs) → bytes[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.

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:

The returned file contents.

Return type:

bytes

Raises:

• reviewboard.scmtools.errors.FileNotFoundError – The file could not be found in the repository.

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

file_exists(path: str, revision: ~typing.Union[~reviewboard.scmtools.core.Revision, str] = <Revision: HEAD>, base_commit_id: ~typing.Optional[str] = None, context: ~typing.Optional[~reviewboard.scmtools.core.FileLookupContext] = None, **kwargs) → bool[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

parse_diff_revision(filename: bytes, revision: bytes, moved: bool = False, copied: bool = False, **kwargs) → Tuple[bytes, Union[bytes, Revision]][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.

Changed in version 6.0: The first two parameters are now named filename and revision, instead of file_str and revision_str, for consistency with built-in tools. These names will be required in a future version.

Parameters:

• filename (bytes) – The filename as represented in the diff.

• revision (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:

Tuple:

• 0 (bytes) – The normalized filename.

• 1 (bytes or Revision) – The normalized revision.

Return type:

tuple

Raises:

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

get_changeset(changesetid: str, allow_empty: bool = False) → ChangeSet[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).

get_repository_info() → Dict[str, Any][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() → Sequence[Branch][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: Optional[str] = None, start: Optional[str] = None) → Sequence[Commit][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(revision: str) → Commit[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_parser(data: bytes) → BaseDiffParser[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.BaseDiffParser

normalize_path_for_display(filename: str, extra_data: Optional[JSONDict] = None, **kwargs) → str[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 (str) – 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:

str

normalize_patch(patch: bytes, filename: str, revision: str) → bytes[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 (str) – The name of the file being changed in the diff.

• revision (str) – The revision of the file being changed in the diff.

Returns:

The resulting diff/patch file.

Return type:

bytes

classmethod popen(command: List[str], local_site_name: Optional[str] = None, env: Dict[str, str] = {}, **kwargs) → Popen[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).

Changed in version 4.0.5: Added **kwargs.

Parameters:

• command (list of str) – The command to execute.

• local_site_name (str, 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.

• **kwargs (dict) –

  Additional keyword arguments to pass to subprocess.Popen.

  All arguments can be set or overridden except for the command and env.

  New in version 4.0.5.

Returns:

The resulting process handle.

Return type:

subprocess.Popen

Raises:

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

classmethod check_repository(path: str, username: Optional[str] = None, password: Optional[str] = None, local_site_name: Optional[str] = None, local_site: Optional[LocalSite] = None, **kwargs) → 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 (str) – The repository path.

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

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

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

• local_site (reviewboard.site.models.LocalSite, optional) – The Local Site instance that owns this repository. This is optional.

• **kwargs (dict, unused) – Additional settings for the repository. These will come from auth_form and repository_form.

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.scmtools.errors.UnverifiedCertificateError – The SSL certificate on the server could not be verified. Information on the certificate will be returned in order to allow verification and acceptance using accept_certificate().

• 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 occurred. Callers should check for this and handle it.

classmethod get_auth_from_uri(path: str, username: str) → Tuple[str, str][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 (str) – The repository path to parse.

• username (str) – The existing username provided in the repository configuration.

Returns:

A 2-tuple containing:

Tuple:

• 0 (str) – The username.

• 1 (str) – The hostname.

Return type:

tuple

classmethod create_auth_form(**kwargs) → BaseSCMToolAuthForm[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) → BaseSCMToolRepositoryForm[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: str, username: Optional[str] = None, password: Optional[str] = None, local_site_name: Optional[str] = None, certificate: Optional[Certificate] = None) → Mapping[str, Any][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 (str) – The repository path.

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

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

• local_site_name (str, 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: str, username: Optional[str] = None, password: Optional[str] = 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.

__annotations__ = {'password': 'Optional[str]', 'path': 'str', 'username': 'Optional[str]'}¶

__init__(path: str, username: Optional[str] = None, password: Optional[str] = None) → None[source]¶

Initialize the client.

Parameters:

• path (str) – The repository path.

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

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

path: str¶

The repository path.

username: Optional[str]¶

The username used for communicating with the repository.

password: Optional[str]¶

The password used for communicating with the repository.

get_file_http(url: str, path: str, revision: Union[Revision, str], mime_type: Optional[str] = None) → Optional[bytes][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 (str) – The URL to fetch the file contents from.

• path (str) – The path of the file, as referenced in the diff.

• revision (Revision) – The revision of the file, as referenced in the diff.

• mime_type (str) – 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:

• reviewboard.scmtools.errors.FileNotFoundError – The file could not be found.

• reviewboard.scmtools.errors.SCMError – Unexpected error in fetching the file. This may be an unexpected HTTP status code.