rbtools.api.request¶

Support for forming requests to a Review Board server.

Classes

class rbtools.api.request.HttpRequest(url: str, method: str = 'GET', query_args: Dict[str, Union[bool, int, float, bytes, str]] = {}, headers: Dict[str, str] = {})[source]¶

Bases: object

A high-level HTTP request.

This is used to construct an HTTP request to a Review Board server. It takes in the URL, HTTP method, any query arguments and headers needed to perform the request, and provides methods for building a request payload compatible with the Review Board API.

Instances are intentionally generic and not tied to urllib2, providing API stability and a path toward eventually interfacing with other HTTP backends.

__init__(url: str, method: str = 'GET', query_args: Dict[str, Union[bool, int, float, bytes, str]] = {}, headers: Dict[str, str] = {}) → None[source]¶

Initialize the HTTP request.

Parameters:

• url (bytes or str) – The URL to request.

• method (bytes or str, optional) – The HTTP method to send to the server.

• query_args (dict, optional) – Any query arguments to add to the URL.

• headers (dict, optional) – Any HTTP headers to provide in the request.

headers: Dict[str, str]¶

HTTP headers to provide when making the request

Type: dict

url: str¶

The URL te request

Type: str

encode_url_key(key: str) → str[source]¶

Encode the given key for inclusion in a URL.

Parameters:

key (str) – The key that is being encoded.

Raises:

ValueError – The given key was neither a unicode string or byte string.

Returns:

The key encoded as a unicode string.

Return type:

str

encode_url_value(key: Union[bytes, str], value: Union[bool, int, float, bytes, str]) → str[source]¶

Encode the given value for inclusion in a URL.

Parameters:

• key (str) – The field name for which the value is being encoded. This argument is only used to generate an error message.

• value (object) – The value to be encoded.

Raises:

ValueError – The given value could not be encoded.

Returns:

The value encoded as a unicode string.

Return type:

str

property method: str[source]¶

The HTTP method to send to the server.

add_field(name: Union[bytes, str], value: Union[bytes, str]) → None[source]¶

Add a form-data field for the request.

Changed in version 4.0: Values of types other than bytes or str are now deprecated, and will be removed in 5.0.

Parameters:

• name (bytes or str) – The name of the field.

• value (bytes or str) –

  The value to send for the field.

  For backwards-compatibility, other values will be converted to strings. This will be removed in 5.0.

add_file(name: Union[bytes, str], filename: Union[bytes, str], content: Union[bytes, str], mimetype: Optional[Union[bytes, str]] = None) → None[source]¶

Add an uploaded file for the request.

Parameters:

• name (bytes or str) – The name of the field representing the file.

• filename (bytes or str) – The filename.

• content (bytes or str) – The contents of the file.

• mimetype (bytes or str, optional) – The optional mimetype of the content. If not provided, it will be guessed.

encode_multipart_formdata() → Tuple[Optional[str], Optional[bytes]][source]¶

Encode the request into a multi-part form-data payload.

Returns:

A tuple containing:

• The content type (str)

• The form-data payload (bytes)

If there are no fields or files in the request, both values will be None.

Return type:

tuple

class rbtools.api.request.RBToolsHTTPSConnection(host, port=None, *, timeout=<object object>, source_address=None, context=None, blocksize=8192)[source]¶

Bases: HTTPSConnection

Connection class for HTTPS connections.

This is a specialization of the default HTTPS connection class that provides custom error handling for SSL errors.

New in version 4.1.

connect(*args, **kwargs) → Any[source]¶

Connect to the server.

This will catch SSL errors and wrap them with our own error classes.

Parameters:

• *args (tuple) – Positional arguments to pass to the parent method.

• **kwargs (dict) – Keyword arguments to pass to the parent method.

Returns:

The result from the parent method.

Return type:

object

Raises:

rbtools.api.errors.ServerInterfaceSSLError – An SSL error occurred during communication. Details will be in the error message.

class rbtools.api.request.RBToolsHTTPSHandler(debuglevel=None, context=None, check_hostname=None)[source]¶

Bases: HTTPSHandler

Request/response handler for HTTPS connections.

This wraps the default HTTPS handler, passing in a specialized HTTPS connection class used to generate more useful SSL-related errors.

New in version 4.1.

do_open(http_class, *args, **kwargs) → HTTPResponse[source]¶

Open a connection to the server.

Parameters:

• http_class (type, unused) – The original HTTPS connection class. This will be replaced with our own.

• *args (tuple) – Positional arguments to pass to the parent method.

• **kwargs (dict) – Keyword arguments to pass to the parent method.

Returns:

The resulting HTTP response.

Return type:

http.client.HTTPResponse

Raises:

rbtools.api.errors.ServerInterfaceSSLError – An SSL error occurred during communication. Details will be in the error message.

class rbtools.api.request.Request(url: str, body: Optional[bytes] = b'', headers: Dict[str, str] = {}, method: str = 'PUT')[source]¶

Bases: Request

A request which contains a method attribute.

__init__(url: str, body: Optional[bytes] = b'', headers: Dict[str, str] = {}, method: str = 'PUT') → None[source]¶

Initialize the request.

Parameters:

• url (str) – The URL to make the request at.

• body (bytes, optional) – The body to send with the request.

• headers (dict, optional) – The headers to send with the request.

• method (str, optional) – The HTTP method to use.

method: str¶

The HTTP method to use.

Type: str

get_method() → str[source]¶

Return the HTTP method.

Returns:

The HTTP method.

Return type:

str

class rbtools.api.request.ReviewBoardHTTPErrorProcessor[source]¶

Bases: HTTPErrorProcessor

Processes HTTP error codes.

Python’s built-in error processing understands 2XX responses as successful, but processes 3XX as an error. This handler ensures that all valid responses from the API are processed as such.

http_response(request, response)[source]¶

https_response(request, response)[source]¶

class rbtools.api.request.ReviewBoardHTTPPasswordMgr(reviewboard_url: str, rb_user: Optional[str] = None, rb_pass: Optional[str] = None, api_token: Optional[str] = None, auth_callback: Optional[Callable[[...], Tuple[str, str]]] = None, otp_token_callback: Optional[Callable[[str, str], str]] = None)[source]¶

Bases: HTTPPasswordMgr

Adds HTTP authentication support for URLs.

__init__(reviewboard_url: str, rb_user: Optional[str] = None, rb_pass: Optional[str] = None, api_token: Optional[str] = None, auth_callback: Optional[Callable[[...], Tuple[str, str]]] = None, otp_token_callback: Optional[Callable[[str, str], str]] = None) → None[source]¶

Initialize the password manager.

Parameters:

• reviewboard_url (str) – The URL of the Review Board server.

• rb_user (str, optional) – The username to authenticate with.

• rb_pass (str, optional) – The password to authenticate with.

• api_token (str, optional) – The API token to authenticate with. If present, this takes priority over the username and password.

• auth_callback (callable, optional) – A callback to prompt the user for their username and password.

• otp_token_callback (callable, optional) – A callback to prompt the user for their two-factor authentication code.

find_user_password(realm: str, uri: str) → Tuple[Optional[str], Optional[str]][source]¶

Return the username and password for the given realm.

Parameters:

• realm (str) – The HTTP Basic authentication realm.

• uri (str) – The URI being accessed.

Returns:

A 2-tuple containing:

Tuple:

• 0 (str) – The username to use.

• 1 (str) – The password to use.

Return type:

tuple

get_otp_token(uri: str, method: str) → Optional[str][source]¶

Return the two-factor authentication code.

Parameters:

• uri (str) – The URI being accessed.

• method (str) – The HTTP method being used.

Returns:

The user’s two-factor authentication code, if available.

Return type:

str

class rbtools.api.request.PresetHTTPAuthHandler(url: str, password_mgr: ReviewBoardHTTPPasswordMgr)[source]¶

Bases: BaseHandler

Handler that presets the use of HTTP Basic Auth.

handler_order = 480[source]¶

AUTH_HEADER = 'Authorization'[source]¶

__init__(url: str, password_mgr: ReviewBoardHTTPPasswordMgr) → None[source]¶

Initialize the handler.

Parameters:

• url (str) – The URL of the Review Board server.

• password_mgr (ReviewBoardHTTPPasswordMgr) – The password manager to use for requests.

reset(*, username: Optional[str] = None, password: Optional[str] = None, api_token: Optional[str] = None) → None[source]¶

Reset the stored authentication credentials.

Changed in version 5.0: Added an optional api_token parameter and made the username and password parameters optional to allow authentication with either a username and password or API token.

Parameters:

• username (str, optional) – The username to use for authentication. If None and no API token is provided, this will log out the user.

• password (str, optional) – The password to use for authentication. If None and no API token is provided, this will log out the user.

• api_token (str, optional) – The API token to use for authentication. If None and no username and password are provided, this will log out the user.

http_request(request: Request) → Request[source]¶

Modify an HTTP request with authentication information.

Parameters:

request (rbtools.api.request.Request) – The HTTP request to make.

Returns:

The HTTP request, with authentication headers added.

Return type:

rbtools.api.request.Request

https_request(request: Request) → Request[source]¶

Modify an HTTP request with authentication information.

Parameters:

request (rbtools.api.request.Request) – The HTTP request to make.

Returns:

The HTTP request, with authentication headers added.

Return type:

rbtools.api.request.Request

class rbtools.api.request.ReviewBoardHTTPBasicAuthHandler(*args, **kwargs)[source]¶

Bases: HTTPBasicAuthHandler

Custom Basic Auth handler that doesn’t retry excessively.

urllib’s HTTPBasicAuthHandler retries over and over, which is useless. This subclass only retries once to make sure we’ve attempted with a valid username and password. It will then fail so we can use our own retry handler.

This also supports two-factor auth, for Review Board servers that support it. When requested by the server, the client will be prompted for a one-time password token, which would be sent generally through a mobile device. In this case, the client will prompt up to a set number of times until a valid token is entered.

OTP_TOKEN_HEADER = 'X-ReviewBoard-OTP'[source]¶

MAX_OTP_TOKEN_ATTEMPTS = 2[source]¶

passwd: ReviewBoardHTTPPasswordMgr¶

__init__(*args, **kwargs) → None[source]¶

Initialize the Basic Auth handler.

Parameters:

• *args (tuple) – Positional arguments to pass to the parent class.

• **kwargs (dict) – Keyword arguments to pass to the parent class.

http_error_auth_reqed(authreq: str, host: str, req: Request, headers: HTTPMessage) → None[source]¶

Handle an HTTP 401 Unauthorized from an API request.

This will start by checking whether a two-factor authentication token is required by the server, and which method it will be sent by (SMS or token generator application), before handing back to the parent class, which will then call into our custom retry_http_basic_auth().

Parameters:

• authreq (str) – The authentication request type.

• host (str) – The URL being accessed.

• req (rbtools.api.request.Request) – The API request being made.

• headers (http.client.HTTPMessage) – The headers sent in the Unauthorized error response.

Returns:

If attempting another request, this will be the HTTP response from that request. This will be None if not making another request.

Return type:

http.client.HTTPResponse

Raises:

urllib2.URLError – The HTTP request resulted in an error. If this is an HTTP 401 Unauthorized, it may be handled by this class again.

retry_http_basic_auth(host: str, request: Request, realm: str) → Optional[HTTPResponse][source]¶

Attempt another HTTP Basic Auth request.

This will determine if another request should be made (based on previous attempts and 2FA requirements. Based on this, it may make another attempt.

Parameters:

• host (str) – The URL being accessed.

• request (rbtools.api.request.Request) – The API request being made.

• realm (str) – The Basic Auth realm, which will be used to look up any stored passwords.

Returns:

If attempting another request, this will be the HTTP response from that request. This will be None if not making another request.

Return type:

http.client.HTTPResponse

Raises:

urllib2.URLError – The HTTP request resulted in an error. If this is an HTTP 401 Unauthorized, it may be handled by this class again.

class rbtools.api.request.CookiePolicy(*, config: RBToolsConfig, **kwargs)[source]¶

Bases: DefaultCookiePolicy

A cookie policy for cookie storage and retrieval.

By default, this uses the default cookie policy imposed by Python, which is very lax with domain lookup. If there’s a cookie for subdomain.example.com and an identical cookie for example.com, both cookies will be returned when accessing subdomain.example.com.

Strict cookie behavior can be enabled by setting COOKIES_STRICT_DOMAIN_MATCH = True in .reviewboardrc.

New in version 5.1.

__init__(*, config: RBToolsConfig, **kwargs) → None[source]¶

Initialize the cookie policy.

Parameters:

• config (rbtools.config.config.RBToolsConfig) – The loaded RBTools configuration.

• **kwargs (dict) – Keyword arguments for the parent constructor.

config: RBToolsConfig¶

The loaded RBTools configuration.

domain_return_ok(domain: str, request: Request) → bool[source]¶

Return whether a domain for a stored cookie should be used.

This will check if a stored cookie is considered valid for an HTTP request to a server based on a domain check. The behavior depends on the COOKIES_STRICT_DOMAIN_MATCH setting.

Parameters:

• domain (str) – The domain of the stored cookie.

• request (urllib.request.Request) – The HTTP request to be sent to the server.

Returns:

True if the cookie’s domain is a match and should be a candidate for the request. False if it should not be included.

Return type:

bool

class rbtools.api.request.ReviewBoardServer(url: str, cookie_file: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, api_token: Optional[str] = None, agent: Optional[str] = None, session: Optional[str] = None, disable_proxy: bool = False, auth_callback: Optional[AuthCallback] = None, otp_token_callback: Optional[OTPCallback] = None, verify_ssl: bool = True, save_cookies: bool = True, ext_auth_cookies: Optional[str] = None, ca_certs: Optional[str] = None, client_key: Optional[str] = None, client_cert: Optional[str] = None, proxy_authorization: Optional[str] = None, *, config: Optional[RBToolsConfig] = None)[source]¶

Bases: object

Represents a Review Board server we are communicating with.

Provides methods for executing HTTP requests on a Review Board server’s Web API.

The auth_callback parameter can be used to specify a callable which will be called when authentication fails. This callable will be passed the realm, and url of the Review Board server and should return a 2-tuple of username, password. The user can be prompted for their credentials using this mechanism.

__init__(url: str, cookie_file: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, api_token: Optional[str] = None, agent: Optional[str] = None, session: Optional[str] = None, disable_proxy: bool = False, auth_callback: Optional[AuthCallback] = None, otp_token_callback: Optional[OTPCallback] = None, verify_ssl: bool = True, save_cookies: bool = True, ext_auth_cookies: Optional[str] = None, ca_certs: Optional[str] = None, client_key: Optional[str] = None, client_cert: Optional[str] = None, proxy_authorization: Optional[str] = None, *, config: Optional[RBToolsConfig] = None) → None[source]¶

Initialize the server object.

Changed in version 5.1: Added the config argument.

Parameters:

• url (str) – The URL of the Review Board server.

• cookie_file (str, optional) – The name of the file to store authentication cookies in.

• username (str, optional) – The username to use for authentication.

• password (str, optional) – The password to use for authentication.

• api_token (str, optional) – An API token to use for authentication. If present, this is preferred over the username and password.

• agent (str, optional) – A User-Agent string to use for the client. If not specified, the default RBTools User-Agent will be used.

• session (str, optional) – An rbsessionid string to use for authentication.

• disable_proxy (bool, optional) – Whether to disable HTTP proxies.

• auth_callback (callable, optional) – A callback method to prompt the user for a username and password.

• otp_callback (callable, optional) – A callback method to prompt the user for their two-factor authentication code.

• verify_ssl (bool, optional) – Whether to verify SSL certificates.

• save_cookies (bool, optional) – Whether to save authentication cookies.

• ext_auth_cookies (str, optional) – The name of a file to load additional cookies from. These will be layered on top of any cookies loaded from cookie_file.

• ca_certs (str, optional) – The name of a file to load certificates from.

• client_key (str, optional) – The key for a client certificate to load into the chain.

• client_cert (str, optional) – A client certificate to load into the chain.

• proxy_authorization (str, optional) – A string to use for the Proxy-Authorization header.

• config (rbtools.config.RBToolsConfig, optional) –

  The loaded RBTools configuration.

  If not provided, the configuration will be loaded.

  New in version 5.1.

config: RBToolsConfig¶

The loaded RBTools configuration.

New in version 5.1.

cookie_file: Optional[str]¶

The path to the file for storing authentication cookies.

Type:

str

cookie_jar: CookieJar¶

The cookie jar object for managing authentication cookies.

Type:

http.cookiejar.CookieJar

enable_cache(cache_location: Optional[str] = None, in_memory: bool = False) → None[source]¶

Enable caching for all future HTTP requests.

The cache will be created at the default location if none is provided.

If the in_memory parameter is True, the cache will be created in memory instead of on disk. This overrides the cache_location parameter.

Parameters:

• cache_location (str, optional) – The name of the file to use for the cache database.

• in_memory (bool, optional) – Whether to only use in-memory caching. If True, the cache_location argument is ignored.

disable_cache() → None[source]¶

Disable caching for all future HTTP requests.

New in version 5.0.

login(*, username: Optional[str] = None, password: Optional[str] = None, api_token: Optional[str] = None) → None[source]¶

Log in to the Review Board server.

Either a username and password combination or an API token must be provided.

Changed in version 5.0: Added an optional api_token parameter and made the username and password parameters optional to allow logging in with either a username and password or API token.

Parameters:

• username (str, optional) – The username to use to log in.

• password (str, optional) – The password to use to log in.

• api_token (str, optional) – The API token to use to log in.

Raises:

ValueError – No username and password or API token was provided.

logout() → None[source]¶

Log the user out of the session.

process_error(http_status: int, data: Union[str, bytes]) → None[source]¶

Process an error, raising an APIError with the information.

Parameters:

• http_status (int) – The HTTP status code.

• data (bytes or str) – The data returned by the server.

Raises:

rbtools.api.errors.APIError – The API error object.

make_request(request: HttpRequest) → Optional[Union[HTTPResponse, CachedHTTPResponse, LiveHTTPResponse]][source]¶

Perform an http request.

Parameters:

request (rbtools.api.request.HttpRequest) – The request object.

Returns:

The HTTP response.

Return type:

http.client.HTTPResponse