rbtools.api.request¶
Functions
|
Return a cookie jar backed by cookie_file |
Classes
|
A high-level HTTP request. |
|
Handler that presets the use of HTTP Basic Auth. |
|
Connection class for HTTPS connections. |
|
Request/response handler for HTTPS connections. |
|
A request which contains a method attribute. |
|
Custom Basic Auth handler that doesn't retry excessively. |
Processes HTTP error codes. |
|
|
Adds HTTP authentication support for URLs. |
|
Represents a Review Board server we are communicating with. |
- 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.
- 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:
- 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:
- Raises:
ValueError – The given value could not be encoded.
- Returns:
The value encoded as a unicode string.
- Return type:
- 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.
- 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.
- 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:
- Returns:
The result from the parent method.
- Return type:
- 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:
- Returns:
The resulting HTTP response.
- Return type:
- 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.
- 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.
- 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.
- class rbtools.api.request.PresetHTTPAuthHandler(url: str, password_mgr: ReviewBoardHTTPPasswordMgr)[source]¶
Bases:
BaseHandler
Handler that presets the use of HTTP Basic Auth.
- __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 theusername
andpassword
parameters optional to allow authentication with either a username and password or API token.- Parameters:
username (
str
, optional) – The username to use for authentication. IfNone
and no API token is provided, this will log out the user.password (
str
, optional) – The password to use for authentication. IfNone
and no API token is provided, this will log out the user.api_token (
str
, optional) – The API token to use for authentication. IfNone
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:
- 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:
- 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.
- passwd: ReviewBoardHTTPPasswordMgr¶
- 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:
- 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:
- 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.
- rbtools.api.request.create_cookie_jar(cookie_file: Optional[str] = None) Tuple[MozillaCookieJar, str] [source]¶
Return a cookie jar backed by cookie_file
If cooie_file is not provided, we will default it. If the cookie_file does not exist, we will create it with the proper permissions.
In the case where we default cookie_file, and it does not exist, we will attempt to copy the .post-review-cookies.txt file.
- Parameters:
cookie_file (
str
, optional) – The filename to use for cookies.- Returns:
A two-tuple containing:
- Tuple:
0 (
http.cookiejar.MozillaCookieJar
) – The cookie jar object.1 (
str
) – The name of the cookie file.
- Return type:
- 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[Callable[[...], Tuple[str, str]]] = None, otp_token_callback: Optional[Callable[[str, str], str]] = 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)[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[Callable[[...], Tuple[str, str]]] = None, otp_token_callback: Optional[Callable[[str, str], str]] = 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) None [source]¶
Initialize the server object.
- 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) – Anrbsessionid
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 fromcookie_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 theProxy-Authorization
header.
- 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.
- 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 theusername
andpassword
parameters optional to allow logging in with either a username and password or API token.- Parameters:
- Raises:
ValueError – No username and password or API token was provided.
- process_error(http_status: int, data: Union[str, bytes]) None [source]¶
Process an error, raising an APIError with the information.
- Parameters:
- 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: