reviewboard.hostingsvcs.service¶

The base hosting service class and associated definitions.

class HostingServiceHTTPRequest(url, query=None, body=None, headers=None, method=u'GET', hosting_service=None, **kwargs)[source]¶

Bases: object

A request that can use any HTTP method.

By default, the urllib2.Request class only supports HTTP GET and HTTP POST methods. This subclass allows for any HTTP method to be specified for the request.

New in version 4.0.

body¶

The request payload body.

Type:	str

headers¶

The headers to send in the request. Each key and value is a native string.

Type:	dict

hosting_service¶

The hosting service this request is associated with.

Type:	reviewboard.hostingsvcs.service.HostingService

method¶

The HTTP method to perform.

Type:	unicode

url¶

The URL the request is being made on.

Type:	unicode

__init__(url, query=None, body=None, headers=None, method=u'GET', hosting_service=None, **kwargs)[source]¶

Initialize the request.

Parameters:

url (unicode) – The URL to make the request against. query (dict, optional) – Query arguments to add onto the URL. These will be mixed with any query arguments already in the URL, and the result will be applied in sorted order, for cross-Python compatibility. body (unicode or bytes, optional) – The payload body for the request, if using a POST or PUT request. headers (dict, optional) – Additional headers to attach to the request. method (unicode, optional) – The request method. If not provided, it defaults to a GET request. hosting_service (reviewboard.hostingsvcs.service.HostingService, optional) – The hosting service this request is associated with. **kwargs (dict, unused) – Additional keyword arguments for the request. This is unused, but allows room for expansion by subclasses.

data[source]¶

The payload data for the request.

Deprecated since version 4.0: This is deprecated in favor of the body attribute.

add_header(name, value)[source]¶

Add a header to the request.

Parameters:	name (unicode or bytes) – The header name. value (unicode or bytes) – The header value.

get_header(name, default=None)[source]¶

Return a header from the request.

Parameters:	name (unicode) – The header name. default (unicode, optional) – The default value if the header was not found.
Returns:	The header value.
Return type:	unicode

add_basic_auth(username, password)[source]¶

Add HTTP Basic Authentication headers to the request.

Parameters:	username (unicode or bytes) – The username. password (unicode or bytes) – The password.

add_digest_auth(username, password)[source]¶

Add HTTP Digest Authentication support to the request.

Parameters:	username (unicode) – The username. password (unicode) – The password.

add_urlopen_handler(handler)[source]¶

Add a handler to invoke for the urlopen call.

Note

This is dependent on a urllib2-backed request. While that is the default today, it may not be in the future. This method should be used with the knowledge that it may someday be deprecated, or may not work at all with special subclasses.

Parameters:	handler (urllib2.BaseHandler) – The handler to add.

open()[source]¶

Open the request to the server, returning the response.

Returns:	The response information from the server.
Return type:	HostingServiceHTTPResponse
Raises:	urllib2.URLError – An error occurred talking to the server, or an HTTP error (400+) was returned.

class HostingServiceHTTPResponse(request, url, data, headers, status_code)[source]¶

Bases: object

An HTTP response from the server.

This stores the URL, payload data, headers, and status code from an HTTP response.

It also emulates a 2-tuple, for compatibility with legacy (pre-Review Board 4.0) calls, when HTTP methods returned tuples of data and headers.

New in version 4.0.

data¶

The response data.

Type:	bytes

headers¶

The response headers. Keys and values will be native strings.

It’s recommended to call get_header() to request a header.

Type:	dict

request¶

The HTTP request this is in response to.

Type:	HostingServiceHTTPRequest

status_code¶

The HTTP status code for the response.

Type:	int

url¶

The URL providing the response.

Type:	unicode

__init__(request, url, data, headers, status_code)[source]¶

Initialize the response.

Parameters:	request (HostingServiceHTTPRequest) – The request this is in response to. url (unicode) – The URL serving the response. If redirected, this may differ from the request URL. data (bytes) – The response payload. headers (dict) – The response headers. status_code (int) – The response HTTP status code.

json[source]¶

A JSON representation of the payload data.

Raises:	ValueError – The data is not valid JSON.

get_header(name, default=None)[source]¶

Return the value of a header as a Unicode string.

This accepts a header name with any form of capitalization. The header name will be normalized.

Parameters:	name (unicode) – The header name. default (unicode, optional) – The default value if the header is not set.
Returns:	The resulting header value.
Return type:	unicode

__getitem__(i)[source]¶

Return an indexed item from the response.

This is used to emulate the older 2-tuple response returned by hosting service HTTP request methods.

Parameters:	i (int) – The index of the item.
Returns:	The object at the specified index. If 0, this will return data. If 1, this will return headers.
Return type:	object
Raises:	IndexError – An index other than 0 or 1 was requested.

class HostingServiceClient(hosting_service)[source]¶

Bases: object

Client for communicating with a hosting service’s API.

This implementation includes abstractions for performing HTTP operations, and wrappers for those to interpret responses as JSON data.

HostingService subclasses can also include an override of this class to add additional checking (such as GitHub’s checking of rate limit headers), or add higher-level API functionality.

hosting_service¶

The hosting service that owns this client.

Type:	HostingService

http_request_cls[source]¶

The HTTP request class to construct for HTTP requests.

Subclasses can replace this if they need custom behavior when constructing or invoking the request.

New in version 4.0.

alias of HostingServiceHTTPRequest

http_response_cls[source]¶

The HTTP response class to construct HTTP responses.

Subclasses can replace this if they need custom ways of formatting or interpreting response data.

New in version 4.0.

alias of HostingServiceHTTPResponse

use_http_basic_auth = True[source]¶

Whether to add HTTP Basic Auth headers by default.

By default, hosting services will support HTTP Basic Auth. This can be turned off if not needed.

New in version 4.0.

use_http_digest_auth = False[source]¶

Whether to add HTTP Digest Auth headers by default.

By default, hosting services will not support HTTP Digest Auth. This can be turned on if needed.

New in version 4.0.

__init__(hosting_service)[source]¶

Initialize the client.

Parameters:	hosting_service (HostingService) – The hosting service that is using this client.

http_delete(url, headers=None, *args, **kwargs)[source]¶

Perform an HTTP DELETE on the given URL.

Changed in version 4.0: This now returns a HostingServiceHTTPResponse instead of a 2-tuple. The response can be treated as a 2-tuple for older code.

Parameters:	url (unicode) – The URL to perform the request on. headers (dict, optional) – Extra headers to include with the request. *args (tuple) – Additional positional arguments to pass to http_request(). **kwargs (dict) – Additional keyword arguments to pass to http_request().
Returns:	The HTTP response for the request.
Return type:	HostingServiceHTTPResponse
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_get(url, headers=None, *args, **kwargs)[source]¶

Perform an HTTP GET on the given URL.

Changed in version 4.0: This now returns a HostingServiceHTTPResponse instead of a 2-tuple. The response can be treated as a 2-tuple for older code.

Parameters:	url (unicode) – The URL to perform the request on. headers (dict, optional) – Extra headers to include with the request. *args (tuple) – Additional positional arguments to pass to http_request(). **kwargs (dict) – Additional keyword arguments to pass to http_request().
Returns:	The HTTP response for the request.
Return type:	HostingServiceHTTPResponse
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_head(url, headers=None, *args, **kwargs)[source]¶

Perform an HTTP HEAD on the given URL.

New in version 4.0.

Parameters:	url (unicode) – The URL to perform the request on. headers (dict, optional) – Extra headers to include with the request. *args (tuple) – Additional positional arguments to pass to http_request(). **kwargs (dict) – Additional keyword arguments to pass to http_request().
Returns:	The HTTP response for the request.
Return type:	HostingServiceHTTPResponse
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_post(url, body=None, fields=None, files=None, content_type=None, headers=None, *args, **kwargs)[source]¶

Perform an HTTP POST on the given URL.

Changed in version 4.0: This now returns a HostingServiceHTTPResponse instead of a 2-tuple. The response can be treated as a 2-tuple for older code.

Parameters:	url (unicode) – The URL to perform the request on. body (bytes, optional) – The request body. if not provided, it will be generated from the fields and files arguments. fields (dict, optional) – Form fields to use to generate the request body. This argument will only be used if body is None. files (dict, optional) – Files to use to generate the request body. This argument will only be used if body is None. content_type (unicode, optional) – The content type of the request. If provided, it will be appended as the Content-Type header. headers (dict, optional) – Extra headers to include with the request. *args (tuple) – Additional positional arguments to pass to http_request(). **kwargs (dict) – Additional keyword arguments to pass to http_request().
Returns:	The HTTP response for the request.
Return type:	HostingServiceHTTPResponse
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_put(url, body=None, fields=None, files=None, content_type=None, headers=None, *args, **kwargs)[source]¶

Perform an HTTP PUT on the given URL.

New in version 4.0.

Parameters:	url (unicode) – The URL to perform the request on. body (bytes, optional) – The request body. if not provided, it will be generated from the fields and files arguments. fields (dict, optional) – Form fields to use to generate the request body. This argument will only be used if body is None. files (dict, optional) – Files to use to generate the request body. This argument will only be used if body is None. content_type (unicode, optional) – The content type of the request. If provided, it will be appended as the Content-Type header. headers (dict, optional) – Extra headers to include with the request. *args (tuple) – Additional positional arguments to pass to http_request(). **kwargs (dict) – Additional keyword arguments to pass to http_request().
Returns:	The HTTP response for the request.
Return type:	HostingServiceHTTPResponse
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_request(url, body=None, headers=None, method=u'GET', **kwargs)[source]¶

Perform an HTTP request, processing and handling results.

This constructs an HTTP request based on the specified criteria, returning the resulting data and headers or raising a suitable error.

In most cases, callers will use one of the wrappers, like http_get() or http_post(). Calling this directly is useful if working with non-standard HTTP methods.

Subclasses can control the behavior of HTTP requests through several related methods:

• get_http_credentials() - Return credentials for use in the HTTP request.

• build_http_request()

  • Build the HostingServiceHTTPRequest object.

• open_http_request() - Performs the actual HTTP request.

• process_http_response() - Performs post-processing on a response from the service, or raises

  an error.

• process_http_error() - Processes a raised exception, handling it in some form or

  converting it into another error.

See those methods for more information.

Changed in version 4.0: This now returns a HostingServiceHTTPResponse instead of a 2-tuple. The response can be treated as a 2-tuple for older code.

Parameters:	url (unicode) – The URL to open. body (bytes, optional) – The request body. headers (dict, optional) – Headers to include in the request. method (unicode, optional) – The HTTP method to use to perform the request. **kwargs (dict) – Additional keyword arguments to pass to build_http_request().
Returns:	The HTTP response for the request.
Return type:	HostingServiceHTTPResponse
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – There was an error performing the request, and the result is a raw HTTP error.

get_http_credentials(account, username=None, password=None, **kwargs)[source]¶

Return credentials used to authenticate with the service.

Subclasses can override this to return credentials based on the account or the values passed in when performing the HTTP request. The resulting dictionary contains keys that will be processed in build_http_request().

There are a few supported keys that subclasses will generally want to return:

username:

The username, typically for use in HTTP Basic Auth or HTTP Digest Auth.

password:

The accompanying password.

header:

A dictionary of authentication headers to add to the request.

By default, this will return a username and password based on the request (if those values are provided by the caller).

Parameters:	account (reviewboard.hostingsvcs.models.HostingServiceAccount) – The stored authentication data for the service. username (unicode, optional) – An explicit username passed by the caller. This will override the data stored in the account, if both a username and password are provided. password (unicode, optional) – An explicit password passed by the caller. This will override the data stored in the account, if both a username and password are provided. **kwargs (dict, unused) – Additional keyword arguments passed in when making the HTTP request.
Returns:	A dictionary of credentials for the request.
Return type:	dict

open_http_request(request)[source]¶

Perform a raw HTTP request and return the result.

This is not meant to be called directly. Please use one of the following methods instead:

• http_delete()
• http_get()
• http_head()
• http_post()
• http_put()
• http_request()

Parameters:	request (HostingServiceHTTPRequest) – The HTTP request to open.
Returns:	The successful response information from the server.
Return type:	HostingServiceHTTPResponse
Raises:	urllib2.URLError – There was an error performing a request on the URL.

build_http_request(credentials, **kwargs)[source]¶

Build a request object for an HTTP request.

This constructs a HostingServiceHTTPRequest containing the information needed to perform the HTTP request by passing the provided keyword arguments to the the constructor.

If username and password are provided in credentials, this will also add a HTTP Basic Auth header (if use_http_basic_auth is set) and HTTP Digest Auth Header (if use_http_digest_auth is set).

Subclasses can override this to change any behavior as needed. For instance, adding other headers or authentication schemes.

Parameters:	credentials (dict) – The credentials used for the request. **kwargs (dict, unused) – Keyword arguments for the HostingServiceHTTPRequest instance.
Returns:	The resulting request object for use in the HTTP request.
Return type:	HostingServiceHTTPRequest

process_http_response(response)[source]¶

Process an HTTP response and return a result.

This can be used by subclasses to modify a response before it gets back to the caller. It can also raise a urllib2.URLError (which will get processed by process_http_error()), or a HostingServiceError.

By default, the response is returned as-is.

Parameters:	response (HostingServiceHTTPResponse) – The response to process.
Returns:	The resulting response.
Return type:	HostingServiceHTTPResponse

process_http_error(request, e)[source]¶

Process an HTTP error, possibly raising a result.

This will look at the error, possibly raising a more suitable exception in its place. By default, it supports handling SSL signature verification failures.

Subclasses can override this to provide more specific errors as needed by the hosting service implementation. They should always call the parent method as well.

If there’s no specific exception, this should just return, allowing the original exception to be raised.

Parameters:	request (HostingServiceHTTPRequest) – The request that resulted in an error. e (urllib2.URLError) – The error to process.
Raises:	reviewboard.scmtools.errors.UnverifiedCertificateError – The SSL certificate was not able to be verified.

json_delete(*args, **kwargs)[source]¶

Perform an HTTP DELETE and interpret the results as JSON.

Deprecated since version 4.0: Use http_delete() instead, and access the json attribute on the response for the JSON payload.

Parameters:	*args (tuple) – Additional positional arguments to pass to http_delete(). **kwargs (dict) – Additional keyword arguments to pass to http_delete().
Returns:	A tuple of: The JSON data (in the appropriate type) The response headers (dict, with keys and values as native strings)
Return type:	tuple
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – When there is an error communicating with the URL.

json_get(*args, **kwargs)[source]¶

Perform an HTTP GET and interpret the results as JSON.

Deprecated since version 4.0: Use http_get() instead, and access the json attribute on the response for the JSON payload.

Parameters:	*args (tuple) – Additional positional arguments to pass to http_get(). **kwargs (dict) – Additional keyword arguments to pass to http_get().
Returns:	A tuple of: The JSON data (in the appropriate type) The response headers (dict, with keys and values as native strings)
Return type:	tuple
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – When there is an error communicating with the URL.

json_post(*args, **kwargs)[source]¶

Perform an HTTP POST and interpret the results as JSON.

Deprecated since version 4.0: Use http_post() instead, and access the json attribute on the response for the JSON payload.

Parameters:	*args (tuple) – Additional positional arguments to pass to http_post(). **kwargs (dict) – Additional keyword arguments to pass to http_post().
Returns:	A tuple of: The JSON data (in the appropriate type) The response headers (dict, with keys and values as native strings)
Return type:	tuple
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error performing the request, and the error has been translated to a more specific hosting service error. urllib2.URLError – When there is an error communicating with the URL.

static build_form_data(fields, files=None)[source]¶

Encode data for use in an HTTP POST.

Parameters:	fields (dict) – A mapping of field names (unicode) to values. files (dict, optional) – A mapping of field names (unicode) to files (dict).
Returns:	A tuple of: The request content (bytes). The request content type (unicode).
Return type:	tuple

class HostingService(account)[source]¶

Bases: object

An interface to a hosting service for repositories and bug trackers.

HostingService subclasses are used to more easily configure repositories and to make use of third party APIs to perform special operations not otherwise usable by generic repositories.

A HostingService can specify forms for repository and bug tracker configuration.

It can also provide a list of repository “plans” (such as public repositories, private repositories, or other types available to the hosting service), along with configuration specific to the plan. These plans will be available when configuring the repository.

hosting_service_id = None[source]¶

The unique ID of the hosting service.

This should be lowercase, and only consist of the characters a-z, 0-9, _, and -.

New in version 3.0.16: This should now be set on all custom hosting services. It will be required in Review Board 4.0.

name = None[source]¶

plans = None[source]¶

supports_bug_trackers = False[source]¶

supports_post_commit = False[source]¶

supports_repositories = False[source]¶

supports_ssh_key_association = False[source]¶

supports_two_factor_auth = False[source]¶

supports_list_remote_repositories = False[source]¶

has_repository_hook_instructions = False[source]¶

visible = True[source]¶

Whether this service should be shown as an available option.

This should be set to False when a service is no longer available to use, and should be hidden from repository configuration. The implementation can then be largely stubbed out. Users will see a message in the repository configuration page.

New in version 3.0.17.

self_hosted = False[source]¶

repository_url_patterns = None[source]¶

client_class[source]¶

alias of HostingServiceClient

auth_form = None[source]¶

Optional form used to configure authentication settings for an account.

needs_authorization = False[source]¶

form = None[source]¶

fields = [][source]¶

repository_fields = {}[source]¶

bug_tracker_field = None[source]¶

supported_scmtools = [][source]¶

A list of SCMTools IDs or names that are supported by this service.

This should contain a list of SCMTool IDs that this service can work with. For backwards-compatibility, it may instead contain a list of SCMTool names (corresponding to database registration names).

This may also be specified per-plan in the plans.

Changed in version 3.0.16: Added support for SCMTool IDs. A future version will deprecate using SCMTool names here.

visible_scmtools = None[source]¶

A list of SCMTool IDs that are visible when configuring the service.

This should contain a list of SCMTool IDs that this service will show when configuring a repository. It can be used to offer continued legacy support for an SCMTool without offering it when creating new repositories. If not specified, all SCMTools listed in supported_scmtools are assumed to be visible.

If explicitly set, this should always be equal to or a subset of supported_scmtools.

This may also be specified per-plan in the plans.

New in version 3.0.17.

__init__(account)[source]¶

Initialize the hosting service.

Parameters:	account (reviewboard.hostingsvcs.models.HostingServiceAccount) – The account to use with the service.

is_authorized()[source]¶

Return whether or not the account is currently authorized.

An account may no longer be authorized if the hosting service switches to a new API that doesn’t match the current authorization records. This function will determine whether the account is still considered authorized.

Returns:	Whether or not the associated account is authorized.
Return type:	bool

get_password()[source]¶

Return the raw password for this hosting service.

Not all hosting services provide this, and not all would need it. It’s primarily used when building a Subversion client, or other SCMTools that still need direct access to the repository itself.

Returns:	The password.
Return type:	unicode

is_ssh_key_associated(repository, key)[source]¶

Return whether or not the key is associated with the repository.

If the given key is present amongst the hosting service’s deploy keys for the given repository, then it is considered to be associated.

Sub-classes should implement this when the hosting service supports SSH key association.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository the key must be associated with. key (paramiko.PKey) – The key to check for association.
Returns:	Whether or not the key is associated with the repository.
Return type:	bool
Raises:	reviewboard.hostingsvcs.errors.SSHKeyAssociationError – If an error occured during communication with the hosting service.

associate_ssh_key(repository, key)[source]¶

Associate an SSH key with a given repository.

Sub-classes should implement this when the hosting service supports SSH key association.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository to associate the key with. key (paramiko.PKey) – The key to add to the repository’s list of deploy keys.
Raises:	reviewboard.hostingsvcs.errors.SSHKeyAssociationError – If an error occured during key association.

authorize(username, password, hosting_url, credentials, two_factor_auth_code=None, local_site_name=None, *args, **kwargs)[source]¶

Authorize an account for the hosting service.

Parameters:

username (unicode) – The username for the account. password (unicode) – The password for the account. hosting_url (unicode) – The hosting URL for the service, if self-hosted. credentials (dict) – All credentials provided by the authentication form. This will contain the username, password, and anything else provided by that form. two_factor_auth_code (unicode, optional) – The two-factor authentication code provided by the user. local_site_name (unicode, optional) – The Local Site name, if any, that the account should be bound to. *args (tuple) – Extra unused positional arguments. **kwargs (dict) – Extra keyword arguments containing values from the repository’s configuration.

Raises:

reviewboard.hostingsvcs.errors.AuthorizationError – The credentials provided were not valid. reviewboard.hostingsvcs.errors.TwoFactorAuthCodeRequiredError – A two-factor authentication code is required to authorize this account. The request must be retried with the same credentials and with the two_factor_auth_code parameter provided.

check_repository(path, username, password, scmtool_class, local_site_name, *args, **kwargs)[source]¶

Checks the validity of a repository configuration.

This performs a check against the hosting service or repository to ensure that the information provided by the user represents a valid repository.

This is passed in the repository details, such as the path and raw credentials, as well as the SCMTool class being used, the LocalSite’s name (if any), and all field data from the HostingServiceForm as keyword arguments.

Parameters:

path (unicode) – The repository URL. username (unicode) – The username to use. password (unicode) – The password to use. scmtool_class (type) – The subclass of SCMTool that should be used. local_site_name (unicode) – The name of the local site associated with the repository, or None. *args (tuple) – Additional positional arguments, unique to each hosting service. **kwargs (dict) – Additional keyword arguments, unique to each hosting service.

Raises:

reviewboard.hostingsvcs.errors.RepositoryError – The repository is not valid.

get_file(repository, path, revision, *args, **kwargs)[source]¶

Return the requested file.

Files can only be returned from hosting services that support repositories.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository to retrieve the file from. path (unicode) – The file path. revision (unicode) – The revision the file should be retrieved from. *args (tuple) – Ignored positional arguments. **kwargs (dict) – Additional keyword arguments to pass to the SCMTool.
Returns:	The contents of the file.
Return type:	bytes
Raises:	NotImplementedError – If this hosting service does not support repositories.

get_file_exists(repository, path, revision, *args, **kwargs)[source]¶

Return whether or not the given path exists in the repository.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository to check for file existence. path (unicode) – The file path. revision (unicode) – The revision to check for file existence. *args (tuple) – Ignored positional arguments. **kwargs (dict) – Additional keyword arguments to be passed to the SCMTool.
Returns:	Whether or not the file exists at the given revision in the repository.
Return type:	bool
Raises:	NotImplementedError – If this hosting service does not support repositories.

get_branches(repository)[source]¶

Return a list of all branches in the repositories.

This should be implemented by subclasses, and is expected to return a list of Branch objects. One (and only one) of those objects should have the “default” field set to True.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository for which branches should be returned.
Returns:	The branches.
Return type:	list of reviewboard.scmtools.core.Branch
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error fetching branches.

get_commits(repository, branch=None, start=None)[source]¶

Return a list of commits backward in history from a given point.

This should be implemented by subclasses, and is expected to return a list of Commit objects (usually 30, but this is flexible depending on the limitations of the APIs provided.

This can be called multiple times in succession using the “parent” field of the last entry as the start parameter in order to paginate through the history of commits in the repository.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository to retrieve commits from. branch (unicode, optional) – The branch to retrieve from. If this is not provided, the default branch will be used. start (unicode, optional) – An optional starting revision. If this is not provided, the most recent commits will be returned.
Returns:	The retrieved commits.
Return type:	list of reviewboard.scmtools.core.Commit
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error fetching commits.

get_change(repository, revision)[source]¶

Return an individual change.

This method should be implemented by subclasses.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository to get the change from. revision (unicode) – The revision to retrieve.
Returns:	The change.
Return type:	reviewboard.scmtools.core.Commit
Raises:	reviewboard.hostingsvcs.errors.HostingServiceError – There was an error fetching the commit.

get_remote_repositories(owner=None, owner_type=None, filter_type=None, start=None, per_page=None, **kwargs)[source]¶

Return a list of remote repositories for the owner.

This method should be implemented by subclasses.

Parameters:	owner (unicode, optional) – The owner of the repositories. This is usually a username. owner_type (unicode, optional) – A hosting service-specific indicator of what the owner is (such as a user or a group). filter_type (unicode, optional) – Some hosting service-specific criteria to filter by. start (int, optional) – The index to start at. per_page (int, optional) – The number of results per page.
Returns:	A paginator for the returned repositories.
Return type:	reviewboard.hostingsvcs.utils.APIPaginator

get_remote_repository(repository_id)[source]¶

Return the remote repository for the ID.

This method should be implemented by subclasses.

Parameters:	repository_id (unicode) – The repository’s identifier. This is unique to each hosting service.
Returns:	The remote repository.
Return type:	reviewboard.hostingsvcs.repository.RemoteRepository
Raises:	django.core.excptions.ObjectDoesNotExist – If the remote repository does not exist.

normalize_patch(repository, patch, filename, revision)[source]¶

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

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

By default, this passes along the normalization to the repository’s SCMTool.

Parameters:	repository (reviewboard.scmtools.models.Repository) – The repository the patch is meant to apply to. patch (bytes) – The diff/patch file to normalize. filename (unicode) – The name of the file being changed in the diff. revision (unicode) – The revision of the file being changed in the diff.
Returns:	The resulting diff/patch file.
Return type:	bytes

classmethod get_repository_fields(username, hosting_url, plan, tool_name, field_vars)[source]¶

Return the repository fields based on the given plan and tool.

If the plan argument is specified, that will be used to fill in some tool-specific field values. Otherwise they will be retrieved from the HostingService’s defaults.

Parameters:	username (unicode) – The username. hosting_url (unicode) – The URL of the repository. plan (unicode) – The name of the plan. tool_name (unicode) – The name of the SCMTool. field_vars (dict) – The field values from the hosting service form.
Returns:	The filled in repository fields.
Return type:	dict
Raises:	KeyError – The provided plan is not valid for the hosting service.

get_repository_hook_instructions(request, repository)[source]¶

Return instructions for setting up incoming webhooks.

Subclasses can override this (and set has_repository_hook_instructions = True on the subclass) to provide instructions that administrators can see when trying to configure an incoming webhook for the hosting service.

Parameters:	request (django.http.HttpRequest) – The current HTTP request. repository (reviewboard.scmtools.models.Repository) – The repository for webhook setup instructions.
Returns:	Rendered and escaped HTML for displaying to the user.
Return type:	django.utils.text.SafeText

classmethod get_bug_tracker_requires_username(plan=None)[source]¶

Return whether or not the bug tracker requires usernames.

Parameters:	plan (unicode, optional) – The name of the plan associated with the account.
Raises:	NotImplementedError – If the hosting service does not support bug tracking.

classmethod get_bug_tracker_field(plan, field_vars)[source]¶

Return the bug tracker field for the given plan.

Parameters:	plan (unicode) – The name of the plan associated with the account. field_vars (dict) – The field values from the hosting service form.
Returns:	The value of the bug tracker field.
Return type:	unicode

Raises

KeyError:

The provided plan is not valid for the hosting service.

classmethod get_field(plan, name, default=None)[source]¶

Return the value of the field for the given plan.

If plan is not None, the field will be looked up in the plan configuration for the service. Otherwise the hosting service’s default value will be used.

Parameters:	plan (unicode) – The plan name. name (unicode) – The field name. default (unicode, optional) – A default value if the field is not present.
Returns:	The field value.
Return type:	unicode

class HostingServiceRegistry[source]¶

Bases: reviewboard.registries.registry.EntryPointRegistry

A registry for managing hosting services.

entry_point = u'reviewboard.hosting_services'[source]¶

lookup_attrs = [u'hosting_service_id'][source]¶

errors = {u'already_registered': u'"%(item)s" is already a registered hosting service.', u'load_entry_point': u'Unable to load repository hosting service %(entry_point)s: %(error)s.', u'not_registered': u'"%(attr_value)s" is not a registered hosting service.'}[source]¶

__init__()[source]¶

unregister(service)[source]¶

Unregister a hosting service.

This will remove all registered URLs that the hosting service has defined.

Parameters:	service (type) – The HostingService subclass.

process_value_from_entry_point(entry_point)[source]¶

Load the class from the entry point.

The id attribute will be set on the class from the entry point’s name.

Parameters:	entry_point (pkg_resources.EntryPoint) – The entry point.
Returns:	The HostingService subclass.
Return type:	type

register(service)[source]¶

Register a hosting service.

This also adds the URL patterns defined by the hosting service. If the hosting service has a HostingService.repository_url_patterns attribute that is non-None, they will be automatically added.

Parameters:	service (type) – The HostingService subclass.

get_hosting_services()[source]¶

Return the list of hosting services.

Returns:	The HostingService subclasses.
Return type:	list

get_hosting_service(name)[source]¶

Return the hosting service with the given name.

If the hosting service is not found, None will be returned.

register_hosting_service(name, cls)[source]¶

Register a custom hosting service class.

A name can only be registered once. A KeyError will be thrown if attempting to register a second time.

Parameters:	name (unicode) – The name of the hosting service. If the hosting service already has an ID assigned as hosting_service_id, that value should be passed. Note that this will also override any existing ID on the service. cls (type) – The hosting service class. This should be a subclass of HostingService.

unregister_hosting_service(name)[source]¶

Unregister a previously registered hosting service.

Parameters:	name (unicode) – The name of the hosting service.

URLRequest[source]¶

Legacy name for HostingServiceHTTPRequest

Deprecated since version 4.0: This has been replaced by HostingServiceHTTPRequest.

alias of reviewboard.hostingsvcs.service.HostingServiceHTTPRequest