rbtools.api.request¶

Support for forming requests to a Review Board server.

Module Attributes

WebLoginCallback

A callback that attempts web-based login and returns its result.

Classes

`CookiePolicy`(, config, *kwargs)	A cookie policy for cookie storage and retrieval.
`HttpRequest`(url[, method, query_args, headers])	A high-level HTTP request.
`PresetHTTPAuthHandler`(url, password_mgr)	Handler that presets the use of HTTP Basic Auth.
`RBToolsHTTPSConnection`(host[, port, ...])	Connection class for HTTPS connections.
`RBToolsHTTPSHandler`([debuglevel, context, ...])	Request/response handler for HTTPS connections.
`Request`(url[, body, headers, method])	A request which contains a method attribute.
`ReviewBoardHTTPBasicAuthHandler`(args, *kwargs)	Custom Basic Auth handler that doesn't retry excessively.
`ReviewBoardHTTPErrorProcessor`()	Processes HTTP error codes.
`ReviewBoardHTTPPasswordMgr`(reviewboard_url)	Adds HTTP authentication support for URLs.
`ReviewBoardServer`(url[, cookie_file, ...])	Represents a Review Board server we are communicating with.
`ReviewBoardWebLoginHandler`(password_mgr)	Handler for authenticating through web-based login.

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.

Added in version 5.1.

__firstlineno__ = 1080¶

__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.

__static_attributes__ = ('config',)¶

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.HttpRequest(url: str, method: str = 'GET', query_args: Mapping[str, QueryArgs] | None = None, headers: Mapping[str, str] | None = None)[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.

__firstlineno__ = 144¶

__init__(url: str, method: str = 'GET', query_args: Mapping[str, QueryArgs] | None = None, headers: Mapping[str, str] | None = None) → 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.

__static_attributes__ = ('_fields', '_files', '_method', 'headers', 'url')¶

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

Add a form-data field for the request.

Changed in version 6.0: Values of types other than bytes or str will now raise a ValueError.

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

Parameters:

name (bytes or str) – The name of the field.
value (bytes or str) – The value to send for the field.

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[str | None, bytes | None][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

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 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

headers: Mapping[str, str]¶

HTTP headers to provide when making the request.

Type: dict

property method: str[source]¶: The HTTP method to send to the server.

url: str¶

The URL to request.

Type: str

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

Bases: BaseHandler

Handler that presets the use of HTTP Basic Auth.

AUTH_HEADER = 'Authorization'[source]¶

__annotations_cache__ = {}¶

__firstlineno__ = 801¶

__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.

__static_attributes__ = ('password_mgr', 'url', 'used')¶

handler_order = 480[source]¶

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

reset(*, username: str | None = None, password: str | None = None, api_token: str | None = 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.

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.

Added in version 4.1.

__annotations_cache__ = {}¶

__firstlineno__ = 429¶

__static_attributes__ = ()¶

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.

Added in version 4.1.

__annotations_cache__ = {}¶

__firstlineno__ = 475¶

__static_attributes__ = ()¶

do_open(http_class: HTTPSConnection, *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: bytes | None = b'', headers: dict[str, str] | None = None, method: str = 'PUT')[source]¶

Bases: Request

A request which contains a method attribute.

__firstlineno__ = 520¶

__init__(url: str, body: bytes | None = b'', headers: dict[str, str] | None = None, 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.

__static_attributes__ = ('method',)¶

get_method() → str[source]¶

Return the HTTP method.

Returns:: The HTTP method.
Return type:: str

method: str¶

The HTTP method to use.

Type: str

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.

MAX_OTP_TOKEN_ATTEMPTS = 2[source]¶

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

__firstlineno__ = 895¶

__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.

__static_attributes__ = ('_last_otp_token', '_otp_token_attempts', '_otp_token_method', '_tried_login')¶

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.

passwd: ReviewBoardHTTPPasswordMgr¶

retry_http_basic_auth(host: str, request: Request, realm: str) → HTTPResponse | None[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.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.

__annotations_cache__ = {}¶

__firstlineno__ = 563¶

__static_attributes__ = ()¶

http_response(request, response)[source]¶

https_response(request, response)[source]¶

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

Bases: HTTPPasswordMgr

Adds HTTP authentication support for URLs.

__annotations_cache__ = {}¶

__firstlineno__ = 583¶

__init__(reviewboard_url: str, rb_user: str | None = None, rb_pass: str | None = None, api_token: str | None = None, auth_callback: Callable[[...], tuple[str, str]] | None = None, otp_token_callback: Callable[[str, str], str] | None = None, web_login_callback: Callable[[], bool] | None = None) → None[source]¶

Initialize the password manager.

Changed in version 6.0: Added the web_login_callback argument.

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.
web_login_callback (callable, optional) –
A callback to attempt authentication through web-based login.

Added in version 6.0.

__static_attributes__ = ('api_token', 'auth_callback', 'otp_token_callback', 'rb_pass', 'rb_url', 'rb_user', 'web_login_callback')¶

attempt_web_login() → bool[source]¶

Attempt authenticating using web-based login.

Added in version 6.0.

Returns:: Whether the web-based login successfully authenticated.
Return type:: bool

find_user_password(realm: str, uri: str) → tuple[str | None, str | None][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) → str | None[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.ReviewBoardServer(url: str, cookie_file: str | None = None, username: str | None = None, password: str | None = None, api_token: str | None = None, agent: str | None = None, session: str | None = None, disable_proxy: bool = False, auth_callback: AuthCallback | None = None, otp_token_callback: OTPCallback | None = None, verify_ssl: bool = True, save_cookies: bool = True, ext_auth_cookies: str | None = None, ca_certs: str | None = None, client_key: str | None = None, client_cert: str | None = None, proxy_authorization: str | None = None, *, config: RBToolsConfig | None = None, web_login_callback: WebLoginCallback | None = 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.

__firstlineno__ = 1227¶

Initialize the server object.

Changed in version 6.0: Added the web_login_callback argument.

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.

Added in version 5.1.
web_login_callback (callable, optional) –
A callback to attempt authentication through web-based login.

Added in version 6.0.

__static_attributes__ = ('_cache', '_urlopen', 'agent', 'config', 'cookie_file', 'cookie_jar', 'domain', 'ext_auth_cookies', 'preset_auth_handler', 'save_cookies', 'url')¶

config: RBToolsConfig¶: The loaded RBTools configuration.

Added in version 5.1.

cookie_file: str | None¶

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

disable_cache() → None[source]¶: Disable caching for all future HTTP requests.

Added in version 5.0.

enable_cache(cache_location: str | None = 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.

has_session_cookie() → bool[source]¶

Return whether a local session cookie exists for this server.

This checks whether the cookie jar would attach a rbsessionid cookie to a request to the API.

This does not guarantee that the session is valid server-side (the cookie may be stale), this just returns whether a local session cookie has been set for this server.

Added in version 6.0.

Returns:: Whether a local session cookie exists for this server.
Return type:: bool

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

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.

make_request(request: HttpRequest) → HTTPResponse | CachedHTTPResponse | LiveHTTPResponse | None[source]¶

Perform an http request.

Parameters:: request (rbtools.api.request.HttpRequest) – The request object.
Returns:: The HTTP response.
Return type:: http.client.HTTPResponse

process_error(http_status: int, data: 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.

class rbtools.api.request.ReviewBoardWebLoginHandler(password_mgr: ReviewBoardHTTPPasswordMgr)[source]¶

Bases: BaseHandler

Handler for authenticating through web-based login.

This will try web-based login one time upon the first HTTP 401, and fall back onto the other auth handlers if it fails.

Added in version 6.0.

__annotations_cache__ = {}¶

__firstlineno__ = 725¶

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

Initialize the handler.

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

__static_attributes__ = ('password_mgr', 'used')¶

handler_order = 470[source]¶

http_error_401(req: Request, fp: HTTPResponse | None, code: int, msg: str, headers: HTTPMessage) → HTTPResponse | None[source]¶

Handle an HTTP 401 Unauthorized from an API request.

This will attempt to authenticate using web-based login. If successfully authenticated, the request will be retried. If the login fails, or if this handler has already been used, the request will be passed on to the next authentication handler.

Added in version 6.0.

Parameters:

req (rbtools.api.request.Request) – The API request being made.
fp (http.client.HTTPResponse, unused) – The file-like HTTP response object, if available.
code (int, unused) – The HTTP error code.
msg (str, unused) – The HTTP error message returned by the server.
headers (HTTPMessage, unused) – The headers sent in the Unauthorized error response.

Returns:

The response if the request was successfully retried and completed, or None to delegate to the next handler.

Return type:

http.client.HTTPResponse

rbtools.api.request.WebLoginCallback¶

A callback that attempts web-based login and returns its result.

Added in version 6.0.

alias of Callable[[], bool]