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
toreviewboard.hostingsvcs.base.client
.Deprecated JSON utility functions now emit deprecation warnings and will be removed in Review Board 8.
- 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 tohttp_request()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_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 tohttp_request()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_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 tohttp_request()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_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
andfiles
arguments.fields (
dict
, optional) –Form fields to use to generate the request body.
This argument will only be used if
body
isNone
.files (
dict
, optional) –Files to use to generate the request body.
This argument will only be used if
body
isNone
.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 tohttp_request()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_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
andfiles
arguments.fields (
dict
, optional) –Form fields to use to generate the request body.
This argument will only be used if
body
isNone
.files (
dict
, optional) –Files to use to generate the request body.
This argument will only be used if
body
isNone
.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 tohttp_request()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_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()
orhttp_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 thereviewboard.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:
- 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:
By default, this will return a
username
andpassword
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:
- 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:
- 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
andpassword
are provided incredentials
, this will also add a HTTP Basic Auth header (ifuse_http_basic_auth
is set) and HTTP Digest Auth Header (ifuse_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 thereviewboard.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 byprocess_http_error()
), or aHostingServiceError
.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 thejson
attribute on the response for the JSON payload.- Parameters:
*args (
tuple
) – Additional positional arguments to pass tohttp_delete()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_delete()
.
- Returns:
A 2-tuple of:
- Return type:
- 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 thejson
attribute on the response for the JSON payload.- Parameters:
*args (
tuple
) – Additional positional arguments to pass tohttp_get()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_get()
.
- Returns:
A 2-tuple of:
- Return type:
- 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 thejson
attribute on the response for the JSON payload.- Parameters:
*args (
tuple
) – Additional positional arguments to pass tohttp_post()
.**kwargs (
dict
) – Additional keyword arguments to pass tohttp_post()
.
- Returns:
A 2-tuple of:
- Return type:
- 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.
- __annotations__ = {'hosting_service': 'BaseHostingService', 'http_request_cls': 'Type[HostingServiceHTTPRequest]', 'http_response_cls': 'Type[HostingServiceHTTPResponse]', 'use_http_basic_auth': 'bool', 'use_http_digest_auth': 'bool'}¶