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.
- extra_data: JSONDict¶
Extra data to store in the draft.
These may map to custom fields.
New in version 5.0.5.
- __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.
- name: TypedProperty[str, str]¶
The name/ID of the revision.
- Type:
- __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:
- __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:
- __repr__() str [source]¶
Return a string representation of this revision.
- Returns:
The string representation.
- Return type:
- __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.
- id: TypedProperty[str, str]¶
The ID of the branch.
- Type:
- 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:
- __repr__() str [source]¶
Return a string representation of this branch.
- Returns:
The string representation.
- Return type:
- __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:
- id: TypedProperty[Optional[str], Optional[str]]¶
The ID of the commit.
This should be its SHA/revision.
- Type:
- date: TypedProperty[Optional[str], Optional[str]]¶
The timestamp of the commit as a string in ISO 8601 format.
- Type:
- 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:
- diff: TypedProperty[Optional[bytes], Optional[bytes]]¶
The contents of the commit’s diff.
This may be
None
, depending on how the commit is fetched.
- __repr__() str [source]¶
Return a string representation of this commit.
- Returns:
The string representation.
- Return type:
- 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.
- __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 beNone
.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 beNone
. 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
orParsedDiff.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
orParsedDiffChange.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
orParsedDiffFile.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
orParsedDiffChange.extra_data
.
- diff_extra_data: JSONDict¶
General metadata stored about the parsed diff.
This is generally the data in
DiffSet.extra_data
orParsedDiff.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
orParsedDiffFile.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]]'}¶
- 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.
- 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.
- 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
andmodules
. 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 deprecatesbase_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 toHEAD
.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:
- Raises:
reviewboard.scmtools.errors.FileNotFoundError – The file could not be found in the repository.
reviewboard.scmtools.errors.InvalidRevisionFormatError – The
revision
orbase_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 deprecatesbase_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 toHEAD
.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:
- 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
andrevision
, instead offile_str
andrevision_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:
- Return type:
- Raises:
reviewboard.scmtools.errors.InvalidRevisionFormatError – The
revision
orbase_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
isTrue
.- 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. IfFalse
, areviewboard.scmtools.errors.EmptyChangeSetError
will be raised.Defaults to
False
.
- Returns:
The resulting changeset containing information on the commit and modified files.
- Return type:
- 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
wasFalse
).
- 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:
- 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 withdefault
set toTrue
.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:
- 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 thestart
parameter in order to paginate through the history of commits in the repository.Callers should check
supports_post_commit
before calling this.- Parameters:
- Returns:
The list of commits, in order from newest to oldest.
- Return type:
- 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:
- 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
andkwargs
arguments. Subclasses that don’t accept at leastkwargs
will result in a deprecation warning.- Parameters:
- Returns:
The resulting filename/path.
- Return type:
- 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.
- 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:
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:
- 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 fromauth_form
andrepository_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.
- classmethod create_auth_form(**kwargs) BaseSCMToolAuthForm [source]¶
Return a form for configuring repository authentication details.
This defaults to returning an instance of
auth_form
(orStandardSCMToolAuthForm
, 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:
- classmethod create_repository_form(**kwargs) BaseSCMToolRepositoryForm [source]¶
Return a form for configuring repository information.
This defaults to returning an instance of
repository_form
(orStandardSCMToolRepositoryForm
, 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:
- 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:
- 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.
- 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:
- 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.