class ReviewBoardServer(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.
"""
def __init__(self,
url,
cookie_file=None,
username=None,
password=None,
api_token=None,
agent=None,
session=None,
disable_proxy=False,
auth_callback=None,
otp_token_callback=None,
verify_ssl=True,
save_cookies=True,
ext_auth_cookies=None):
if not url.endswith('/'):
url += '/'
self.url = url + 'api/'
self.save_cookies = save_cookies
self.ext_auth_cookies = ext_auth_cookies
if self.save_cookies:
self.cookie_jar, self.cookie_file = create_cookie_jar(
cookie_file=cookie_file)
try:
self.cookie_jar.load(ignore_expires=True)
except IOError:
pass
else:
self.cookie_jar = CookieJar()
self.cookie_file = None
if self.ext_auth_cookies:
try:
self.cookie_jar.load(ext_auth_cookies, ignore_expires=True)
except IOError as e:
logging.critical(
'There was an error while loading a '
'cookie file: %s', e)
pass
# Get the cookie domain from the url. If the domain
# does not contain a '.' (e.g. 'localhost'), we assume
# it is a local domain and suffix it (See RFC 2109).
parsed_url = urlparse(url)
self.domain = parsed_url[1].partition(':')[0] # Remove Port.
if self.domain.count('.') < 1:
self.domain = '%s.local' % self.domain
if session:
cookie = Cookie(version=0,
name=RB_COOKIE_NAME,
value=session,
port=None,
port_specified=False,
domain=self.domain,
domain_specified=True,
domain_initial_dot=True,
path=parsed_url[2],
path_specified=True,
secure=False,
expires=None,
discard=False,
comment=None,
comment_url=None,
rest={'HttpOnly': None})
self.cookie_jar.set_cookie(cookie)
if self.save_cookies:
self.cookie_jar.save()
if username:
# If the username parameter is given, we have to clear the session
# cookie manually or it will override the username:password
# combination retrieved from the authentication callback.
try:
self.cookie_jar.clear(self.domain, parsed_url[2],
RB_COOKIE_NAME)
except KeyError:
pass
# Set up the HTTP libraries to support all of the features we need.
password_mgr = ReviewBoardHTTPPasswordMgr(self.url, username, password,
api_token, auth_callback,
otp_token_callback)
self.preset_auth_handler = PresetHTTPAuthHandler(
self.url, password_mgr)
handlers = []
if not verify_ssl:
context = ssl._create_unverified_context()
handlers.append(HTTPSHandler(context=context))
if disable_proxy:
handlers.append(ProxyHandler({}))
handlers += [
HTTPCookieProcessor(self.cookie_jar),
ReviewBoardHTTPBasicAuthHandler(password_mgr),
HTTPDigestAuthHandler(password_mgr),
self.preset_auth_handler,
ReviewBoardHTTPErrorProcessor(),
]
if agent:
self.agent = agent
else:
self.agent = ('RBTools/' + get_package_version()).encode('utf-8')
opener = build_opener(*handlers)
opener.addheaders = [
(str('User-agent'), str(self.agent)),
]
install_opener(opener)
self._cache = None
self._urlopen = urlopen
def enable_cache(self, cache_location=None, in_memory=False):
"""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.
"""
if not self._cache:
self._cache = APICache(create_db_in_memory=in_memory,
db_location=cache_location)
self._urlopen = self._cache.make_request
def login(self, username, password):
"""Reset the user information"""
self.preset_auth_handler.reset(username, password)
def logout(self):
"""Logs the user out of the session."""
self.preset_auth_handler.reset(None, None)
self.make_request(HttpRequest('%ssession/' % self.url,
method='DELETE'))
self.cookie_jar.clear(self.domain)
if self.save_cookies:
self.cookie_jar.save()
def process_error(self, http_status, data):
"""Processes an error, raising an APIError with the information."""
# In Python 3, the data can be bytes, not str, and json.loads
# explicitly requires decoded strings.
data = force_unicode(data)
try:
rsp = json_loads(data)
assert rsp['stat'] == 'fail'
logging.debug('Got API Error %d (HTTP code %d): %s',
rsp['err']['code'], http_status, rsp['err']['msg'])
logging.debug('Error data: %r', rsp)
raise create_api_error(http_status, rsp['err']['code'], rsp,
rsp['err']['msg'])
except ValueError:
logging.debug('Got HTTP error: %s: %s', http_status, data)
raise APIError(http_status, None, None, data)
def make_request(self, request):
"""Perform an http request.
The request argument should be an instance of
'rbtools.api.request.HttpRequest'.
"""
try:
content_type, body = request.encode_multipart_formdata()
headers = request.headers
if body:
headers.update({
'Content-Type': content_type,
'Content-Length': str(len(body)),
})
else:
headers['Content-Length'] = '0'
rsp = self._urlopen(
Request(request.url, body, headers, request.method))
except HTTPError as e:
self.process_error(e.code, e.read())
except URLError as e:
raise ServerInterfaceError('%s' % e.reason)
if self.save_cookies:
try:
self.cookie_jar.save()
except IOError:
pass
return rsp
class ReviewBoardServer(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.
"""
def __init__(self, url, cookie_file=None, username=None, password=None,
api_token=None, agent=None, session=None, disable_proxy=False,
auth_callback=None, otp_token_callback=None,
verify_ssl=True, save_cookies=True, ext_auth_cookies=None):
if not url.endswith('/'):
url += '/'
self.url = url + 'api/'
self.save_cookies = save_cookies
self.ext_auth_cookies = ext_auth_cookies
if self.save_cookies:
self.cookie_jar, self.cookie_file = create_cookie_jar(
cookie_file=cookie_file)
try:
self.cookie_jar.load(ignore_expires=True)
except IOError:
pass
else:
self.cookie_jar = CookieJar()
self.cookie_file = None
if self.ext_auth_cookies:
try:
self.cookie_jar.load(ext_auth_cookies, ignore_expires=True)
except IOError as e:
logging.critical('There was an error while loading a '
'cookie file: %s', e)
pass
# Get the cookie domain from the url. If the domain
# does not contain a '.' (e.g. 'localhost'), we assume
# it is a local domain and suffix it (See RFC 2109).
parsed_url = urlparse(url)
self.domain = parsed_url[1].partition(':')[0] # Remove Port.
if self.domain.count('.') < 1:
self.domain = '%s.local' % self.domain
if session:
cookie = Cookie(
version=0,
name=RB_COOKIE_NAME,
value=session,
port=None,
port_specified=False,
domain=self.domain,
domain_specified=True,
domain_initial_dot=True,
path=parsed_url[2],
path_specified=True,
secure=False,
expires=None,
discard=False,
comment=None,
comment_url=None,
rest={'HttpOnly': None})
self.cookie_jar.set_cookie(cookie)
if self.save_cookies:
self.cookie_jar.save()
if username:
# If the username parameter is given, we have to clear the session
# cookie manually or it will override the username:password
# combination retrieved from the authentication callback.
try:
self.cookie_jar.clear(self.domain, parsed_url[2],
RB_COOKIE_NAME)
except KeyError:
pass
# Set up the HTTP libraries to support all of the features we need.
password_mgr = ReviewBoardHTTPPasswordMgr(self.url,
username,
password,
api_token,
auth_callback,
otp_token_callback)
self.preset_auth_handler = PresetHTTPAuthHandler(self.url,
password_mgr)
handlers = []
if not verify_ssl:
context = ssl._create_unverified_context()
handlers.append(HTTPSHandler(context=context))
if disable_proxy:
handlers.append(ProxyHandler({}))
handlers += [
HTTPCookieProcessor(self.cookie_jar),
ReviewBoardHTTPBasicAuthHandler(password_mgr),
HTTPDigestAuthHandler(password_mgr),
self.preset_auth_handler,
ReviewBoardHTTPErrorProcessor(),
]
if agent:
self.agent = agent
else:
self.agent = ('RBTools/' + get_package_version()).encode('utf-8')
opener = build_opener(*handlers)
opener.addheaders = [
(b'User-agent', self.agent),
]
install_opener(opener)
self._cache = None
self._urlopen = urlopen
def enable_cache(self, cache_location=None, in_memory=False):
"""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.
"""
if not self._cache:
self._cache = APICache(create_db_in_memory=in_memory,
db_location=cache_location)
self._urlopen = self._cache.make_request
def login(self, username, password):
"""Reset the user information"""
self.preset_auth_handler.reset(username, password)
def logout(self):
"""Logs the user out of the session."""
self.preset_auth_handler.reset(None, None)
self.make_request(HttpRequest('%ssession/' % self.url,
method='DELETE'))
self.cookie_jar.clear(self.domain)
if self.save_cookies:
self.cookie_jar.save()
def process_error(self, http_status, data):
"""Processes an error, raising an APIError with the information."""
try:
rsp = json_loads(data)
assert rsp['stat'] == 'fail'
logging.debug('Got API Error %d (HTTP code %d): %s' %
(rsp['err']['code'], http_status, rsp['err']['msg']))
logging.debug('Error data: %r' % rsp)
raise create_api_error(http_status, rsp['err']['code'], rsp,
rsp['err']['msg'])
except ValueError:
logging.debug('Got HTTP error: %s: %s' % (http_status, data))
raise APIError(http_status, None, None, data)
def make_request(self, request):
"""Perform an http request.
The request argument should be an instance of
'rbtools.api.request.HttpRequest'.
"""
try:
content_type, body = request.encode_multipart_formdata()
headers = request.headers
if body:
headers.update({
b'Content-Type': content_type,
b'Content-Length': str(len(body)),
})
else:
headers[b'Content-Length'] = '0'
r = Request(request.url.encode('utf-8'), body, headers,
request.method.encode('utf-8'))
rsp = self._urlopen(r)
except HTTPError as e:
self.process_error(e.code, e.read())
except URLError as e:
raise ServerInterfaceError('%s' % e.reason)
if self.save_cookies:
try:
self.cookie_jar.save()
except IOError:
pass
return rsp