reviewboard.hostingsvcs.base.client¶

Base communication client support for hosting services.

New in version 6.0: This replaces the client code in the old reviewboard.hostingsvcs.service module.

class HostingServiceClient(hosting_service: BaseHostingService)[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.

Hosting service implementations 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.

Changed in version 6.0:

Moved from reviewboard.hostingsvcs.service to reviewboard.hostingsvcs.base.client.
Deprecated JSON utility functions now emit deprecation warnings and will be removed in Review Board 7.

http_request_cls¶

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¶

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

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

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: BaseHostingService) → None[source]¶

Initialize the client.

Parameters:: hosting_service (reviewboard.hostingsvcs.base.hosting_service.BaseHostingService) – The hosting service that is using this client.

hosting_service: BaseHostingService¶

The hosting service that owns this client.

Type:: The hosting service that owns this client.

http_delete(url: str, headers: Optional[HTTPHeaders] = None, *args, **kwargs) → HostingServiceHTTPResponse[source]¶

Perform an HTTP DELETE on the given URL.

Changed in version 4.0: This now returns a HostingServiceHTTPResponse instead of a 2-tuple.

Parameters:

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

reviewboard.hostingsvcs.base.http.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.
urllib.error.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_get(url: str, headers: Optional[HTTPHeaders] = None, *args, **kwargs) → HostingServiceHTTPResponse[source]¶

Perform an HTTP GET on the given URL.

Changed in version 4.0: This now returns a reviewboard.hostingsvcs.base.http. HostingServiceHTTPResponse instead of a 2-tuple.

Parameters:

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

reviewboard.hostingsvcs.base.http.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.
urllib.error.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_head(url: str, headers: Optional[HTTPHeaders] = None, *args, **kwargs) → HostingServiceHTTPResponse[source]¶

Perform an HTTP HEAD on the given URL.

New in version 4.0.

Parameters:

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

reviewboard.hostingsvcs.base.http.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.
urllib.error.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_post(url: str, body: Optional[bytes] = None, fields: Optional[FormFields] = None, files: Optional[UploadedFiles] = None, content_type: Optional[str] = None, headers: Optional[HTTPHeaders] = None, *args, **kwargs) → HostingServiceHTTPResponse[source]¶

Perform an HTTP POST on the given URL.

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

Parameters:

url (str) – 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 (str, 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:

reviewboard.hostingsvcs.base.http.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.
urllib.error.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_put(url: str, body: Optional[bytes] = None, fields: Optional[FormFields] = None, files: Optional[UploadedFiles] = None, content_type: Optional[str] = None, headers: Optional[HTTPHeaders] = None, *args, **kwargs) → HostingServiceHTTPResponse[source]¶

Perform an HTTP PUT on the given URL.

New in version 4.0.

Parameters:

url (str) – 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 (str, 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:

reviewboard.hostingsvcs.base.http.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.
urllib.error.URLError – There was an error performing the request, and the result is a raw HTTP error.

http_request(url: str, body: Optional[bytes] = None, headers: Optional[HTTPHeaders] = None, method: str = 'GET', **kwargs) → HostingServiceHTTPResponse[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 reviewboard.hostingsvcs.base.http. 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 reviewboard.hostingsvcs.base.http. HostingServiceHTTPResponse instead of a 2-tuple.

Parameters:

url (str) – The URL to open.
body (bytes, optional) – The request body.
headers (dict, optional) – Headers to include in the request.
method (str, 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:

reviewboard.hostingsvcs.base.http.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.
urllib.error.URLError – There was an error performing the request, and the result is a raw HTTP error.

get_http_credentials(account: HostingServiceAccount, username: Optional[str] = None, password: Optional[str] = None, **kwargs) → HostingServiceCredentials[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:

Keys:

username (str) – The username, typically for use in HTTP Basic Auth or HTTP Digest Auth.
password (str) – The accompanying password.
header (dict) – 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 (str, 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 (str, 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: HostingServiceHTTPRequest) → HostingServiceHTTPResponse[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 (reviewboard.hostingsvcs.base.http.HostingServiceHTTPRequest) – The HTTP request to open.
Returns:: The successful response information from the server.
Return type:: reviewboard.hostingsvcs.base.http.HostingServiceHTTPResponse
Raises:: urllib.error.URLError – There was an error performing a request on the URL.

build_http_request(credentials: HostingServiceCredentials, **kwargs) → HostingServiceHTTPRequest[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 reviewboard.hostingsvcs. base.http.HostingServiceHTTPRequest instance.

Returns:

The resulting request object for use in the HTTP request.

Return type:

HostingServiceHTTPRequest

process_http_response(response: HostingServiceHTTPResponse) → HostingServiceHTTPResponse[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 urllib.error.URLError (which will get processed by process_http_error()), or a HostingServiceError.

By default, the response is returned as-is.

Parameters:: response (reviewboard.hostingsvcs.base.http.HostingServiceHTTPResponse) – The response to process.
Returns:: The resulting response.
Return type:: reviewboard.hostingsvcs.base.http.HostingServiceHTTPResponse

process_http_error(request: HostingServiceHTTPRequest, e: URLError) → None[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 (reviewboard.hostingsvcs.base.http.HostingServiceHTTPRequest) – The request that resulted in an error.
e (urllib.error.URLError) – The error to process.

Raises:

reviewboard.scmtools.errors.UnverifiedCertificateError – The SSL certificate was not able to be verified.

json_delete(*args, **kwargs) → Tuple[JSONValue, HTTPHeaders][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 2-tuple of:

Tuple:

0 (object) – The JSON data (in the appropriate type).
1 (dict) – The HTTP response headers.

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.
urllib.error.URLError – When there is an error communicating with the URL.

json_get(*args, **kwargs) → Tuple[JSONValue, HTTPHeaders][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 2-tuple of:

Tuple:

0 (object) – The JSON data (in the appropriate type).
1 (dict) – The HTTP response headers.

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.
urllib.error.URLError – When there is an error communicating with the URL.

json_post(*args, **kwargs) → Tuple[JSONValue, HTTPHeaders][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 2-tuple of:

Tuple:

0 (object) – The JSON data (in the appropriate type).
1 (dict) – The HTTP response headers.

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.
urllib.error.URLError – When there is an error communicating with the URL.

static build_form_data(fields: Optional[FormFields], files: Optional[UploadedFiles] = None) → Tuple[bytes, str][source]¶

Encode data for use in an HTTP POST.

Parameters:

fields (dict) – A mapping of field names to values.
files (dict, optional) – A mapping of field names to files (dict).

Returns:

Tuple:

0 (bytes) – The body to post.
1 (dict) – The HTTP response headers.

Return type:

A 2-tuple of

__annotations__ = {'hosting_service': 'BaseHostingService', 'http_request_cls': 'Type[HostingServiceHTTPRequest]', 'http_response_cls': 'Type[HostingServiceHTTPResponse]', 'use_http_basic_auth': 'bool', 'use_http_digest_auth': 'bool'}¶