reviewboard.scmtools.models¶
Models for repository support.
- class Tool(*args, **kwargs)[source]¶
Bases:
Model
A configured source code management tool.
Each
SCMTool
used by repositories must have a correspondingTool
entry. These provide information on the capabilities of the tool, and accessors to construct a tool for a repository.Deprecated since version 5.0: This model is now obsolete. Any usage of this should be updated to use equivalent methods on the Repository or SCMTool instead.
- name[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- class_name[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- objects: ClassVar[ToolManager] = <reviewboard.scmtools.managers.ToolManager object>¶
- property field_help_text[source]¶
Overridden help text for the configuration form fields.
See
SCMTool.field_help_text
for details.
- get_scmtool_class() type[SCMTool] [source]¶
Return the configured SCMTool class.
- Returns:
The subclass of
SCMTool
backed by this Tool entry.- Return type:
- Raises:
django.core.exceptions.ImproperlyConfigured – The SCMTool could not be found.
- property scmtool_class: type[SCMTool][source]¶
Return the configured SCMTool class.
- Returns:
The subclass of
SCMTool
backed by this Tool entry.- Return type:
- Raises:
django.core.exceptions.ImproperlyConfigured – The SCMTool could not be found.
- __annotations__ = {'objects': 'ClassVar[ToolManager]'}¶
- id¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- repositories¶
Accessor to the related objects manager on the reverse side of a many-to-one relation.
In the example:
class Child(Model): parent = ForeignKey(Parent, related_name='children')
Parent.children
is aReverseManyToOneDescriptor
instance.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.
- class Repository(*args, **kwargs)[source]¶
Bases:
Model
A configured external source code repository.
Each configured Repository entry represents a source code repository that Review Board can communicate with as part of the diff uploading and viewing process.
Repositories are backed by a
SCMTool
, which functions as a client for the type of repository and can fetch files, load lists of commits and branches, and more.Access control is managed by a combination of the
public
,users
, andgroups
fields.public
controls whether a repository is publicly-accessible by all users on the server. WhenFalse
, only users explicitly listed inusers
or users who are members of the groups listed ingroups
will be able to access the repository or view review requests posted against it.- BRANCHES_CACHE_PERIOD: Final[int] = 300¶
The amount of time branches are cached, in seconds.
Branches are cached for 5 minutes.
- COMMITS_CACHE_PERIOD_SHORT: Final[int] = 300¶
The short period of time to cache commit information, in seconds.
Some commit information (such as retrieving the latest commits in a repository) should result in information cached only for a short period of time. This is set to cache for 5 minutes.
- COMMITS_CACHE_PERIOD_LONG: Final[int] = 86400¶
The long period of time to cache commit information, in seconds.
Commit information that is unlikely to change should be kept around for a longer period of time. This is set to cache for 1 day.
- FALLBACK_ENCODING: Final[str] = 'iso-8859-15'¶
The fallback encoding for text-based files in repositories.
This is used if the file isn’t valid UTF-8, and if the repository doesn’t specify a list of encodings.
- NAME_CONFLICT_ERROR: Final[StrPromise] = 'A repository with this name already exists'¶
The error message used to indicate that a repository name conflicts.
- PATH_CONFLICT_ERROR: Final[StrPromise] = 'A repository with this path already exists'¶
The error message used to indicate that a repository path conflicts.
- ENCRYPTED_PASSWORD_PREFIX: Final[str] = '\t'¶
The prefix used to indicate an encrypted password.
This is used to indicate whether a stored password is in encrypted form or plain text form.
- name[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- path[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- mirror_path[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- raw_file_url[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- username[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- encrypted_password[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- extra_data[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- tool[source]¶
Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.
In the example:
class Child(Model): parent = ForeignKey(Parent, related_name='children')
Child.parent
is aForwardManyToOneDescriptor
instance.
- scmtool_id[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- hosting_account[source]¶
Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.
In the example:
class Child(Model): parent = ForeignKey(Parent, related_name='children')
Child.parent
is aForwardManyToOneDescriptor
instance.
- bug_tracker[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- encoding[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- visible[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- archived[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- archived_timestamp[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- local_site[source]¶
Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.
In the example:
class Child(Model): parent = ForeignKey(Parent, related_name='children')
Child.parent
is aForwardManyToOneDescriptor
instance.
- public[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- users[source]¶
Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.
In the example:
class Pizza(Model): toppings = ManyToManyField(Topping, related_name='pizzas')
Pizza.toppings
andTopping.pizzas
areManyToManyDescriptor
instances.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.
- review_groups[source]¶
Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.
In the example:
class Pizza(Model): toppings = ManyToManyField(Topping, related_name='pizzas')
Pizza.toppings
andTopping.pizzas
areManyToManyDescriptor
instances.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.
- hooks_uuid[source]¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- objects: ClassVar[RepositoryManager] = <reviewboard.scmtools.managers.RepositoryManager object>¶
- property password: Optional[str][source]¶
The password for the repository.
If a password is stored and encrypted, it will be decrypted and returned.
If the stored password is in plain-text, then it will be encrypted, stored in the database, and returned.
- property scmtool_class: Optional[type[SCMTool]][source]¶
The SCMTool subclass used for this repository.
- Type:
- Raises:
django.core.exceptions.ImproperlyConfigured – The SCMTool could not be found, due to missing packages or extensions. Details are in the message, and the failure is logged.
- hosting_service()[source]¶
The hosting service providing this repository.
This will be
None
if this is a standalone repository.- Type:
reviewboard.hostingsvcs.base.hosting_service.BaseHostingService
- Raises:
reviewboard.hostingsvcs.errors.MissingHostingServiceError – The hosting service for this repository could not be loaded.
- bug_tracker_service()[source]¶
The selected bug tracker service for the repository.
This will be
None
if this repository is not associated with a bug tracker.- Type:
reviewboard.hostingsvcs.base.hosting_service.BaseHostingService
- Raises:
reviewboard.hostingsvcs.errors.MissingHostingServiceError – The hosting service for this repository could not be loaded.
- property supports_post_commit: bool[source]¶
Whether or not this repository supports post-commit creation.
If this is
True
, theget_branches()
andget_commits()
methods will be implemented to fetch information about the committed revisions, and get_change will be implemented to fetch the actual diff. This is used byReviewRequestDraft.update_from_commit_id
.- Type:
- Raises:
reviewboard.hostingsvcs.errors.MissingHostingServiceError – The hosting service for this repository could not be loaded.
- property supports_pending_changesets: bool[source]¶
Whether this repository supports server-aware pending changesets.
- Type:
- diffs_use_absolute_paths()[source]¶
Whether or not diffs for this repository contain absolute paths.
Some types of source code management systems generate diffs that contain paths relative to the directory where the diff was generated. Most contain absolute paths. This flag indicates which path format this repository can expect.
- Type:
- get_scmtool() SCMTool [source]¶
Return an instance of the SCMTool for this repository.
Each call will construct a brand new instance. The returned value should be stored and used for multiple operations in a single session.
- Returns:
A new instance of the SCMTool for this repository.
- Return type:
- get_credentials() Mapping[str, Any] [source]¶
Return the credentials for this repository.
This returns a dictionary with
username
andpassword
keys. By default, these will be the values stored for the repository, but if a hosting service is used and the repository doesn’t have values for one or both of these, the hosting service’s credentials (if available) will be used instead.- Returns:
A dictionary with credentials information.
- Return type:
- get_or_create_hooks_uuid(*, max_attempts: int = 20) str [source]¶
Return a hooks UUID, creating one if necessary.
A hooks UUID is used for creating unique incoming webhook URLs, allowing services to communicate information to Review Board.
If a hooks UUID isn’t already saved, then this will try to generate one that doesn’t conflict with any other registered hooks UUID. It will try up to
max_attempts
times, and if it fails,None
will be returned.
- get_encoding_list() Sequence[str] [source]¶
Return a list of candidate text encodings for files.
This will return a list based on a comma-separated list of encodings in
encoding
. If no encodings are configured, the default ofiso-8859-15
will be used.
- get_file(*, path: str, revision: str, base_commit_id: Optional[str] = None, request: Optional[HttpRequest] = None, context: Optional[FileLookupContext] = None) bytes [source]¶
Return a file from the repository.
This will attempt to retrieve the file from the repository. If the repository is backed by a hosting service, it will go through that. Otherwise, it will attempt to directly access the repository.
This will send the
fetching_file
signal before beginning a file fetch from the repository (if not cached), and thefetched_file
signal after.- Parameters:
path (
str
) – The path to the file in the repository.revision (
str
) – The revision of the file to retrieve.base_commit_id (
str
, optional) –The ID of the commit containing the revision of the file to retrieve. This is required for some types of repositories where the revision of a file and the ID of a commit differ.
Deprecated since version 4.0.5: Callers should provide this in
context
instead.request (
django.http.HttpRequest
, optional) –The current HTTP request from the client. This is used for logging purposes.
Deprecated since version 4.0.5: Callers should provide this in
context
instead.context (
reviewboard.scmtools.core.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.
New in version 4.0.5.
- Returns:
The resulting file contents.
- Return type:
- Raises:
TypeError – One or more of the provided arguments is an invalid type. Details are contained in the error message.
- get_file_exists(*, path: str, revision: str, base_commit_id: Optional[str] = None, request: Optional[HttpRequest] = None, context: Optional[FileLookupContext] = None) bool [source]¶
Return whether or not a file exists in the repository.
If the repository is backed by a hosting service, this will go through that. Otherwise, it will attempt to directly access the repository.
The result of this call will be cached, making future lookups of this path and revision on this repository faster.
This will send the
checking_file_exists
signal before beginning a file fetch from the repository (if not cached), and thechecked_file_exists
signal after.- Parameters:
path (
str
) – The path to the file in the repository.revision (
str
) – The revision of the file to check.base_commit_id (
str
, optional) –The ID of the commit containing the revision of the file to check. This is required for some types of repositories where the revision of a file and the ID of a commit differ.
Deprecated since version 4.0.5: Callers should provide this in
context
instead.request (
django.http.HttpRequest
, optional) –The current HTTP request from the client. This is used for logging purposes.
Deprecated since version 4.0.5: Callers should provide this in
context
instead.context (
reviewboard.scmtools.core.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.
New in version 4.0.5.
- Returns:
True
if the file exists in the repository.False
if it does not.- Return type:
- Raises:
TypeError – One or more of the provided arguments is an invalid type. Details are contained in the error message.
- 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.
- Returns:
The list of branches in the repository. One (and only one) will be marked as the default branch.
- Return type:
- Raises:
reviewboard.hostingsvcs.errors.HostingServiceError – The hosting service backing the repository encountered an error.
reviewboard.scmtools.errors.SCMError – The repository tool encountered an error.
NotImplementedError – Branch retrieval is not available for this type of repository.
- get_commit_cache_key(commit_id: str) str [source]¶
Return the cache key used for a commit ID.
The resulting cache key is used to cache information about a commit retrieved from the repository that matches the provided ID. This can be used to delete information already in cache.
- get_commits(*, branch: Optional[str] = None, start: Optional[str] = None) Sequence[Commit] [source]¶
Return a list of commits.
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.- Parameters:
- Returns:
The retrieved commits.
- Return type:
- Raises:
reviewboard.hostingsvcs.errors.HostingServiceError – The hosting service backing the repository encountered an error.
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 in the repository.
- Parameters:
revision (
str
) – The commit ID or revision to retrieve.- Returns:
The commit from the repository.
- Return type:
- Raises:
reviewboard.hostingsvcs.errors.HostingServiceError – The hosting service backing the repository encountered an error.
reviewboard.scmtools.errors.SCMError – The repository tool encountered an error.
NotImplementedError – Commits retrieval is not available for this type of repository.
- 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.
This passes the request on to the hosting service or repository tool backend.
- Parameters:
- Returns:
The resulting diff/patch file.
- Return type:
- Raises:
reviewboard.hostingsvcs.errors.MissingHostingServiceError – The hosting service for this repository could not be loaded.
- is_accessible_by(user: Union[AnonymousUser, User]) bool [source]¶
Return whether or not the user has access to the repository.
The repository is accessibly by the user if it is public or the user has access to it (either by being explicitly on the allowed users list, or by being a member of a review group on that list).
- Parameters:
user (
django.contrib.auth.models.User
) – The user to check.- Returns:
True
if the repository is accessible by the user.False
if it is not.- Return type:
- is_mutable_by(user: Union[AnonymousUser, User]) bool [source]¶
Return whether or not the user can modify or delete the repository.
The repository is mutable by the user if the user is an administrator with proper permissions or the repository is part of a LocalSite and the user has permissions to modify it.
- Parameters:
user (
django.contrib.auth.models.User
) – The user to check.- Returns:
True
if the repository can modify or delete the repository.False
if they cannot.- Return type:
- archive(*, save: bool = True) None [source]¶
Archive a repository.
The repository won’t appear in any public lists of repositories, and won’t be used when looking up repositories. Review requests can’t be posted against an archived repository.
New repositories can be created with the same information as the archived repository.
- Parameters:
save (
bool
, optional) – Whether to save the repository immediately.
- save(*args, **kwargs) None [source]¶
Save the repository.
This will perform any data normalization needed, and then save the repository to the database.
- Parameters:
**kwargs (
dict
) – Keyword arguments to pass to the parent method.
- clean() None [source]¶
Clean method for checking null unique_together constraints.
Django has a bug where unique_together constraints for foreign keys aren’t checked properly if one of the relations is null. This means that users who aren’t using local sites could create multiple groups with the same name.
- Raises:
django.core.exceptions.ValidationError – Validation of the model’s data failed. Details are in the exception.
- __str__() str [source]¶
Return a string representation of the repository.
This uses the repository’s name as the string representation. However, it should not be used if explicitly wanting to retrieve the repository name, as future versions may return a different value.
- Returns:
The repository name.
- Return type:
- __annotations__ = {'BRANCHES_CACHE_PERIOD': 'Final[int]', 'COMMITS_CACHE_PERIOD_LONG': 'Final[int]', 'COMMITS_CACHE_PERIOD_SHORT': 'Final[int]', 'ENCRYPTED_PASSWORD_PREFIX': 'Final[str]', 'FALLBACK_ENCODING': 'Final[str]', 'NAME_CONFLICT_ERROR': 'Final[StrPromise]', 'PATH_CONFLICT_ERROR': 'Final[StrPromise]', '_scmtool_class': 'type[SCMTool]', 'objects': 'ClassVar[RepositoryManager]'}¶
- defaultreviewer_set¶
Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.
In the example:
class Pizza(Model): toppings = ManyToManyField(Topping, related_name='pizzas')
Pizza.toppings
andTopping.pizzas
areManyToManyDescriptor
instances.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.
- diffsets¶
Accessor to the related objects manager on the reverse side of a many-to-one relation.
In the example:
class Child(Model): parent = ForeignKey(Parent, related_name='children')
Parent.children
is aReverseManyToOneDescriptor
instance.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.
- file_attachments¶
Accessor to the related objects manager on the reverse side of a many-to-one relation.
In the example:
class Child(Model): parent = ForeignKey(Parent, related_name='children')
Parent.children
is aReverseManyToOneDescriptor
instance.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.
- get_extra_data_json()¶
- hosting_account_id¶
- id¶
A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.
- local_site_id¶
- review_requests¶
Accessor to the related objects manager on the reverse side of a many-to-one relation.
In the example:
class Child(Model): parent = ForeignKey(Parent, related_name='children')
Parent.children
is aReverseManyToOneDescriptor
instance.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.
- set_extra_data_json(json)¶
- tool_id¶
- webhooks¶
Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.
In the example:
class Pizza(Model): toppings = ManyToManyField(Topping, related_name='pizzas')
Pizza.toppings
andTopping.pizzas
areManyToManyDescriptor
instances.Most of the implementation is delegated to a dynamically defined manager class built by
create_forward_many_to_many_manager()
defined below.