+bugzilla
+ + + + + + +1# python-bugzilla - a Python interface to bugzilla using xmlrpclib. + 2# + 3# Copyright (C) 2007, 2008 Red Hat Inc. + 4# Author: Will Woods <wwoods@redhat.com> + 5# + 6# This work is licensed under the GNU GPLv2 or later. + 7# See the COPYING file in the top-level directory. + 8 + 9from .apiversion import version, __version__ +10from .base import Bugzilla +11from .exceptions import BugzillaError +12from .oldclasses import (Bugzilla3, Bugzilla32, Bugzilla34, Bugzilla36, +13 Bugzilla4, Bugzilla42, Bugzilla44, +14 NovellBugzilla, RHBugzilla, RHBugzilla3, RHBugzilla4) +15 +16 +17# This is the public API. If you are explicitly instantiating any other +18# class, using some function, or poking into internal files, don't complain +19# if things break on you. +20__all__ = [ +21 "Bugzilla3", "Bugzilla32", "Bugzilla34", "Bugzilla36", +22 "Bugzilla4", "Bugzilla42", "Bugzilla44", +23 "NovellBugzilla", +24 "RHBugzilla3", "RHBugzilla4", "RHBugzilla", +25 'BugzillaError', +26 'Bugzilla', "version", +27] +28 +29 +30# Clear all other locals() from the public API +31for __sym in locals().copy(): +32 if __sym.startswith("__") or __sym in __all__: +33 continue +34 locals().pop(__sym) +35locals().pop("__sym") +
The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+Helper class for historical bugzilla.redhat.com back compat
+ +Historically this class used many more non-upstream methods, but +in 2012 RH started dropping most of its custom bits. By that time, +upstream BZ had most of the important functionality.
+ +Much of the remaining code here is just trying to keep things operating +in python-bugzilla back compatible manner.
+ +This class was written using bugzilla.redhat.com's API docs: +https://bugzilla.redhat.com/docs/en/html/api/
+Helper class for historical bugzilla.redhat.com back compat
+ +Historically this class used many more non-upstream methods, but +in 2012 RH started dropping most of its custom bits. By that time, +upstream BZ had most of the important functionality.
+ +Much of the remaining code here is just trying to keep things operating +in python-bugzilla back compatible manner.
+ +This class was written using bugzilla.redhat.com's API docs: +https://bugzilla.redhat.com/docs/en/html/api/
+43class RHBugzilla(Bugzilla): +44 """ +45 Helper class for historical bugzilla.redhat.com back compat +46 +47 Historically this class used many more non-upstream methods, but +48 in 2012 RH started dropping most of its custom bits. By that time, +49 upstream BZ had most of the important functionality. +50 +51 Much of the remaining code here is just trying to keep things operating +52 in python-bugzilla back compatible manner. +53 +54 This class was written using bugzilla.redhat.com's API docs: +55 https://bugzilla.redhat.com/docs/en/html/api/ +56 """ +57 _is_redhat_bugzilla = True +
Helper class for historical bugzilla.redhat.com back compat
+ +Historically this class used many more non-upstream methods, but +in 2012 RH started dropping most of its custom bits. By that time, +upstream BZ had most of the important functionality.
+ +Much of the remaining code here is just trying to keep things operating +in python-bugzilla back compatible manner.
+ +This class was written using bugzilla.redhat.com's API docs: +https://bugzilla.redhat.com/docs/en/html/api/
+
+
+ class
+ BugzillaError(builtins.Exception):
+
+
+
+
+
+ 7class BugzillaError(Exception): + 8 """ + 9 Error raised in the Bugzilla client code. +10 """ +11 @staticmethod +12 def get_bugzilla_error_string(exc): +13 """ +14 Helper to return the bugzilla instance error message from an +15 XMLRPC Fault, or any other exception type that's raised from bugzilla +16 interaction +17 """ +18 return getattr(exc, "faultString", str(exc)) +19 +20 @staticmethod +21 def get_bugzilla_error_code(exc): +22 """ +23 Helper to return the bugzilla instance error code from an +24 XMLRPC Fault, or any other exception type that's raised from bugzilla +25 interaction +26 """ +27 for propname in ["faultCode", "code"]: +28 if hasattr(exc, propname): +29 return getattr(exc, propname) +30 return None +31 +32 def __init__(self, message, code=None): +33 """ +34 :param code: The error code from the remote bugzilla instance. Only +35 set if the error came directly from the remove bugzilla +36 """ +37 self.code = code +38 if self.code: +39 message += " (code=%s)" % self.code +40 Exception.__init__(self, message) +
Error raised in the Bugzilla client code.
+
+
+
+
+
+
+
+
+
+
+
+ BugzillaError(message, code=None)
+
+
+
+
+
+ 32 def __init__(self, message, code=None): +33 """ +34 :param code: The error code from the remote bugzilla instance. Only +35 set if the error came directly from the remove bugzilla +36 """ +37 self.code = code +38 if self.code: +39 message += " (code=%s)" % self.code +40 Exception.__init__(self, message) +
Parameters
+ +-
+
- code: The error code from the remote bugzilla instance. Only +set if the error came directly from the remove bugzilla +
+
+
+
+
+
+
+
+
+
+
+
+ @staticmethod
+
+ def
+ get_bugzilla_error_string(exc):
+
+
+
+ 11 @staticmethod +12 def get_bugzilla_error_string(exc): +13 """ +14 Helper to return the bugzilla instance error message from an +15 XMLRPC Fault, or any other exception type that's raised from bugzilla +16 interaction +17 """ +18 return getattr(exc, "faultString", str(exc)) +
Helper to return the bugzilla instance error message from an +XMLRPC Fault, or any other exception type that's raised from bugzilla +interaction
+
+
+
+
+
+
+
+
+
+
+
+
+
+ @staticmethod
+
+ def
+ get_bugzilla_error_code(exc):
+
+
+
+ 20 @staticmethod +21 def get_bugzilla_error_code(exc): +22 """ +23 Helper to return the bugzilla instance error code from an +24 XMLRPC Fault, or any other exception type that's raised from bugzilla +25 interaction +26 """ +27 for propname in ["faultCode", "code"]: +28 if hasattr(exc, propname): +29 return getattr(exc, propname) +30 return None +
Helper to return the bugzilla instance error code from an +XMLRPC Fault, or any other exception type that's raised from bugzilla +interaction
+
+
+ class
+ Bugzilla:
+
+
+
+
+
+ 80class Bugzilla(object): + 81 """ + 82 The main API object. Connects to a bugzilla instance over XMLRPC, and + 83 provides wrapper functions to simplify dealing with API calls. + 84 + 85 The most common invocation here will just be with just a URL: + 86 + 87 bzapi = Bugzilla("http://bugzilla.example.com") + 88 + 89 If you have previously logged into that URL, and have cached login + 90 tokens, you will automatically be logged in. Otherwise to + 91 log in, you can either pass auth options to __init__, or call a login + 92 helper like interactive_login(). + 93 + 94 If you are not logged in, you won't be able to access restricted data like + 95 user email, or perform write actions like bug create/update. But simple + 96 querys will work correctly. + 97 + 98 If you are unsure if you are logged in, you can check the .logged_in + 99 property. + 100 + 101 Another way to specify auth credentials is via a 'bugzillarc' file. + 102 See readconfig() documentation for details. + 103 """ + 104 @staticmethod + 105 def url_to_query(url): + 106 """ + 107 Given a big huge bugzilla query URL, returns a query dict that can + 108 be passed along to the Bugzilla.query() method. + 109 """ + 110 q = {} + 111 + 112 # pylint: disable=unpacking-non-sequence + 113 (ignore1, ignore2, path, + 114 ignore, query, ignore3) = urllib.parse.urlparse(url) + 115 + 116 base = os.path.basename(path) + 117 if base not in ('buglist.cgi', 'query.cgi'): + 118 return {} + 119 + 120 for (k, v) in urllib.parse.parse_qsl(query): + 121 if k not in q: + 122 q[k] = v + 123 elif isinstance(q[k], list): + 124 q[k].append(v) + 125 else: + 126 oldv = q[k] + 127 q[k] = [oldv, v] + 128 + 129 # Handle saved searches + 130 if base == "buglist.cgi" and "namedcmd" in q and "sharer_id" in q: + 131 q = { + 132 "sharer_id": q["sharer_id"], + 133 "savedsearch": q["namedcmd"], + 134 } + 135 + 136 return q + 137 + 138 @staticmethod + 139 def fix_url(url, force_rest=False): + 140 """ + 141 Turn passed url into a bugzilla XMLRPC web url + 142 + 143 :param force_rest: If True, generate a REST API url + 144 """ + 145 (scheme, netloc, path, + 146 params, query, fragment) = urllib.parse.urlparse(url) + 147 if not scheme: + 148 scheme = 'https' + 149 + 150 if path and not netloc: + 151 netloc = path.split("/", 1)[0] + 152 path = "/".join(path.split("/")[1:]) or None + 153 + 154 if not path: + 155 path = 'xmlrpc.cgi' + 156 if force_rest: + 157 path = "rest/" + 158 + 159 if not path.startswith("/"): + 160 path = "/" + path + 161 + 162 newurl = urllib.parse.urlunparse( + 163 (scheme, netloc, path, params, query, fragment)) + 164 return newurl + 165 + 166 @staticmethod + 167 def get_rcfile_default_url(): + 168 """ + 169 Helper to check all the default bugzillarc file paths for + 170 a [DEFAULT] url=X section, and if found, return it. + 171 """ + 172 configpaths = _BugzillaRCFile.get_default_configpaths() + 173 rcfile = _BugzillaRCFile() + 174 rcfile.set_configpaths(configpaths) + 175 return rcfile.get_default_url() + 176 + 177 + 178 def __init__(self, url=-1, user=None, password=None, cookiefile=-1, + 179 sslverify=True, tokenfile=-1, use_creds=True, api_key=None, + 180 cert=None, configpaths=-1, + 181 force_rest=False, force_xmlrpc=False, requests_session=None): + 182 """ + 183 :param url: The bugzilla instance URL, which we will connect + 184 to immediately. Most users will want to specify this at + 185 __init__ time, but you can defer connecting by passing + 186 url=None and calling connect(URL) manually + 187 :param user: optional username to connect with + 188 :param password: optional password for the connecting user + 189 :param cert: optional certificate file for client side certificate + 190 authentication + 191 :param cookiefile: Deprecated, raises an error if not -1 or None + 192 :param sslverify: Set this to False to skip SSL hostname and CA + 193 validation checks, like out of date certificate + 194 :param tokenfile: Location to cache the API login token so youi + 195 don't have to keep specifying username/password. + 196 If -1, use the default path. If None, don't use + 197 or save any tokenfile. + 198 :param use_creds: If False, this disables tokenfile + 199 and configpaths by default. This is a convenience option to + 200 unset those values at init time. If those values are later + 201 changed, they may be used for future operations. + 202 :param sslverify: Maps to 'requests' sslverify parameter. Set to + 203 False to disable SSL verification, but it can also be a path + 204 to file or directory for custom certs. + 205 :param api_key: A bugzilla5+ API key + 206 :param configpaths: A list of possible bugzillarc locations. + 207 :param force_rest: Force use of the REST API + 208 :param force_xmlrpc: Force use of the XMLRPC API. If neither force_X + 209 parameter are specified, heuristics will be used to determine + 210 which API to use, with XMLRPC preferred for back compatability. + 211 :param requests_session: An optional requests.Session object the + 212 API will use to contact the remote bugzilla instance. This + 213 way the API user can set up whatever auth bits they may need. + 214 """ + 215 if url == -1: + 216 raise TypeError("Specify a valid bugzilla url, or pass url=None") + 217 + 218 # Settings the user might want to tweak + 219 self.user = user or '' + 220 self.password = password or '' + 221 self.api_key = api_key + 222 self.cert = cert or None + 223 self.url = '' + 224 + 225 self._backend = None + 226 self._session = None + 227 self._user_requests_session = requests_session + 228 self._sslverify = sslverify + 229 self._cache = _BugzillaAPICache() + 230 self._bug_autorefresh = False + 231 self._is_redhat_bugzilla = False + 232 + 233 self._rcfile = _BugzillaRCFile() + 234 self._tokencache = _BugzillaTokenCache() + 235 + 236 self._force_rest = force_rest + 237 self._force_xmlrpc = force_xmlrpc + 238 + 239 if cookiefile not in [None, -1]: + 240 raise TypeError("cookiefile is deprecated, don't pass any value.") + 241 + 242 if not use_creds: + 243 tokenfile = None + 244 configpaths = [] + 245 + 246 if tokenfile == -1: + 247 tokenfile = self._tokencache.get_default_path() + 248 if configpaths == -1: + 249 configpaths = _BugzillaRCFile.get_default_configpaths() + 250 + 251 self._settokenfile(tokenfile) + 252 self._setconfigpath(configpaths) + 253 + 254 if url: + 255 self.connect(url) + 256 + 257 def _detect_is_redhat_bugzilla(self): + 258 if self._is_redhat_bugzilla: + 259 return True + 260 + 261 match = ".redhat.com" + 262 if match in self.url: + 263 log.info("Using RHBugzilla for URL containing %s", match) + 264 return True + 265 + 266 return False + 267 + 268 def _init_class_from_url(self): + 269 """ + 270 Detect if we should use RHBugzilla class, and if so, set it + 271 """ + 272 from .oldclasses import RHBugzilla # pylint: disable=cyclic-import + 273 + 274 if not self._detect_is_redhat_bugzilla(): + 275 return + 276 + 277 self._is_redhat_bugzilla = True + 278 if self.__class__ == Bugzilla: + 279 # Overriding the class doesn't have any functional effect, + 280 # but we continue to do it for API back compat incase anyone + 281 # is doing any class comparison. We should drop this in the future + 282 self.__class__ = RHBugzilla + 283 + 284 def _get_field_aliases(self): + 285 # List of field aliases. Maps old style RHBZ parameter + 286 # names to actual upstream values. Used for createbug() and + 287 # query include_fields at least. + 288 ret = [] + 289 + 290 def _add(*args, **kwargs): + 291 ret.append(_FieldAlias(*args, **kwargs)) + 292 + 293 def _add_both(newname, origname): + 294 _add(newname, origname, is_api=False) + 295 _add(origname, newname, is_bug=False) + 296 + 297 _add('summary', 'short_desc') + 298 _add('description', 'comment') + 299 _add('platform', 'rep_platform') + 300 _add('severity', 'bug_severity') + 301 _add('status', 'bug_status') + 302 _add('id', 'bug_id') + 303 _add('blocks', 'blockedby') + 304 _add('blocks', 'blocked') + 305 _add('depends_on', 'dependson') + 306 _add('creator', 'reporter') + 307 _add('url', 'bug_file_loc') + 308 _add('dupe_of', 'dupe_id') + 309 _add('dupe_of', 'dup_id') + 310 _add('comments', 'longdescs') + 311 _add('creation_time', 'opendate') + 312 _add('creation_time', 'creation_ts') + 313 _add('whiteboard', 'status_whiteboard') + 314 _add('last_change_time', 'delta_ts') + 315 + 316 if self._is_redhat_bugzilla: + 317 _add_both('fixed_in', 'cf_fixed_in') + 318 _add_both('qa_whiteboard', 'cf_qa_whiteboard') + 319 _add_both('devel_whiteboard', 'cf_devel_whiteboard') + 320 _add_both('internal_whiteboard', 'cf_internal_whiteboard') + 321 + 322 _add('component', 'components', is_bug=False) + 323 _add('version', 'versions', is_bug=False) + 324 # Yes, sub_components is the field name the API expects + 325 _add('sub_components', 'sub_component', is_bug=False) + 326 # flags format isn't exactly the same but it's the closest approx + 327 _add('flags', 'flag_types') + 328 + 329 return ret + 330 + 331 def _get_user_agent(self): + 332 return 'python-bugzilla/%s' % __version__ + 333 user_agent = property(_get_user_agent) + 334 + 335 @property + 336 def bz_ver_major(self): + 337 return self._cache.version_parsed[0] + 338 + 339 @property + 340 def bz_ver_minor(self): + 341 return self._cache.version_parsed[1] + 342 + 343 + 344 ################### + 345 # Private helpers # + 346 ################### + 347 + 348 def _get_version(self): + 349 """ + 350 Return version number as a float + 351 """ + 352 return float("%d.%d" % (self.bz_ver_major, self.bz_ver_minor)) + 353 + 354 def _get_bug_aliases(self): + 355 return [(f.newname, f.oldname) + 356 for f in self._get_field_aliases() if f.is_bug] + 357 + 358 def _get_api_aliases(self): + 359 return [(f.newname, f.oldname) + 360 for f in self._get_field_aliases() if f.is_api] + 361 + 362 + 363 ################# + 364 # Auth handling # + 365 ################# + 366 + 367 def _getcookiefile(self): + 368 return None + 369 cookiefile = property(_getcookiefile) + 370 + 371 def _gettokenfile(self): + 372 return self._tokencache.get_filename() + 373 def _settokenfile(self, filename): + 374 self._tokencache.set_filename(filename) + 375 def _deltokenfile(self): + 376 self._settokenfile(None) + 377 tokenfile = property(_gettokenfile, _settokenfile, _deltokenfile) + 378 + 379 def _getconfigpath(self): + 380 return self._rcfile.get_configpaths() + 381 def _setconfigpath(self, configpaths): + 382 return self._rcfile.set_configpaths(configpaths) + 383 def _delconfigpath(self): + 384 return self._rcfile.set_configpaths(None) + 385 configpath = property(_getconfigpath, _setconfigpath, _delconfigpath) + 386 + 387 + 388 ############################# + 389 # Login/connection handling # + 390 ############################# + 391 + 392 def readconfig(self, configpath=None, overwrite=True): + 393 """ + 394 :param configpath: Optional bugzillarc path to read, instead of + 395 the default list. + 396 + 397 This function is called automatically from Bugzilla connect(), which + 398 is called at __init__ if a URL is passed. Calling it manually is + 399 just for passing in a non-standard configpath. + 400 + 401 The locations for the bugzillarc file are preferred in this order: + 402 + 403 ~/.config/python-bugzilla/bugzillarc + 404 ~/.bugzillarc + 405 /etc/bugzillarc + 406 + 407 It has content like: + 408 [bugzilla.yoursite.com] + 409 user = username + 410 password = password + 411 Or + 412 [bugzilla.yoursite.com] + 413 api_key = key + 414 + 415 The file can have multiple sections for different bugzilla instances. + 416 A 'url' field in the [DEFAULT] section can be used to set a default + 417 URL for the bugzilla command line tool. + 418 + 419 Be sure to set appropriate permissions on bugzillarc if you choose to + 420 store your password in it! + 421 + 422 :param overwrite: If True, bugzillarc will clobber any already + 423 set self.user/password/api_key/cert value. + 424 """ + 425 if configpath: + 426 self._setconfigpath(configpath) + 427 data = self._rcfile.parse(self.url) + 428 + 429 for key, val in data.items(): + 430 if key == "api_key" and (overwrite or not self.api_key): + 431 log.debug("bugzillarc: setting api_key") + 432 self.api_key = val + 433 elif key == "user" and (overwrite or not self.user): + 434 log.debug("bugzillarc: setting user=%s", val) + 435 self.user = val + 436 elif key == "password" and (overwrite or not self.password): + 437 log.debug("bugzillarc: setting password") + 438 self.password = val + 439 elif key == "cert" and (overwrite or not self.cert): + 440 log.debug("bugzillarc: setting cert") + 441 self.cert = val + 442 else: + 443 log.debug("bugzillarc: unknown key=%s", key) + 444 + 445 def _set_bz_version(self, version): + 446 self._cache.version_raw = version + 447 try: + 448 major, minor = [int(i) for i in version.split(".")[0:2]] + 449 except Exception: + 450 log.debug("version doesn't match expected format X.Y.Z, " + 451 "assuming 5.0", exc_info=True) + 452 major = 5 + 453 minor = 0 + 454 self._cache.version_parsed = (major, minor) + 455 + 456 def _get_backend_class(self, url): # pragma: no cover + 457 # This is a hook for the test suite to do some mock hackery + 458 if self._force_rest and self._force_xmlrpc: + 459 raise BugzillaError( + 460 "Cannot specify both force_rest and force_xmlrpc") + 461 + 462 xmlurl = self.fix_url(url) + 463 if self._force_xmlrpc: + 464 return _BackendXMLRPC, xmlurl + 465 + 466 resturl = self.fix_url(url, force_rest=self._force_rest) + 467 if self._force_rest: + 468 return _BackendREST, resturl + 469 + 470 # Simple heuristic if the original url has a path in it + 471 if "/xmlrpc" in url: + 472 return _BackendXMLRPC, xmlurl + 473 if "/rest" in url: + 474 return _BackendREST, resturl + 475 + 476 # We were passed something like bugzilla.example.com but we + 477 # aren't sure which method to use, try probing + 478 if _BackendXMLRPC.probe(xmlurl): + 479 return _BackendXMLRPC, xmlurl + 480 if _BackendREST.probe(resturl): + 481 return _BackendREST, resturl + 482 + 483 # Otherwise fallback to XMLRPC default and let it fail + 484 return _BackendXMLRPC, xmlurl + 485 + 486 def connect(self, url=None): + 487 """ + 488 Connect to the bugzilla instance with the given url. This is + 489 called by __init__ if a URL is passed. Or it can be called manually + 490 at any time with a passed URL. + 491 + 492 This will also read any available config files (see readconfig()), + 493 which may set 'user' and 'password', and others. + 494 + 495 If 'user' and 'password' are both set, we'll run login(). Otherwise + 496 you'll have to login() yourself before some methods will work. + 497 """ + 498 if self._session: + 499 self.disconnect() + 500 + 501 url = url or self.url + 502 backendclass, newurl = self._get_backend_class(url) + 503 if url != newurl: + 504 log.debug("Converted url=%s to fixed url=%s", url, newurl) + 505 self.url = newurl + 506 log.debug("Connecting with URL %s", self.url) + 507 + 508 # we've changed URLs - reload config + 509 self.readconfig(overwrite=False) + 510 + 511 # Detect if connecting to redhat bugzilla + 512 self._init_class_from_url() + 513 + 514 self._session = _BugzillaSession(self.url, self.user_agent, + 515 sslverify=self._sslverify, + 516 cert=self.cert, + 517 tokencache=self._tokencache, + 518 api_key=self.api_key, + 519 is_redhat_bugzilla=self._is_redhat_bugzilla, + 520 requests_session=self._user_requests_session) + 521 self._backend = backendclass(self.url, self._session) + 522 + 523 if (self.user and self.password): + 524 log.info("user and password present - doing login()") + 525 self.login() + 526 + 527 if self.api_key: + 528 log.debug("using API key") + 529 + 530 version = self._backend.bugzilla_version()["version"] + 531 log.debug("Bugzilla version string: %s", version) + 532 self._set_bz_version(version) + 533 + 534 + 535 @property + 536 def _proxy(self): + 537 """ + 538 Return an xmlrpc ServerProxy instance that will work seamlessly + 539 with bugzilla + 540 + 541 Some apps have historically accessed _proxy directly, like + 542 fedora infrastrucutre pieces. So we consider it part of the API + 543 """ + 544 return self._backend.get_xmlrpc_proxy() + 545 + 546 def is_xmlrpc(self): + 547 """ + 548 :returns: True if using the XMLRPC API + 549 """ + 550 return self._backend.is_xmlrpc() + 551 + 552 def is_rest(self): + 553 """ + 554 :returns: True if using the REST API + 555 """ + 556 return self._backend.is_rest() + 557 + 558 def get_requests_session(self): + 559 """ + 560 Give API users access to the Requests.session object we use for + 561 talking to the remote bugzilla instance. + 562 + 563 :returns: The Requests.session object backing the open connection. + 564 """ + 565 return self._session.get_requests_session() + 566 + 567 def disconnect(self): + 568 """ + 569 Disconnect from the given bugzilla instance. + 570 """ + 571 self._backend = None + 572 self._session = None + 573 self._cache = _BugzillaAPICache() + 574 + 575 def login(self, user=None, password=None, restrict_login=None): + 576 """ + 577 Attempt to log in using the given username and password. Subsequent + 578 method calls will use this username and password. Returns False if + 579 login fails, otherwise returns some kind of login info - typically + 580 either a numeric userid, or a dict of user info. + 581 + 582 If user is not set, the value of Bugzilla.user will be used. If *that* + 583 is not set, ValueError will be raised. If login fails, BugzillaError + 584 will be raised. + 585 + 586 The login session can be restricted to current user IP address + 587 with restrict_login argument. (Bugzilla 4.4+) + 588 + 589 This method will be called implicitly at the end of connect() if user + 590 and password are both set. So under most circumstances you won't need + 591 to call this yourself. + 592 """ + 593 if self.api_key: + 594 raise ValueError("cannot login when using an API key") + 595 + 596 if user: + 597 self.user = user + 598 if password: + 599 self.password = password + 600 + 601 if not self.user: + 602 raise ValueError("missing username") + 603 if not self.password: + 604 raise ValueError("missing password") + 605 + 606 payload = {"login": self.user} + 607 if restrict_login: + 608 payload['restrict_login'] = True + 609 log.debug("logging in with options %s", str(payload)) + 610 payload['password'] = self.password + 611 + 612 try: + 613 ret = self._backend.user_login(payload) + 614 self.password = '' + 615 log.info("login succeeded for user=%s", self.user) + 616 if "token" in ret: + 617 self._tokencache.set_value(self.url, ret["token"]) + 618 return ret + 619 except Exception as e: + 620 log.debug("Login exception: %s", str(e), exc_info=True) + 621 raise BugzillaError("Login failed: %s" % + 622 BugzillaError.get_bugzilla_error_string(e)) from None + 623 + 624 def interactive_save_api_key(self): + 625 """ + 626 Helper method to interactively ask for an API key, verify it + 627 is valid, and save it to a bugzillarc file referenced via + 628 self.configpaths + 629 """ + 630 sys.stdout.write('API Key: ') + 631 sys.stdout.flush() + 632 api_key = sys.stdin.readline().strip() + 633 + 634 self.disconnect() + 635 self.api_key = api_key + 636 + 637 log.info('Checking API key... ') + 638 self.connect() + 639 + 640 if not self.logged_in: # pragma: no cover + 641 raise BugzillaError("Login with API_KEY failed") + 642 log.info('API Key accepted') + 643 + 644 wrote_filename = self._rcfile.save_api_key(self.url, self.api_key) + 645 log.info("API key written to filename=%s", wrote_filename) + 646 + 647 msg = "Login successful." + 648 if wrote_filename: + 649 msg += " API key written to %s" % wrote_filename + 650 print(msg) + 651 + 652 def interactive_login(self, user=None, password=None, force=False, + 653 restrict_login=None): + 654 """ + 655 Helper method to handle login for this bugzilla instance. + 656 + 657 :param user: bugzilla username. If not specified, prompt for it. + 658 :param password: bugzilla password. If not specified, prompt for it. + 659 :param force: Unused + 660 :param restrict_login: restricts session to IP address + 661 """ + 662 ignore = force + 663 log.debug('Calling interactive_login') + 664 + 665 if not user: + 666 sys.stdout.write('Bugzilla Username: ') + 667 sys.stdout.flush() + 668 user = sys.stdin.readline().strip() + 669 if not password: + 670 password = getpass.getpass('Bugzilla Password: ') + 671 + 672 log.info('Logging in... ') + 673 out = self.login(user, password, restrict_login) + 674 msg = "Login successful." + 675 if "token" not in out: + 676 msg += " However no token was returned." + 677 else: + 678 if not self.tokenfile: + 679 msg += " Token not saved to disk." + 680 else: + 681 msg += " Token cache saved to %s" % self.tokenfile + 682 if self._get_version() >= 5.0: + 683 msg += "\nToken usage is deprecated. " + 684 msg += "Consider using bugzilla API keys instead. " + 685 msg += "See `man bugzilla` for more details." + 686 print(msg) + 687 + 688 def logout(self): + 689 """ + 690 Log out of bugzilla. Drops server connection and user info, and + 691 destroys authentication cache + 692 """ + 693 self._backend.user_logout() + 694 self.disconnect() + 695 self.user = '' + 696 self.password = '' + 697 + 698 @property + 699 def logged_in(self): + 700 """ + 701 This is True if this instance is logged in else False. + 702 + 703 We test if this session is authenticated by calling the User.get() + 704 XMLRPC method with ids set. Logged-out users cannot pass the 'ids' + 705 parameter and will result in a 505 error. If we tried to login with a + 706 token, but the token was incorrect or expired, the server returns a + 707 32000 error. + 708 + 709 For Bugzilla 5 and later, a new method, User.valid_login is available + 710 to test the validity of the token. However, this will require that the + 711 username be cached along with the token in order to work effectively in + 712 all scenarios and is not currently used. For more information, refer to + 713 the following url. + 714 + 715 http://bugzilla.readthedocs.org/en/latest/api/core/v1/user.html#valid-login + 716 """ + 717 try: + 718 self._backend.user_get({"ids": [1]}) + 719 return True + 720 except Exception as e: + 721 code = BugzillaError.get_bugzilla_error_code(e) + 722 if code in [505, 32000]: + 723 return False + 724 raise e + 725 + 726 + 727 ###################### + 728 # Bugfields querying # + 729 ###################### + 730 + 731 def getbugfields(self, force_refresh=False, names=None): + 732 """ + 733 Calls getBugFields, which returns a list of fields in each bug + 734 for this bugzilla instance. This can be used to set the list of attrs + 735 on the Bug object. + 736 + 737 :param force_refresh: If True, overwrite the bugfield cache + 738 with these newly checked values. + 739 :param names: Only check for the passed bug field names + 740 """ + 741 def _fieldnames(): + 742 data = {"include_fields": ["name"]} + 743 if names: + 744 data["names"] = names + 745 r = self._backend.bug_fields(data) + 746 return [f['name'] for f in r['fields']] + 747 + 748 if force_refresh or not self._cache.bugfields: + 749 log.debug("Refreshing bugfields") + 750 self._cache.bugfields = _fieldnames() + 751 self._cache.bugfields.sort() + 752 log.debug("bugfields = %s", self._cache.bugfields) + 753 + 754 return self._cache.bugfields + 755 bugfields = property(fget=lambda self: self.getbugfields(), + 756 fdel=lambda self: setattr(self, '_bugfields', None)) + 757 + 758 + 759 #################### + 760 # Product querying # + 761 #################### + 762 + 763 def product_get(self, ids=None, names=None, + 764 include_fields=None, exclude_fields=None, + 765 ptype=None): + 766 """ + 767 Raw wrapper around Product.get + 768 https://bugzilla.readthedocs.io/en/latest/api/core/v1/product.html#get-product + 769 + 770 This does not perform any caching like other product API calls. + 771 If ids, names, or ptype is not specified, we default to + 772 ptype=accessible for historical reasons + 773 + 774 @ids: List of product IDs to lookup + 775 @names: List of product names to lookup + 776 @ptype: Either 'accessible', 'selectable', or 'enterable'. If + 777 specified, we return data for all those + 778 @include_fields: Only include these fields in the output + 779 @exclude_fields: Do not include these fields in the output + 780 """ + 781 if ids is None and names is None and ptype is None: + 782 ptype = "accessible" + 783 + 784 if ptype: + 785 raw = None + 786 if ptype == "accessible": + 787 raw = self._backend.product_get_accessible() + 788 elif ptype == "enterable": + 789 raw = self._backend.product_get_enterable() + 790 elif ptype == "selectable": + 791 raw = self._backend.product_get_selectable() + 792 + 793 if raw is None: + 794 raise RuntimeError("Unknown ptype=%s" % ptype) + 795 ids = raw['ids'] + 796 log.debug("For ptype=%s found ids=%s", ptype, ids) + 797 + 798 kwargs = {} + 799 if ids: + 800 kwargs["ids"] = listify(ids) + 801 if names: + 802 kwargs["names"] = listify(names) + 803 if include_fields: + 804 kwargs["include_fields"] = include_fields + 805 if exclude_fields: + 806 kwargs["exclude_fields"] = exclude_fields + 807 + 808 ret = self._backend.product_get(kwargs) + 809 return ret['products'] + 810 + 811 def refresh_products(self, **kwargs): + 812 """ + 813 Refresh a product's cached info. Basically calls product_get + 814 with the passed arguments, and tries to intelligently update + 815 our product cache. + 816 + 817 For example, if we already have cached info for product=foo, + 818 and you pass in names=["bar", "baz"], the new cache will have + 819 info for products foo, bar, baz. Individual product fields are + 820 also updated. + 821 """ + 822 for product in self.product_get(**kwargs): + 823 updated = False + 824 for current in self._cache.products[:]: + 825 if (current.get("id", -1) != product.get("id", -2) and + 826 current.get("name", -1) != product.get("name", -2)): + 827 continue + 828 + 829 _nested_update(current, product) + 830 updated = True + 831 break + 832 if not updated: + 833 self._cache.products.append(product) + 834 + 835 def getproducts(self, force_refresh=False, **kwargs): + 836 """ + 837 Query all products and return the raw dict info. Takes all the + 838 same arguments as product_get. + 839 + 840 On first invocation this will contact bugzilla and internally + 841 cache the results. Subsequent getproducts calls or accesses to + 842 self.products will return this cached data only. + 843 + 844 :param force_refresh: force refreshing via refresh_products() + 845 """ + 846 if force_refresh or not self._cache.products: + 847 self.refresh_products(**kwargs) + 848 return self._cache.products + 849 + 850 products = property( + 851 fget=lambda self: self.getproducts(), + 852 fdel=lambda self: setattr(self, '_products', None), + 853 doc="Helper for accessing the products cache. If nothing " + 854 "has been cached yet, this calls getproducts()") + 855 + 856 + 857 ####################### + 858 # components querying # + 859 ####################### + 860 + 861 def _lookup_product_in_cache(self, productname): + 862 prodstr = isinstance(productname, str) and productname or None + 863 prodint = isinstance(productname, int) and productname or None + 864 for proddict in self._cache.products: + 865 if prodstr == proddict.get("name", -1): + 866 return proddict + 867 if prodint == proddict.get("id", "nope"): + 868 return proddict + 869 return {} + 870 + 871 def getcomponentsdetails(self, product, force_refresh=False): + 872 """ + 873 Wrapper around Product.get(include_fields=["components"]), + 874 returning only the "components" data for the requested product, + 875 slightly reworked to a dict mapping of components.name: components, + 876 for historical reasons. + 877 + 878 This uses the product cache, but will update it if the product + 879 isn't found or "components" isn't cached for the product. + 880 + 881 In cases like bugzilla.redhat.com where there are tons of + 882 components for some products, this API will time out. You + 883 should use product_get instead. + 884 """ + 885 proddict = self._lookup_product_in_cache(product) + 886 + 887 if (force_refresh or not proddict or "components" not in proddict): + 888 self.refresh_products(names=[product], + 889 include_fields=["name", "id", "components"]) + 890 proddict = self._lookup_product_in_cache(product) + 891 + 892 ret = {} + 893 for compdict in proddict["components"]: + 894 ret[compdict["name"]] = compdict + 895 return ret + 896 + 897 def getcomponentdetails(self, product, component, force_refresh=False): + 898 """ + 899 Helper for accessing a single component's info. This is a wrapper + 900 around getcomponentsdetails, see that for explanation + 901 """ + 902 d = self.getcomponentsdetails(product, force_refresh) + 903 return d[component] + 904 + 905 def getcomponents(self, product, force_refresh=False): + 906 """ + 907 Return a list of component names for the passed product. + 908 + 909 On first invocation the value is cached, and subsequent calls + 910 will return the cached data. + 911 + 912 :param force_refresh: Force refreshing the cache, and return + 913 the new data + 914 """ + 915 proddict = self._lookup_product_in_cache(product) + 916 product_id = proddict.get("id", None) + 917 + 918 if (force_refresh or product_id is None or + 919 "components" not in proddict): + 920 self.refresh_products( + 921 names=[product], + 922 include_fields=["name", "id", "components.name"]) + 923 proddict = self._lookup_product_in_cache(product) + 924 if "id" not in proddict: + 925 raise BugzillaError("Product '%s' not found" % product) + 926 product_id = proddict["id"] + 927 + 928 if product_id not in self._cache.component_names: + 929 names = [] + 930 for comp in proddict.get("components", []): + 931 name = comp.get("name") + 932 if name: + 933 names.append(name) + 934 self._cache.component_names[product_id] = names + 935 + 936 return self._cache.component_names[product_id] + 937 + 938 + 939 ############################ + 940 # component adding/editing # + 941 ############################ + 942 + 943 def _component_data_convert(self, data, update=False): + 944 # Back compat for the old RH interface + 945 convert_fields = [ + 946 ("initialowner", "default_assignee"), + 947 ("initialqacontact", "default_qa_contact"), + 948 ("initialcclist", "default_cc"), + 949 ] + 950 for old, new in convert_fields: + 951 if old in data: + 952 data[new] = data.pop(old) + 953 + 954 if update: + 955 names = {"product": data.pop("product"), + 956 "component": data.pop("component")} + 957 updates = {} + 958 for k in list(data.keys()): + 959 updates[k] = data.pop(k) + 960 + 961 data["names"] = [names] + 962 data["updates"] = updates + 963 + 964 + 965 def addcomponent(self, data): + 966 """ + 967 A method to create a component in Bugzilla. Takes a dict, with the + 968 following elements: + 969 + 970 product: The product to create the component in + 971 component: The name of the component to create + 972 description: A one sentence summary of the component + 973 default_assignee: The bugzilla login (email address) of the initial + 974 owner of the component + 975 default_qa_contact (optional): The bugzilla login of the + 976 initial QA contact + 977 default_cc: (optional) The initial list of users to be CC'ed on + 978 new bugs for the component. + 979 is_active: (optional) If False, the component is hidden from + 980 the component list when filing new bugs. + 981 """ + 982 data = data.copy() + 983 self._component_data_convert(data) + 984 return self._backend.component_create(data) + 985 + 986 def editcomponent(self, data): + 987 """ + 988 A method to edit a component in Bugzilla. Takes a dict, with + 989 mandatory elements of product. component, and initialowner. + 990 All other elements are optional and use the same names as the + 991 addcomponent() method. + 992 """ + 993 data = data.copy() + 994 self._component_data_convert(data, update=True) + 995 return self._backend.component_update(data) + 996 + 997 + 998 ################### + 999 # getbug* methods # +1000 ################### +1001 +1002 def _process_include_fields(self, include_fields, exclude_fields, +1003 extra_fields): +1004 """ +1005 Internal helper to process include_fields lists +1006 """ +1007 def _convert_fields(_in): +1008 for newname, oldname in self._get_api_aliases(): +1009 if oldname in _in: +1010 _in.remove(oldname) +1011 if newname not in _in: +1012 _in.append(newname) +1013 return _in +1014 +1015 ret = {} +1016 if include_fields: +1017 include_fields = _convert_fields(include_fields) +1018 if "id" not in include_fields: +1019 include_fields.append("id") +1020 ret["include_fields"] = include_fields +1021 if exclude_fields: +1022 exclude_fields = _convert_fields(exclude_fields) +1023 ret["exclude_fields"] = exclude_fields +1024 if self._supports_getbug_extra_fields(): +1025 if extra_fields: +1026 ret["extra_fields"] = _convert_fields(extra_fields) +1027 return ret +1028 +1029 def _get_bug_autorefresh(self): +1030 """ +1031 This value is passed to Bug.autorefresh for all fetched bugs. +1032 If True, and an uncached attribute is requested from a Bug, +1033 the Bug will update its contents and try again. +1034 """ +1035 return self._bug_autorefresh +1036 +1037 def _set_bug_autorefresh(self, val): +1038 self._bug_autorefresh = bool(val) +1039 bug_autorefresh = property(_get_bug_autorefresh, _set_bug_autorefresh) +1040 +1041 +1042 def _getbug_extra_fields(self): +1043 """ +1044 Extra fields that need to be explicitly +1045 requested from Bug.get in order for the data to be returned. +1046 """ +1047 rhbz_extra_fields = [ +1048 "comments", "description", +1049 "external_bugs", "flags", "sub_components", +1050 "tags", +1051 ] +1052 if self._is_redhat_bugzilla: +1053 return rhbz_extra_fields +1054 return [] +1055 +1056 def _supports_getbug_extra_fields(self): +1057 """ +1058 Return True if the bugzilla instance supports passing +1059 extra_fields to getbug +1060 +1061 As of Dec 2012 it seems like only RH bugzilla actually has behavior +1062 like this, for upstream bz it returns all info for every Bug.get() +1063 """ +1064 return self._is_redhat_bugzilla +1065 +1066 +1067 def _getbugs(self, idlist, permissive, +1068 include_fields=None, exclude_fields=None, extra_fields=None): +1069 """ +1070 Return a list of dicts of full bug info for each given bug id. +1071 bug ids that couldn't be found will return None instead of a dict. +1072 """ +1073 ids = [] +1074 aliases = [] +1075 +1076 def _alias_or_int(_v): +1077 if str(_v).isdigit(): +1078 return int(_v), None +1079 return None, str(_v) +1080 +1081 for idstr in idlist: +1082 idint, alias = _alias_or_int(idstr) +1083 if alias: +1084 aliases.append(alias) +1085 else: +1086 ids.append(idstr) +1087 +1088 if (include_fields is not None and aliases +1089 and "alias" not in include_fields): +1090 # Extra field to prevent sorting (see below) from causing an error +1091 include_fields.append("alias") +1092 +1093 extra_fields = listify(extra_fields or []) +1094 extra_fields += self._getbug_extra_fields() +1095 +1096 getbugdata = {} +1097 if permissive: +1098 getbugdata["permissive"] = 1 +1099 +1100 getbugdata.update(self._process_include_fields( +1101 include_fields, exclude_fields, extra_fields)) +1102 +1103 r = self._backend.bug_get(ids, aliases, getbugdata) +1104 +1105 # Do some wrangling to ensure we return bugs in the same order +1106 # the were passed in, for historical reasons +1107 ret = [] +1108 for idval in idlist: +1109 idint, alias = _alias_or_int(idval) +1110 for bugdict in r["bugs"]: +1111 if idint is not None and idint != bugdict.get("id", None): +1112 continue +1113 aliaslist = listify(bugdict.get("alias", None) or []) +1114 if alias and alias not in aliaslist: +1115 continue +1116 +1117 ret.append(bugdict) +1118 break +1119 return ret +1120 +1121 def _getbug(self, objid, **kwargs): +1122 """ +1123 Thin wrapper around _getbugs to handle the slight argument tweaks +1124 for fetching a single bug. The main bit is permissive=False, which +1125 will tell bugzilla to raise an explicit error if we can't fetch +1126 that bug. +1127 +1128 This logic is called from Bug() too +1129 """ +1130 return self._getbugs([objid], permissive=False, **kwargs)[0] +1131 +1132 def getbug(self, objid, +1133 include_fields=None, exclude_fields=None, extra_fields=None): +1134 """ +1135 Return a Bug object with the full complement of bug data +1136 already loaded. +1137 """ +1138 data = self._getbug(objid, +1139 include_fields=include_fields, exclude_fields=exclude_fields, +1140 extra_fields=extra_fields) +1141 return Bug(self, dict=data, autorefresh=self.bug_autorefresh) +1142 +1143 def getbugs(self, idlist, +1144 include_fields=None, exclude_fields=None, extra_fields=None, +1145 permissive=True): +1146 """ +1147 Return a list of Bug objects with the full complement of bug data +1148 already loaded. If there's a problem getting the data for a given id, +1149 the corresponding item in the returned list will be None. +1150 """ +1151 data = self._getbugs(idlist, include_fields=include_fields, +1152 exclude_fields=exclude_fields, extra_fields=extra_fields, +1153 permissive=permissive) +1154 return [(b and Bug(self, dict=b, +1155 autorefresh=self.bug_autorefresh)) or None +1156 for b in data] +1157 +1158 def get_comments(self, idlist): +1159 """ +1160 Returns a dictionary of bugs and comments. The comments key will +1161 be empty. See bugzilla docs for details +1162 """ +1163 return self._backend.bug_comments(idlist, {}) +1164 +1165 +1166 ################# +1167 # query methods # +1168 ################# +1169 +1170 def build_query(self, +1171 product=None, +1172 component=None, +1173 version=None, +1174 long_desc=None, +1175 bug_id=None, +1176 short_desc=None, +1177 cc=None, +1178 assigned_to=None, +1179 reporter=None, +1180 qa_contact=None, +1181 status=None, +1182 blocked=None, +1183 dependson=None, +1184 keywords=None, +1185 keywords_type=None, +1186 url=None, +1187 url_type=None, +1188 status_whiteboard=None, +1189 status_whiteboard_type=None, +1190 fixed_in=None, +1191 fixed_in_type=None, +1192 flag=None, +1193 alias=None, +1194 qa_whiteboard=None, +1195 devel_whiteboard=None, +1196 bug_severity=None, +1197 priority=None, +1198 target_release=None, +1199 target_milestone=None, +1200 emailtype=None, +1201 include_fields=None, +1202 quicksearch=None, +1203 savedsearch=None, +1204 savedsearch_sharer_id=None, +1205 sub_component=None, +1206 tags=None, +1207 exclude_fields=None, +1208 extra_fields=None, +1209 limit=None, +1210 resolution=None): +1211 """ +1212 Build a query string from passed arguments. Will handle +1213 query parameter differences between various bugzilla versions. +1214 +1215 Most of the parameters should be self-explanatory. However, +1216 if you want to perform a complex query, and easy way is to +1217 create it with the bugzilla web UI, copy the entire URL it +1218 generates, and pass it to the static method +1219 +1220 Bugzilla.url_to_query +1221 +1222 Then pass the output to Bugzilla.query() +1223 +1224 For details about the specific argument formats, see the bugzilla docs: +1225 https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#search-bugs +1226 """ +1227 query = { +1228 "alias": alias, +1229 "product": listify(product), +1230 "component": listify(component), +1231 "version": version, +1232 "id": bug_id, +1233 "short_desc": short_desc, +1234 "bug_status": status, +1235 "bug_severity": bug_severity, +1236 "priority": priority, +1237 "target_release": target_release, +1238 "target_milestone": target_milestone, +1239 "tag": listify(tags), +1240 "quicksearch": quicksearch, +1241 "savedsearch": savedsearch, +1242 "sharer_id": savedsearch_sharer_id, +1243 "limit": limit, +1244 "resolution": resolution, +1245 +1246 # RH extensions... don't add any more. See comment below +1247 "sub_components": listify(sub_component), +1248 } +1249 +1250 def add_bool(bzkey, value, bool_id, booltype=None): +1251 value = listify(value) +1252 if value is None: +1253 return bool_id +1254 +1255 query["query_format"] = "advanced" +1256 for boolval in value: +1257 def make_bool_str(prefix): +1258 # pylint: disable=cell-var-from-loop +1259 return "%s%i-0-0" % (prefix, bool_id) +1260 +1261 query[make_bool_str("field")] = bzkey +1262 query[make_bool_str("value")] = boolval +1263 query[make_bool_str("type")] = booltype or "substring" +1264 +1265 bool_id += 1 +1266 return bool_id +1267 +1268 # RH extensions that we have to maintain here for back compat, +1269 # but all future custom fields should be specified via +1270 # cli --field option, or via extending the query dict() manually. +1271 # No more supporting custom fields in this API +1272 bool_id = 0 +1273 bool_id = add_bool("keywords", keywords, bool_id, keywords_type) +1274 bool_id = add_bool("blocked", blocked, bool_id) +1275 bool_id = add_bool("dependson", dependson, bool_id) +1276 bool_id = add_bool("bug_file_loc", url, bool_id, url_type) +1277 bool_id = add_bool("cf_fixed_in", fixed_in, bool_id, fixed_in_type) +1278 bool_id = add_bool("flagtypes.name", flag, bool_id) +1279 bool_id = add_bool("status_whiteboard", +1280 status_whiteboard, bool_id, status_whiteboard_type) +1281 bool_id = add_bool("cf_qa_whiteboard", qa_whiteboard, bool_id) +1282 bool_id = add_bool("cf_devel_whiteboard", devel_whiteboard, bool_id) +1283 +1284 def add_email(key, value, count): +1285 if value is None: +1286 return count +1287 if not emailtype: +1288 query[key] = value +1289 return count +1290 +1291 query["query_format"] = "advanced" +1292 query['email%i' % count] = value +1293 query['email%s%i' % (key, count)] = True +1294 query['emailtype%i' % count] = emailtype +1295 return count + 1 +1296 +1297 email_count = 1 +1298 email_count = add_email("cc", cc, email_count) +1299 email_count = add_email("assigned_to", assigned_to, email_count) +1300 email_count = add_email("reporter", reporter, email_count) +1301 email_count = add_email("qa_contact", qa_contact, email_count) +1302 +1303 if long_desc is not None: +1304 query["query_format"] = "advanced" +1305 query["longdesc"] = long_desc +1306 query["longdesc_type"] = "allwordssubstr" +1307 +1308 # 'include_fields' only available for Bugzilla4+ +1309 # 'extra_fields' is an RHBZ extension +1310 query.update(self._process_include_fields( +1311 include_fields, exclude_fields, extra_fields)) +1312 +1313 # Strip out None elements in the dict +1314 for k, v in query.copy().items(): +1315 if v is None: +1316 del query[k] +1317 +1318 self.pre_translation(query) +1319 return query +1320 +1321 +1322 def query_return_extra(self, query): +1323 """ +1324 Same as `query()`, but the return value is altered to be +1325 (buglist, values), where `values` is raw dictionary output from +1326 the API call, excluding the bug content. For example this may +1327 include a `limit` value if the bugzilla instance puts an implied +1328 limit on returned result numbers. +1329 """ +1330 try: +1331 r = self._backend.bug_search(query) +1332 log.debug("bug_search returned:\n%s", str(r)) +1333 except Exception as e: +1334 # Try to give a hint in the error message if url_to_query +1335 # isn't supported by this bugzilla instance +1336 if ("query_format" not in str(e) or +1337 not BugzillaError.get_bugzilla_error_code(e) or +1338 self._get_version() >= 5.0): +1339 raise +1340 raise BugzillaError("%s\nYour bugzilla instance does not " +1341 "appear to support API queries derived from bugzilla " +1342 "web URL queries." % e) from None +1343 +1344 rawbugs = r.pop("bugs") +1345 log.debug("Query returned %s bugs", len(rawbugs)) +1346 bugs = [Bug(self, dict=b, +1347 autorefresh=self.bug_autorefresh) for b in rawbugs] +1348 +1349 return bugs, r +1350 +1351 def query(self, query): +1352 """ +1353 Pass search terms to bugzilla and and return a list of matching +1354 Bug objects. +1355 +1356 See `build_query` for more details about constructing the +1357 `query` dict parameter. +1358 """ +1359 bugs, dummy = self.query_return_extra(query) +1360 return bugs +1361 +1362 def pre_translation(self, query): +1363 """ +1364 In order to keep the API the same, Bugzilla4 needs to process the +1365 query and the result. This also applies to the refresh() function +1366 """ +1367 if self._is_redhat_bugzilla: +1368 _RHBugzillaConverters.pre_translation(query) +1369 query.update(self._process_include_fields( +1370 query.get("include_fields", []), None, None)) +1371 +1372 def post_translation(self, query, bug): +1373 """ +1374 In order to keep the API the same, Bugzilla4 needs to process the +1375 query and the result. This also applies to the refresh() function +1376 """ +1377 if self._is_redhat_bugzilla: +1378 _RHBugzillaConverters.post_translation(query, bug) +1379 +1380 def bugs_history_raw(self, bug_ids): +1381 """ +1382 Experimental. Gets the history of changes for +1383 particular bugs in the database. +1384 """ +1385 return self._backend.bug_history(bug_ids, {}) +1386 +1387 +1388 ####################################### +1389 # Methods for modifying existing bugs # +1390 ####################################### +1391 +1392 # Bug() also has individual methods for many ops, like setassignee() +1393 +1394 def update_bugs(self, ids, updates): +1395 """ +1396 A thin wrapper around bugzilla Bug.update(). Used to update all +1397 values of an existing bug report, as well as add comments. +1398 +1399 The dictionary passed to this function should be generated with +1400 build_update(), otherwise we cannot guarantee back compatibility. +1401 """ +1402 tmp = updates.copy() +1403 return self._backend.bug_update(listify(ids), tmp) +1404 +1405 def update_tags(self, idlist, tags_add=None, tags_remove=None): +1406 """ +1407 Updates the 'tags' field for a bug. +1408 """ +1409 tags = {} +1410 if tags_add: +1411 tags["add"] = listify(tags_add) +1412 if tags_remove: +1413 tags["remove"] = listify(tags_remove) +1414 +1415 d = { +1416 "tags": tags, +1417 } +1418 +1419 return self._backend.bug_update_tags(listify(idlist), d) +1420 +1421 def update_flags(self, idlist, flags): +1422 """ +1423 A thin back compat wrapper around build_update(flags=X) +1424 """ +1425 return self.update_bugs(idlist, self.build_update(flags=flags)) +1426 +1427 +1428 def build_update(self, +1429 alias=None, +1430 assigned_to=None, +1431 blocks_add=None, +1432 blocks_remove=None, +1433 blocks_set=None, +1434 depends_on_add=None, +1435 depends_on_remove=None, +1436 depends_on_set=None, +1437 cc_add=None, +1438 cc_remove=None, +1439 is_cc_accessible=None, +1440 comment=None, +1441 comment_private=None, +1442 component=None, +1443 deadline=None, +1444 dupe_of=None, +1445 estimated_time=None, +1446 groups_add=None, +1447 groups_remove=None, +1448 keywords_add=None, +1449 keywords_remove=None, +1450 keywords_set=None, +1451 op_sys=None, +1452 platform=None, +1453 priority=None, +1454 product=None, +1455 qa_contact=None, +1456 is_creator_accessible=None, +1457 remaining_time=None, +1458 reset_assigned_to=None, +1459 reset_qa_contact=None, +1460 resolution=None, +1461 see_also_add=None, +1462 see_also_remove=None, +1463 severity=None, +1464 status=None, +1465 summary=None, +1466 target_milestone=None, +1467 target_release=None, +1468 url=None, +1469 version=None, +1470 whiteboard=None, +1471 work_time=None, +1472 fixed_in=None, +1473 qa_whiteboard=None, +1474 devel_whiteboard=None, +1475 internal_whiteboard=None, +1476 sub_component=None, +1477 flags=None, +1478 comment_tags=None, +1479 minor_update=None): +1480 """ +1481 Returns a python dict() with properly formatted parameters to +1482 pass to update_bugs(). See bugzilla documentation for the format +1483 of the individual fields: +1484 +1485 https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#create-bug +1486 """ +1487 ret = {} +1488 rhbzret = {} +1489 +1490 # These are only supported for rhbugzilla +1491 # +1492 # This should not be extended any more. +1493 # If people want to handle custom fields, manually extend the +1494 # returned dictionary. +1495 rhbzargs = { +1496 "fixed_in": fixed_in, +1497 "devel_whiteboard": devel_whiteboard, +1498 "qa_whiteboard": qa_whiteboard, +1499 "internal_whiteboard": internal_whiteboard, +1500 "sub_component": sub_component, +1501 } +1502 if self._is_redhat_bugzilla: +1503 rhbzret = _RHBugzillaConverters.convert_build_update( +1504 component=component, **rhbzargs) +1505 else: +1506 for key, val in rhbzargs.items(): +1507 if val is not None: +1508 raise ValueError("bugzilla instance does not support " +1509 "updating '%s'" % key) +1510 +1511 def s(key, val, convert=None): +1512 if val is None: +1513 return +1514 if convert: +1515 val = convert(val) +1516 ret[key] = val +1517 +1518 def add_dict(key, add, remove, _set=None): +1519 if add is remove is _set is None: +1520 return +1521 +1522 newdict = {} +1523 if add is not None: +1524 newdict["add"] = listify(add) +1525 if remove is not None: +1526 newdict["remove"] = listify(remove) +1527 if _set is not None: +1528 newdict["set"] = listify(_set) +1529 ret[key] = newdict +1530 +1531 +1532 s("alias", alias) +1533 s("assigned_to", assigned_to) +1534 s("is_cc_accessible", is_cc_accessible, bool) +1535 s("component", component) +1536 s("deadline", deadline) +1537 s("dupe_of", dupe_of, int) +1538 s("estimated_time", estimated_time, int) +1539 s("op_sys", op_sys) +1540 s("platform", platform) +1541 s("priority", priority) +1542 s("product", product) +1543 s("qa_contact", qa_contact) +1544 s("is_creator_accessible", is_creator_accessible, bool) +1545 s("remaining_time", remaining_time, float) +1546 s("reset_assigned_to", reset_assigned_to, bool) +1547 s("reset_qa_contact", reset_qa_contact, bool) +1548 s("resolution", resolution) +1549 s("severity", severity) +1550 s("status", status) +1551 s("summary", summary) +1552 s("target_milestone", target_milestone) +1553 s("target_release", target_release) +1554 s("url", url) +1555 s("version", version) +1556 s("whiteboard", whiteboard) +1557 s("work_time", work_time, float) +1558 s("flags", flags) +1559 s("comment_tags", comment_tags, listify) +1560 s("minor_update", minor_update, bool) +1561 +1562 add_dict("blocks", blocks_add, blocks_remove, blocks_set) +1563 add_dict("depends_on", depends_on_add, depends_on_remove, depends_on_set) +1564 add_dict("cc", cc_add, cc_remove) +1565 add_dict("groups", groups_add, groups_remove) +1566 add_dict("keywords", keywords_add, keywords_remove, keywords_set) +1567 add_dict("see_also", see_also_add, see_also_remove) +1568 +1569 if comment is not None: +1570 ret["comment"] = {"comment": comment} +1571 if comment_private: +1572 ret["comment"]["is_private"] = comment_private +1573 +1574 ret.update(rhbzret) +1575 return ret +1576 +1577 +1578 ######################################## +1579 # Methods for working with attachments # +1580 ######################################## +1581 +1582 def attachfile(self, idlist, attachfile, description, **kwargs): +1583 """ +1584 Attach a file to the given bug IDs. Returns the ID of the attachment +1585 or raises XMLRPC Fault if something goes wrong. +1586 +1587 attachfile may be a filename (which will be opened) or a file-like +1588 object, which must provide a 'read' method. If it's not one of these, +1589 this method will raise a TypeError. +1590 description is the short description of this attachment. +1591 +1592 Optional keyword args are as follows: +1593 file_name: this will be used as the filename for the attachment. +1594 REQUIRED if attachfile is a file-like object with no +1595 'name' attribute, otherwise the filename or .name +1596 attribute will be used. +1597 comment: An optional comment about this attachment. +1598 is_private: Set to True if the attachment should be marked private. +1599 is_patch: Set to True if the attachment is a patch. +1600 content_type: The mime-type of the attached file. Defaults to +1601 application/octet-stream if not set. NOTE that text +1602 files will *not* be viewable in bugzilla unless you +1603 remember to set this to text/plain. So remember that! +1604 +1605 Returns the list of attachment ids that were added. If only one +1606 attachment was added, we return the single int ID for back compat +1607 """ +1608 if isinstance(attachfile, str): +1609 f = open(attachfile, "rb") +1610 elif hasattr(attachfile, 'read'): +1611 f = attachfile +1612 else: +1613 raise TypeError("attachfile must be filename or file-like object") +1614 +1615 # Back compat +1616 if "contenttype" in kwargs: +1617 kwargs["content_type"] = kwargs.pop("contenttype") +1618 if "ispatch" in kwargs: +1619 kwargs["is_patch"] = kwargs.pop("ispatch") +1620 if "isprivate" in kwargs: +1621 kwargs["is_private"] = kwargs.pop("isprivate") +1622 if "filename" in kwargs: +1623 kwargs["file_name"] = kwargs.pop("filename") +1624 +1625 kwargs['summary'] = description +1626 +1627 data = f.read() +1628 if not isinstance(data, bytes): # pragma: no cover +1629 data = data.encode(locale.getpreferredencoding()) +1630 +1631 if 'file_name' not in kwargs and hasattr(f, "name"): +1632 kwargs['file_name'] = os.path.basename(f.name) +1633 if 'content_type' not in kwargs: +1634 ctype = None +1635 if kwargs['file_name']: +1636 ctype = mimetypes.guess_type( +1637 kwargs['file_name'], strict=False)[0] +1638 kwargs['content_type'] = ctype or 'application/octet-stream' +1639 +1640 ret = self._backend.bug_attachment_create( +1641 listify(idlist), data, kwargs) +1642 +1643 if "attachments" in ret: +1644 # Up to BZ 4.2 +1645 ret = [int(k) for k in ret["attachments"].keys()] +1646 elif "ids" in ret: +1647 # BZ 4.4+ +1648 ret = ret["ids"] +1649 +1650 if isinstance(ret, list) and len(ret) == 1: +1651 ret = ret[0] +1652 return ret +1653 +1654 def openattachment_data(self, attachment_dict): +1655 """ +1656 Helper for turning passed API attachment dictionary into a +1657 filelike object +1658 """ +1659 ret = BytesIO() +1660 data = attachment_dict["data"] +1661 +1662 if hasattr(data, "data"): +1663 # This is for xmlrpc Binary +1664 content = data.data # pragma: no cover +1665 else: +1666 import base64 +1667 content = base64.b64decode(data) +1668 +1669 ret.write(content) +1670 ret.name = attachment_dict["file_name"] +1671 ret.seek(0) +1672 return ret +1673 +1674 def openattachment(self, attachid): +1675 """ +1676 Get the contents of the attachment with the given attachment ID. +1677 Returns a file-like object. +1678 """ +1679 attachments = self.get_attachments(None, attachid) +1680 data = attachments["attachments"][str(attachid)] +1681 return self.openattachment_data(data) +1682 +1683 def updateattachmentflags(self, bugid, attachid, flagname, **kwargs): +1684 """ +1685 Updates a flag for the given attachment ID. +1686 Optional keyword args are: +1687 status: new status for the flag ('-', '+', '?', 'X') +1688 requestee: new requestee for the flag +1689 """ +1690 # Bug ID was used for the original custom redhat API, no longer +1691 # needed though +1692 ignore = bugid +1693 +1694 flags = {"name": flagname} +1695 flags.update(kwargs) +1696 attachment_ids = [int(attachid)] +1697 update = {'flags': [flags]} +1698 +1699 return self._backend.bug_attachment_update(attachment_ids, update) +1700 +1701 def get_attachments(self, ids, attachment_ids, +1702 include_fields=None, exclude_fields=None): +1703 """ +1704 Wrapper for Bug.attachments. One of ids or attachment_ids is required +1705 +1706 :param ids: Get attachments for this bug ID +1707 :param attachment_ids: Specific attachment ID to get +1708 +1709 https://bugzilla.readthedocs.io/en/latest/api/core/v1/attachment.html#get-attachment +1710 """ +1711 params = {} +1712 if include_fields: +1713 params["include_fields"] = listify(include_fields) +1714 if exclude_fields: +1715 params["exclude_fields"] = listify(exclude_fields) +1716 +1717 if attachment_ids: +1718 return self._backend.bug_attachment_get(attachment_ids, params) +1719 return self._backend.bug_attachment_get_all(ids, params) +1720 +1721 +1722 ##################### +1723 # createbug methods # +1724 ##################### +1725 +1726 createbug_required = ('product', 'component', 'summary', 'version', +1727 'description') +1728 +1729 def build_createbug(self, +1730 product=None, +1731 component=None, +1732 version=None, +1733 summary=None, +1734 description=None, +1735 comment_private=None, +1736 blocks=None, +1737 cc=None, +1738 assigned_to=None, +1739 keywords=None, +1740 depends_on=None, +1741 groups=None, +1742 op_sys=None, +1743 platform=None, +1744 priority=None, +1745 qa_contact=None, +1746 resolution=None, +1747 severity=None, +1748 status=None, +1749 target_milestone=None, +1750 target_release=None, +1751 url=None, +1752 sub_component=None, +1753 alias=None, +1754 comment_tags=None): +1755 """ +1756 Returns a python dict() with properly formatted parameters to +1757 pass to createbug(). See bugzilla documentation for the format +1758 of the individual fields: +1759 +1760 https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#update-bug +1761 """ +1762 +1763 localdict = {} +1764 if blocks: +1765 localdict["blocks"] = listify(blocks) +1766 if cc: +1767 localdict["cc"] = listify(cc) +1768 if depends_on: +1769 localdict["depends_on"] = listify(depends_on) +1770 if groups is not None: +1771 localdict["groups"] = listify(groups) +1772 if keywords: +1773 localdict["keywords"] = listify(keywords) +1774 if description: +1775 localdict["description"] = description +1776 if comment_private: +1777 localdict["comment_is_private"] = True +1778 +1779 # Most of the machinery and formatting here is the same as +1780 # build_update, so reuse that as much as possible +1781 ret = self.build_update(product=product, component=component, +1782 version=version, summary=summary, op_sys=op_sys, +1783 platform=platform, priority=priority, qa_contact=qa_contact, +1784 resolution=resolution, severity=severity, status=status, +1785 target_milestone=target_milestone, +1786 target_release=target_release, url=url, +1787 assigned_to=assigned_to, sub_component=sub_component, +1788 alias=alias, comment_tags=comment_tags) +1789 +1790 ret.update(localdict) +1791 return ret +1792 +1793 def _validate_createbug(self, *args, **kwargs): +1794 # Previous API required users specifying keyword args that mapped +1795 # to the XMLRPC arg names. Maintain that bad compat, but also allow +1796 # receiving a single dictionary like query() does +1797 if kwargs and args: # pragma: no cover +1798 raise BugzillaError("createbug: cannot specify positional " +1799 "args=%s with kwargs=%s, must be one or the " +1800 "other." % (args, kwargs)) +1801 if args: +1802 if len(args) > 1 or not isinstance(args[0], dict): +1803 raise BugzillaError( # pragma: no cover +1804 "createbug: positional arguments only " +1805 "accept a single dictionary.") +1806 data = args[0] +1807 else: +1808 data = kwargs +1809 +1810 # If we're getting a call that uses an old fieldname, convert it to the +1811 # new fieldname instead. +1812 for newname, oldname in self._get_api_aliases(): +1813 if (newname in self.createbug_required and +1814 newname not in data and +1815 oldname in data): +1816 data[newname] = data.pop(oldname) +1817 +1818 # Back compat handling for check_args +1819 if "check_args" in data: +1820 del data["check_args"] +1821 +1822 return data +1823 +1824 def createbug(self, *args, **kwargs): +1825 """ +1826 Create a bug with the given info. Returns a new Bug object. +1827 Check bugzilla API documentation for valid values, at least +1828 product, component, summary, version, and description need to +1829 be passed. +1830 """ +1831 data = self._validate_createbug(*args, **kwargs) +1832 rawbug = self._backend.bug_create(data) +1833 return Bug(self, bug_id=rawbug["id"], +1834 autorefresh=self.bug_autorefresh) +1835 +1836 +1837 ############################## +1838 # Methods for handling Users # +1839 ############################## +1840 +1841 def getuser(self, username): +1842 """ +1843 Return a bugzilla User for the given username +1844 +1845 :arg username: The username used in bugzilla. +1846 :raises XMLRPC Fault: Code 51 if the username does not exist +1847 :returns: User record for the username +1848 """ +1849 ret = self.getusers(username) +1850 return ret and ret[0] +1851 +1852 def getusers(self, userlist): +1853 """ +1854 Return a list of Users from . +1855 +1856 :userlist: List of usernames to lookup +1857 :returns: List of User records +1858 """ +1859 userlist = listify(userlist) +1860 rawusers = self._backend.user_get({"names": userlist}) +1861 userobjs = [User(self, **rawuser) for rawuser in +1862 rawusers.get('users', [])] +1863 +1864 # Return users in same order they were passed in +1865 ret = [] +1866 for u in userlist: +1867 for uobj in userobjs[:]: +1868 if uobj.email == u: +1869 userobjs.remove(uobj) +1870 ret.append(uobj) +1871 break +1872 ret += userobjs +1873 return ret +1874 +1875 +1876 def searchusers(self, pattern): +1877 """ +1878 Return a bugzilla User for the given list of patterns +1879 +1880 :arg pattern: List of patterns to match against. +1881 :returns: List of User records +1882 """ +1883 rawusers = self._backend.user_get({"match": listify(pattern)}) +1884 return [User(self, **rawuser) for rawuser in +1885 rawusers.get('users', [])] +1886 +1887 def createuser(self, email, name='', password=''): +1888 """ +1889 Return a bugzilla User for the given username +1890 +1891 :arg email: The email address to use in bugzilla +1892 :kwarg name: Real name to associate with the account +1893 :kwarg password: Password to set for the bugzilla account +1894 :raises XMLRPC Fault: Code 501 if the username already exists +1895 Code 500 if the email address isn't valid +1896 Code 502 if the password is too short +1897 Code 503 if the password is too long +1898 :return: User record for the username +1899 """ +1900 args = {"email": email} +1901 if name: +1902 args["name"] = name +1903 if password: +1904 args["password"] = password +1905 self._backend.user_create(args) +1906 return self.getuser(email) +1907 +1908 def updateperms(self, user, action, groups): +1909 """ +1910 A method to update the permissions (group membership) of a bugzilla +1911 user. +1912 +1913 :arg user: The e-mail address of the user to be acted upon. Can +1914 also be a list of emails. +1915 :arg action: add, remove, or set +1916 :arg groups: list of groups to be added to (i.e. ['fedora_contrib']) +1917 """ +1918 groups = listify(groups) +1919 if action == "rem": +1920 action = "remove" +1921 if action not in ["add", "remove", "set"]: +1922 raise BugzillaError("Unknown user permission action '%s'" % action) +1923 +1924 update = { +1925 "names": listify(user), +1926 "groups": { +1927 action: groups, +1928 } +1929 } +1930 +1931 return self._backend.user_update(update) +1932 +1933 +1934 ############################### +1935 # Methods for handling Groups # +1936 ############################### +1937 +1938 def _getgroups(self, names, membership=False): +1939 """ +1940 Return a list of groups that match criteria. +1941 +1942 :kwarg ids: list of group ids to return data on +1943 :kwarg membership: boolean specifying wether to query the members +1944 of the group or not. +1945 :raises XMLRPC Fault: Code 51: if a Bad Login Name was sent to the +1946 names array. +1947 Code 304: if the user was not authorized to see user they +1948 requested. +1949 Code 505: user is logged out and can't use the match or ids +1950 parameter. +1951 Code 805: logged in user do not have enough priviledges to view +1952 groups. +1953 """ +1954 params = {"membership": membership} +1955 params['names'] = listify(names) +1956 return self._backend.group_get(params) +1957 +1958 def getgroup(self, name, membership=False): +1959 """ +1960 Return a bugzilla Group for the given name +1961 +1962 :arg name: The group name used in bugzilla. +1963 :raises XMLRPC Fault: Code 51 if the name does not exist +1964 :raises XMLRPC Fault: Code 805 if the user does not have enough +1965 permissions to view groups +1966 :returns: Group record for the name +1967 """ +1968 ret = self.getgroups(name, membership=membership) +1969 return ret and ret[0] +1970 +1971 def getgroups(self, grouplist, membership=False): +1972 """ +1973 Return a list of Groups from . +1974 +1975 :userlist: List of group names to lookup +1976 :returns: List of Group records +1977 """ +1978 grouplist = listify(grouplist) +1979 groupobjs = [ +1980 Group(self, **rawgroup) +1981 for rawgroup in self._getgroups( +1982 names=grouplist, membership=membership).get('groups', []) +1983 ] +1984 +1985 # Return in same order they were passed in +1986 ret = [] +1987 for g in grouplist: +1988 for gobj in groupobjs[:]: +1989 if gobj.name == g: +1990 groupobjs.remove(gobj) +1991 ret.append(gobj) +1992 break +1993 ret += groupobjs +1994 return ret +1995 +1996 +1997 ############################# +1998 # ExternalBugs API wrappers # +1999 ############################# +2000 +2001 def add_external_tracker(self, bug_ids, ext_bz_bug_id, ext_type_id=None, +2002 ext_type_description=None, ext_type_url=None, +2003 ext_status=None, ext_description=None, +2004 ext_priority=None): +2005 """ +2006 Wrapper method to allow adding of external tracking bugs using the +2007 ExternalBugs::WebService::add_external_bug method. +2008 +2009 This is documented at +2010 https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#add-external-bug +2011 +2012 bug_ids: A single bug id or list of bug ids to have external trackers +2013 added. +2014 ext_bz_bug_id: The external bug id (ie: the bug number in the +2015 external tracker). +2016 ext_type_id: The external tracker id as used by Bugzilla. +2017 ext_type_description: The external tracker description as used by +2018 Bugzilla. +2019 ext_type_url: The external tracker url as used by Bugzilla. +2020 ext_status: The status of the external bug. +2021 ext_description: The description of the external bug. +2022 ext_priority: The priority of the external bug. +2023 """ +2024 param_dict = {'ext_bz_bug_id': ext_bz_bug_id} +2025 if ext_type_id is not None: +2026 param_dict['ext_type_id'] = ext_type_id +2027 if ext_type_description is not None: +2028 param_dict['ext_type_description'] = ext_type_description +2029 if ext_type_url is not None: +2030 param_dict['ext_type_url'] = ext_type_url +2031 if ext_status is not None: +2032 param_dict['ext_status'] = ext_status +2033 if ext_description is not None: +2034 param_dict['ext_description'] = ext_description +2035 if ext_priority is not None: +2036 param_dict['ext_priority'] = ext_priority +2037 params = { +2038 'bug_ids': listify(bug_ids), +2039 'external_bugs': [param_dict], +2040 } +2041 return self._backend.externalbugs_add(params) +2042 +2043 def update_external_tracker(self, ids=None, ext_type_id=None, +2044 ext_type_description=None, ext_type_url=None, +2045 ext_bz_bug_id=None, bug_ids=None, +2046 ext_status=None, ext_description=None, +2047 ext_priority=None): +2048 """ +2049 Wrapper method to allow adding of external tracking bugs using the +2050 ExternalBugs::WebService::update_external_bug method. +2051 +2052 This is documented at +2053 https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#update-external-bug +2054 +2055 ids: A single external tracker bug id or list of external tracker bug +2056 ids. +2057 ext_type_id: The external tracker id as used by Bugzilla. +2058 ext_type_description: The external tracker description as used by +2059 Bugzilla. +2060 ext_type_url: The external tracker url as used by Bugzilla. +2061 ext_bz_bug_id: A single external bug id or list of external bug ids +2062 (ie: the bug number in the external tracker). +2063 bug_ids: A single bug id or list of bug ids to have external tracker +2064 info updated. +2065 ext_status: The status of the external bug. +2066 ext_description: The description of the external bug. +2067 ext_priority: The priority of the external bug. +2068 """ +2069 params = {} +2070 if ids is not None: +2071 params['ids'] = listify(ids) +2072 if ext_type_id is not None: +2073 params['ext_type_id'] = ext_type_id +2074 if ext_type_description is not None: +2075 params['ext_type_description'] = ext_type_description +2076 if ext_type_url is not None: +2077 params['ext_type_url'] = ext_type_url +2078 if ext_bz_bug_id is not None: +2079 params['ext_bz_bug_id'] = listify(ext_bz_bug_id) +2080 if bug_ids is not None: +2081 params['bug_ids'] = listify(bug_ids) +2082 if ext_status is not None: +2083 params['ext_status'] = ext_status +2084 if ext_description is not None: +2085 params['ext_description'] = ext_description +2086 if ext_priority is not None: +2087 params['ext_priority'] = ext_priority +2088 return self._backend.externalbugs_update(params) +2089 +2090 def remove_external_tracker(self, ids=None, ext_type_id=None, +2091 ext_type_description=None, ext_type_url=None, +2092 ext_bz_bug_id=None, bug_ids=None): +2093 """ +2094 Wrapper method to allow removal of external tracking bugs using the +2095 ExternalBugs::WebService::remove_external_bug method. +2096 +2097 This is documented at +2098 https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#remove-external-bug +2099 +2100 ids: A single external tracker bug id or list of external tracker bug +2101 ids. +2102 ext_type_id: The external tracker id as used by Bugzilla. +2103 ext_type_description: The external tracker description as used by +2104 Bugzilla. +2105 ext_type_url: The external tracker url as used by Bugzilla. +2106 ext_bz_bug_id: A single external bug id or list of external bug ids +2107 (ie: the bug number in the external tracker). +2108 bug_ids: A single bug id or list of bug ids to have external tracker +2109 info updated. +2110 """ +2111 params = {} +2112 if ids is not None: +2113 params['ids'] = listify(ids) +2114 if ext_type_id is not None: +2115 params['ext_type_id'] = ext_type_id +2116 if ext_type_description is not None: +2117 params['ext_type_description'] = ext_type_description +2118 if ext_type_url is not None: +2119 params['ext_type_url'] = ext_type_url +2120 if ext_bz_bug_id is not None: +2121 params['ext_bz_bug_id'] = listify(ext_bz_bug_id) +2122 if bug_ids is not None: +2123 params['bug_ids'] = listify(bug_ids) +2124 return self._backend.externalbugs_remove(params) +
The main API object. Connects to a bugzilla instance over XMLRPC, and +provides wrapper functions to simplify dealing with API calls.
+ +The most common invocation here will just be with just a URL:
+ +bzapi = Bugzilla("http://bugzilla.example.com")
+If you have previously logged into that URL, and have cached login +tokens, you will automatically be logged in. Otherwise to +log in, you can either pass auth options to __init__, or call a login +helper like interactive_login().
+ +If you are not logged in, you won't be able to access restricted data like +user email, or perform write actions like bug create/update. But simple +querys will work correctly.
+ +If you are unsure if you are logged in, you can check the .logged_in +property.
+ +Another way to specify auth credentials is via a 'bugzillarc' file. +See readconfig() documentation for details.
+
+
+
+
+
+
+
+
+
+
+
+ Bugzilla( url=-1, user=None, password=None, cookiefile=-1, sslverify=True, tokenfile=-1, use_creds=True, api_key=None, cert=None, configpaths=-1, force_rest=False, force_xmlrpc=False, requests_session=None)
+
+
+
+
+
+ 178 def __init__(self, url=-1, user=None, password=None, cookiefile=-1, +179 sslverify=True, tokenfile=-1, use_creds=True, api_key=None, +180 cert=None, configpaths=-1, +181 force_rest=False, force_xmlrpc=False, requests_session=None): +182 """ +183 :param url: The bugzilla instance URL, which we will connect +184 to immediately. Most users will want to specify this at +185 __init__ time, but you can defer connecting by passing +186 url=None and calling connect(URL) manually +187 :param user: optional username to connect with +188 :param password: optional password for the connecting user +189 :param cert: optional certificate file for client side certificate +190 authentication +191 :param cookiefile: Deprecated, raises an error if not -1 or None +192 :param sslverify: Set this to False to skip SSL hostname and CA +193 validation checks, like out of date certificate +194 :param tokenfile: Location to cache the API login token so youi +195 don't have to keep specifying username/password. +196 If -1, use the default path. If None, don't use +197 or save any tokenfile. +198 :param use_creds: If False, this disables tokenfile +199 and configpaths by default. This is a convenience option to +200 unset those values at init time. If those values are later +201 changed, they may be used for future operations. +202 :param sslverify: Maps to 'requests' sslverify parameter. Set to +203 False to disable SSL verification, but it can also be a path +204 to file or directory for custom certs. +205 :param api_key: A bugzilla5+ API key +206 :param configpaths: A list of possible bugzillarc locations. +207 :param force_rest: Force use of the REST API +208 :param force_xmlrpc: Force use of the XMLRPC API. If neither force_X +209 parameter are specified, heuristics will be used to determine +210 which API to use, with XMLRPC preferred for back compatability. +211 :param requests_session: An optional requests.Session object the +212 API will use to contact the remote bugzilla instance. This +213 way the API user can set up whatever auth bits they may need. +214 """ +215 if url == -1: +216 raise TypeError("Specify a valid bugzilla url, or pass url=None") +217 +218 # Settings the user might want to tweak +219 self.user = user or '' +220 self.password = password or '' +221 self.api_key = api_key +222 self.cert = cert or None +223 self.url = '' +224 +225 self._backend = None +226 self._session = None +227 self._user_requests_session = requests_session +228 self._sslverify = sslverify +229 self._cache = _BugzillaAPICache() +230 self._bug_autorefresh = False +231 self._is_redhat_bugzilla = False +232 +233 self._rcfile = _BugzillaRCFile() +234 self._tokencache = _BugzillaTokenCache() +235 +236 self._force_rest = force_rest +237 self._force_xmlrpc = force_xmlrpc +238 +239 if cookiefile not in [None, -1]: +240 raise TypeError("cookiefile is deprecated, don't pass any value.") +241 +242 if not use_creds: +243 tokenfile = None +244 configpaths = [] +245 +246 if tokenfile == -1: +247 tokenfile = self._tokencache.get_default_path() +248 if configpaths == -1: +249 configpaths = _BugzillaRCFile.get_default_configpaths() +250 +251 self._settokenfile(tokenfile) +252 self._setconfigpath(configpaths) +253 +254 if url: +255 self.connect(url) +
Parameters
+ +-
+
- url: The bugzilla instance URL, which we will connect +to immediately. Most users will want to specify this at +__init__ time, but you can defer connecting by passing +url=None and calling connect(URL) manually +
- user: optional username to connect with +
- password: optional password for the connecting user +
- cert: optional certificate file for client side certificate +authentication +
- cookiefile: Deprecated, raises an error if not -1 or None +
- sslverify: Set this to False to skip SSL hostname and CA +validation checks, like out of date certificate +
- tokenfile: Location to cache the API login token so youi +don't have to keep specifying username/password. +If -1, use the default path. If None, don't use +or save any tokenfile. +
- use_creds: If False, this disables tokenfile +and configpaths by default. This is a convenience option to +unset those values at init time. If those values are later +changed, they may be used for future operations. +
- sslverify: Maps to 'requests' sslverify parameter. Set to +False to disable SSL verification, but it can also be a path +to file or directory for custom certs. +
- api_key: A bugzilla5+ API key +
- configpaths: A list of possible bugzillarc locations. +
- force_rest: Force use of the REST API +
- force_xmlrpc: Force use of the XMLRPC API. If neither force_X +parameter are specified, heuristics will be used to determine +which API to use, with XMLRPC preferred for back compatability. +
- requests_session: An optional requests.Session object the +API will use to contact the remote bugzilla instance. This +way the API user can set up whatever auth bits they may need. +
+
+
+
+
+
+
+
+
+
+
+
+ @staticmethod
+
+ def
+ url_to_query(url):
+
+
+
+ 104 @staticmethod +105 def url_to_query(url): +106 """ +107 Given a big huge bugzilla query URL, returns a query dict that can +108 be passed along to the Bugzilla.query() method. +109 """ +110 q = {} +111 +112 # pylint: disable=unpacking-non-sequence +113 (ignore1, ignore2, path, +114 ignore, query, ignore3) = urllib.parse.urlparse(url) +115 +116 base = os.path.basename(path) +117 if base not in ('buglist.cgi', 'query.cgi'): +118 return {} +119 +120 for (k, v) in urllib.parse.parse_qsl(query): +121 if k not in q: +122 q[k] = v +123 elif isinstance(q[k], list): +124 q[k].append(v) +125 else: +126 oldv = q[k] +127 q[k] = [oldv, v] +128 +129 # Handle saved searches +130 if base == "buglist.cgi" and "namedcmd" in q and "sharer_id" in q: +131 q = { +132 "sharer_id": q["sharer_id"], +133 "savedsearch": q["namedcmd"], +134 } +135 +136 return q +
Given a big huge bugzilla query URL, returns a query dict that can +be passed along to the Bugzilla.query() method.
+
+
+
+
+
+
+
+
+
+
+
+
+ @staticmethod
+
+ def
+ fix_url(url, force_rest=False):
+
+
+
+ 138 @staticmethod +139 def fix_url(url, force_rest=False): +140 """ +141 Turn passed url into a bugzilla XMLRPC web url +142 +143 :param force_rest: If True, generate a REST API url +144 """ +145 (scheme, netloc, path, +146 params, query, fragment) = urllib.parse.urlparse(url) +147 if not scheme: +148 scheme = 'https' +149 +150 if path and not netloc: +151 netloc = path.split("/", 1)[0] +152 path = "/".join(path.split("/")[1:]) or None +153 +154 if not path: +155 path = 'xmlrpc.cgi' +156 if force_rest: +157 path = "rest/" +158 +159 if not path.startswith("/"): +160 path = "/" + path +161 +162 newurl = urllib.parse.urlunparse( +163 (scheme, netloc, path, params, query, fragment)) +164 return newurl +
Turn passed url into a bugzilla XMLRPC web url
+ +Parameters
+ +-
+
- force_rest: If True, generate a REST API url +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ @staticmethod
+
+ def
+ get_rcfile_default_url():
+
+
+
+ 166 @staticmethod +167 def get_rcfile_default_url(): +168 """ +169 Helper to check all the default bugzillarc file paths for +170 a [DEFAULT] url=X section, and if found, return it. +171 """ +172 configpaths = _BugzillaRCFile.get_default_configpaths() +173 rcfile = _BugzillaRCFile() +174 rcfile.set_configpaths(configpaths) +175 return rcfile.get_default_url() +
Helper to check all the default bugzillarc file paths for +a [DEFAULT] url=X section, and if found, return it.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ readconfig(self, configpath=None, overwrite=True):
+
+
+
+
+
+ 392 def readconfig(self, configpath=None, overwrite=True): +393 """ +394 :param configpath: Optional bugzillarc path to read, instead of +395 the default list. +396 +397 This function is called automatically from Bugzilla connect(), which +398 is called at __init__ if a URL is passed. Calling it manually is +399 just for passing in a non-standard configpath. +400 +401 The locations for the bugzillarc file are preferred in this order: +402 +403 ~/.config/python-bugzilla/bugzillarc +404 ~/.bugzillarc +405 /etc/bugzillarc +406 +407 It has content like: +408 [bugzilla.yoursite.com] +409 user = username +410 password = password +411 Or +412 [bugzilla.yoursite.com] +413 api_key = key +414 +415 The file can have multiple sections for different bugzilla instances. +416 A 'url' field in the [DEFAULT] section can be used to set a default +417 URL for the bugzilla command line tool. +418 +419 Be sure to set appropriate permissions on bugzillarc if you choose to +420 store your password in it! +421 +422 :param overwrite: If True, bugzillarc will clobber any already +423 set self.user/password/api_key/cert value. +424 """ +425 if configpath: +426 self._setconfigpath(configpath) +427 data = self._rcfile.parse(self.url) +428 +429 for key, val in data.items(): +430 if key == "api_key" and (overwrite or not self.api_key): +431 log.debug("bugzillarc: setting api_key") +432 self.api_key = val +433 elif key == "user" and (overwrite or not self.user): +434 log.debug("bugzillarc: setting user=%s", val) +435 self.user = val +436 elif key == "password" and (overwrite or not self.password): +437 log.debug("bugzillarc: setting password") +438 self.password = val +439 elif key == "cert" and (overwrite or not self.cert): +440 log.debug("bugzillarc: setting cert") +441 self.cert = val +442 else: +443 log.debug("bugzillarc: unknown key=%s", key) +
Parameters
+ +-
+
- configpath: Optional bugzillarc path to read, instead of +the default list. +
This function is called automatically from Bugzilla connect(), which +is called at __init__ if a URL is passed. Calling it manually is +just for passing in a non-standard configpath.
+ +The locations for the bugzillarc file are preferred in this order:
+ +~/.config/python-bugzilla/bugzillarc
+~/.bugzillarc
+/etc/bugzillarc
+It has content like: + [bugzilla.yoursite.com] + user = username + password = password +Or + [bugzilla.yoursite.com] + api_key = key
+ +The file can have multiple sections for different bugzilla instances. +A 'url' field in the [DEFAULT] section can be used to set a default +URL for the bugzilla command line tool.
+ +Be sure to set appropriate permissions on bugzillarc if you choose to +store your password in it!
+ +-
+
- overwrite: If True, bugzillarc will clobber any already +set self.user/password/api_key/cert value. +
+
+
+
+
+
+
+
+
+
+
+ def
+ connect(self, url=None):
+
+
+
+
+
+ 486 def connect(self, url=None): +487 """ +488 Connect to the bugzilla instance with the given url. This is +489 called by __init__ if a URL is passed. Or it can be called manually +490 at any time with a passed URL. +491 +492 This will also read any available config files (see readconfig()), +493 which may set 'user' and 'password', and others. +494 +495 If 'user' and 'password' are both set, we'll run login(). Otherwise +496 you'll have to login() yourself before some methods will work. +497 """ +498 if self._session: +499 self.disconnect() +500 +501 url = url or self.url +502 backendclass, newurl = self._get_backend_class(url) +503 if url != newurl: +504 log.debug("Converted url=%s to fixed url=%s", url, newurl) +505 self.url = newurl +506 log.debug("Connecting with URL %s", self.url) +507 +508 # we've changed URLs - reload config +509 self.readconfig(overwrite=False) +510 +511 # Detect if connecting to redhat bugzilla +512 self._init_class_from_url() +513 +514 self._session = _BugzillaSession(self.url, self.user_agent, +515 sslverify=self._sslverify, +516 cert=self.cert, +517 tokencache=self._tokencache, +518 api_key=self.api_key, +519 is_redhat_bugzilla=self._is_redhat_bugzilla, +520 requests_session=self._user_requests_session) +521 self._backend = backendclass(self.url, self._session) +522 +523 if (self.user and self.password): +524 log.info("user and password present - doing login()") +525 self.login() +526 +527 if self.api_key: +528 log.debug("using API key") +529 +530 version = self._backend.bugzilla_version()["version"] +531 log.debug("Bugzilla version string: %s", version) +532 self._set_bz_version(version) +
Connect to the bugzilla instance with the given url. This is +called by __init__ if a URL is passed. Or it can be called manually +at any time with a passed URL.
+ +This will also read any available config files (see readconfig()), +which may set 'user' and 'password', and others.
+ +If 'user' and 'password' are both set, we'll run login(). Otherwise +you'll have to login() yourself before some methods will work.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ is_xmlrpc(self):
+
+
+
+
+
+ 546 def is_xmlrpc(self): +547 """ +548 :returns: True if using the XMLRPC API +549 """ +550 return self._backend.is_xmlrpc() +
:returns: True if using the XMLRPC API
+
+
+
+
+
+
+
+
+
+
+
+ def
+ is_rest(self):
+
+
+
+
+
+ 552 def is_rest(self): +553 """ +554 :returns: True if using the REST API +555 """ +556 return self._backend.is_rest() +
:returns: True if using the REST API
+
+
+
+
+
+
+
+
+
+
+
+ def
+ get_requests_session(self):
+
+
+
+
+
+ 558 def get_requests_session(self): +559 """ +560 Give API users access to the Requests.session object we use for +561 talking to the remote bugzilla instance. +562 +563 :returns: The Requests.session object backing the open connection. +564 """ +565 return self._session.get_requests_session() +
Give API users access to the Requests.session object we use for +talking to the remote bugzilla instance.
+ +:returns: The Requests.session object backing the open connection.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ disconnect(self):
+
+
+
+
+
+ 567 def disconnect(self): +568 """ +569 Disconnect from the given bugzilla instance. +570 """ +571 self._backend = None +572 self._session = None +573 self._cache = _BugzillaAPICache() +
Disconnect from the given bugzilla instance.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ login(self, user=None, password=None, restrict_login=None):
+
+
+
+
+
+ 575 def login(self, user=None, password=None, restrict_login=None): +576 """ +577 Attempt to log in using the given username and password. Subsequent +578 method calls will use this username and password. Returns False if +579 login fails, otherwise returns some kind of login info - typically +580 either a numeric userid, or a dict of user info. +581 +582 If user is not set, the value of Bugzilla.user will be used. If *that* +583 is not set, ValueError will be raised. If login fails, BugzillaError +584 will be raised. +585 +586 The login session can be restricted to current user IP address +587 with restrict_login argument. (Bugzilla 4.4+) +588 +589 This method will be called implicitly at the end of connect() if user +590 and password are both set. So under most circumstances you won't need +591 to call this yourself. +592 """ +593 if self.api_key: +594 raise ValueError("cannot login when using an API key") +595 +596 if user: +597 self.user = user +598 if password: +599 self.password = password +600 +601 if not self.user: +602 raise ValueError("missing username") +603 if not self.password: +604 raise ValueError("missing password") +605 +606 payload = {"login": self.user} +607 if restrict_login: +608 payload['restrict_login'] = True +609 log.debug("logging in with options %s", str(payload)) +610 payload['password'] = self.password +611 +612 try: +613 ret = self._backend.user_login(payload) +614 self.password = '' +615 log.info("login succeeded for user=%s", self.user) +616 if "token" in ret: +617 self._tokencache.set_value(self.url, ret["token"]) +618 return ret +619 except Exception as e: +620 log.debug("Login exception: %s", str(e), exc_info=True) +621 raise BugzillaError("Login failed: %s" % +622 BugzillaError.get_bugzilla_error_string(e)) from None +
Attempt to log in using the given username and password. Subsequent +method calls will use this username and password. Returns False if +login fails, otherwise returns some kind of login info - typically +either a numeric userid, or a dict of user info.
+ +If user is not set, the value of Bugzilla.user will be used. If that +is not set, ValueError will be raised. If login fails, BugzillaError +will be raised.
+ +The login session can be restricted to current user IP address +with restrict_login argument. (Bugzilla 4.4+)
+ +This method will be called implicitly at the end of connect() if user +and password are both set. So under most circumstances you won't need +to call this yourself.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ interactive_save_api_key(self):
+
+
+
+
+
+ 624 def interactive_save_api_key(self): +625 """ +626 Helper method to interactively ask for an API key, verify it +627 is valid, and save it to a bugzillarc file referenced via +628 self.configpaths +629 """ +630 sys.stdout.write('API Key: ') +631 sys.stdout.flush() +632 api_key = sys.stdin.readline().strip() +633 +634 self.disconnect() +635 self.api_key = api_key +636 +637 log.info('Checking API key... ') +638 self.connect() +639 +640 if not self.logged_in: # pragma: no cover +641 raise BugzillaError("Login with API_KEY failed") +642 log.info('API Key accepted') +643 +644 wrote_filename = self._rcfile.save_api_key(self.url, self.api_key) +645 log.info("API key written to filename=%s", wrote_filename) +646 +647 msg = "Login successful." +648 if wrote_filename: +649 msg += " API key written to %s" % wrote_filename +650 print(msg) +
Helper method to interactively ask for an API key, verify it +is valid, and save it to a bugzillarc file referenced via +self.configpaths
+
+
+
+
+
+
+
+
+
+
+
+ def
+ interactive_login(self, user=None, password=None, force=False, restrict_login=None):
+
+
+
+
+
+ 652 def interactive_login(self, user=None, password=None, force=False, +653 restrict_login=None): +654 """ +655 Helper method to handle login for this bugzilla instance. +656 +657 :param user: bugzilla username. If not specified, prompt for it. +658 :param password: bugzilla password. If not specified, prompt for it. +659 :param force: Unused +660 :param restrict_login: restricts session to IP address +661 """ +662 ignore = force +663 log.debug('Calling interactive_login') +664 +665 if not user: +666 sys.stdout.write('Bugzilla Username: ') +667 sys.stdout.flush() +668 user = sys.stdin.readline().strip() +669 if not password: +670 password = getpass.getpass('Bugzilla Password: ') +671 +672 log.info('Logging in... ') +673 out = self.login(user, password, restrict_login) +674 msg = "Login successful." +675 if "token" not in out: +676 msg += " However no token was returned." +677 else: +678 if not self.tokenfile: +679 msg += " Token not saved to disk." +680 else: +681 msg += " Token cache saved to %s" % self.tokenfile +682 if self._get_version() >= 5.0: +683 msg += "\nToken usage is deprecated. " +684 msg += "Consider using bugzilla API keys instead. " +685 msg += "See `man bugzilla` for more details." +686 print(msg) +
Helper method to handle login for this bugzilla instance.
+ +Parameters
+ +-
+
- user: bugzilla username. If not specified, prompt for it. +
- password: bugzilla password. If not specified, prompt for it. +
- force: Unused +
- restrict_login: restricts session to IP address +
+
+
+
+
+
+
+
+
+
+
+ def
+ logout(self):
+
+
+
+
+
+ 688 def logout(self): +689 """ +690 Log out of bugzilla. Drops server connection and user info, and +691 destroys authentication cache +692 """ +693 self._backend.user_logout() +694 self.disconnect() +695 self.user = '' +696 self.password = '' +
Log out of bugzilla. Drops server connection and user info, and +destroys authentication cache
+
+
+
+
+
+
+
+
+
+
+ logged_in
+
+
+
+
+
+ 698 @property +699 def logged_in(self): +700 """ +701 This is True if this instance is logged in else False. +702 +703 We test if this session is authenticated by calling the User.get() +704 XMLRPC method with ids set. Logged-out users cannot pass the 'ids' +705 parameter and will result in a 505 error. If we tried to login with a +706 token, but the token was incorrect or expired, the server returns a +707 32000 error. +708 +709 For Bugzilla 5 and later, a new method, User.valid_login is available +710 to test the validity of the token. However, this will require that the +711 username be cached along with the token in order to work effectively in +712 all scenarios and is not currently used. For more information, refer to +713 the following url. +714 +715 http://bugzilla.readthedocs.org/en/latest/api/core/v1/user.html#valid-login +716 """ +717 try: +718 self._backend.user_get({"ids": [1]}) +719 return True +720 except Exception as e: +721 code = BugzillaError.get_bugzilla_error_code(e) +722 if code in [505, 32000]: +723 return False +724 raise e +
This is True if this instance is logged in else False.
+ +We test if this session is authenticated by calling the User.get() +XMLRPC method with ids set. Logged-out users cannot pass the 'ids' +parameter and will result in a 505 error. If we tried to login with a +token, but the token was incorrect or expired, the server returns a +32000 error.
+ +For Bugzilla 5 and later, a new method, User.valid_login is available +to test the validity of the token. However, this will require that the +username be cached along with the token in order to work effectively in +all scenarios and is not currently used. For more information, refer to +the following url.
+ +http://bugzilla.readthedocs.org/en/latest/api/core/v1/user.html#valid-login
+
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getbugfields(self, force_refresh=False, names=None):
+
+
+
+
+
+ 731 def getbugfields(self, force_refresh=False, names=None): +732 """ +733 Calls getBugFields, which returns a list of fields in each bug +734 for this bugzilla instance. This can be used to set the list of attrs +735 on the Bug object. +736 +737 :param force_refresh: If True, overwrite the bugfield cache +738 with these newly checked values. +739 :param names: Only check for the passed bug field names +740 """ +741 def _fieldnames(): +742 data = {"include_fields": ["name"]} +743 if names: +744 data["names"] = names +745 r = self._backend.bug_fields(data) +746 return [f['name'] for f in r['fields']] +747 +748 if force_refresh or not self._cache.bugfields: +749 log.debug("Refreshing bugfields") +750 self._cache.bugfields = _fieldnames() +751 self._cache.bugfields.sort() +752 log.debug("bugfields = %s", self._cache.bugfields) +753 +754 return self._cache.bugfields +
Calls getBugFields, which returns a list of fields in each bug +for this bugzilla instance. This can be used to set the list of attrs +on the Bug object.
+ +Parameters
+ +-
+
- force_refresh: If True, overwrite the bugfield cache +with these newly checked values. +
- names: Only check for the passed bug field names +
+
+
+
+
+
+
+
+
+
+
+ def
+ product_get( self, ids=None, names=None, include_fields=None, exclude_fields=None, ptype=None):
+
+
+
+
+
+ 763 def product_get(self, ids=None, names=None, +764 include_fields=None, exclude_fields=None, +765 ptype=None): +766 """ +767 Raw wrapper around Product.get +768 https://bugzilla.readthedocs.io/en/latest/api/core/v1/product.html#get-product +769 +770 This does not perform any caching like other product API calls. +771 If ids, names, or ptype is not specified, we default to +772 ptype=accessible for historical reasons +773 +774 @ids: List of product IDs to lookup +775 @names: List of product names to lookup +776 @ptype: Either 'accessible', 'selectable', or 'enterable'. If +777 specified, we return data for all those +778 @include_fields: Only include these fields in the output +779 @exclude_fields: Do not include these fields in the output +780 """ +781 if ids is None and names is None and ptype is None: +782 ptype = "accessible" +783 +784 if ptype: +785 raw = None +786 if ptype == "accessible": +787 raw = self._backend.product_get_accessible() +788 elif ptype == "enterable": +789 raw = self._backend.product_get_enterable() +790 elif ptype == "selectable": +791 raw = self._backend.product_get_selectable() +792 +793 if raw is None: +794 raise RuntimeError("Unknown ptype=%s" % ptype) +795 ids = raw['ids'] +796 log.debug("For ptype=%s found ids=%s", ptype, ids) +797 +798 kwargs = {} +799 if ids: +800 kwargs["ids"] = listify(ids) +801 if names: +802 kwargs["names"] = listify(names) +803 if include_fields: +804 kwargs["include_fields"] = include_fields +805 if exclude_fields: +806 kwargs["exclude_fields"] = exclude_fields +807 +808 ret = self._backend.product_get(kwargs) +809 return ret['products'] +
Raw wrapper around Product.get +https://bugzilla.readthedocs.io/en/latest/api/core/v1/product.html#get-product
+ +This does not perform any caching like other product API calls. +If ids, names, or ptype is not specified, we default to +ptype=accessible for historical reasons
+ +@ids: List of product IDs to lookup +@names: List of product names to lookup +@ptype: Either 'accessible', 'selectable', or 'enterable'. If + specified, we return data for all those +@include_fields: Only include these fields in the output +@exclude_fields: Do not include these fields in the output
+
+
+
+
+
+
+
+
+
+
+
+ def
+ refresh_products(self, **kwargs):
+
+
+
+
+
+ 811 def refresh_products(self, **kwargs): +812 """ +813 Refresh a product's cached info. Basically calls product_get +814 with the passed arguments, and tries to intelligently update +815 our product cache. +816 +817 For example, if we already have cached info for product=foo, +818 and you pass in names=["bar", "baz"], the new cache will have +819 info for products foo, bar, baz. Individual product fields are +820 also updated. +821 """ +822 for product in self.product_get(**kwargs): +823 updated = False +824 for current in self._cache.products[:]: +825 if (current.get("id", -1) != product.get("id", -2) and +826 current.get("name", -1) != product.get("name", -2)): +827 continue +828 +829 _nested_update(current, product) +830 updated = True +831 break +832 if not updated: +833 self._cache.products.append(product) +
Refresh a product's cached info. Basically calls product_get +with the passed arguments, and tries to intelligently update +our product cache.
+ +For example, if we already have cached info for product=foo, +and you pass in names=["bar", "baz"], the new cache will have +info for products foo, bar, baz. Individual product fields are +also updated.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getproducts(self, force_refresh=False, **kwargs):
+
+
+
+
+
+ 835 def getproducts(self, force_refresh=False, **kwargs): +836 """ +837 Query all products and return the raw dict info. Takes all the +838 same arguments as product_get. +839 +840 On first invocation this will contact bugzilla and internally +841 cache the results. Subsequent getproducts calls or accesses to +842 self.products will return this cached data only. +843 +844 :param force_refresh: force refreshing via refresh_products() +845 """ +846 if force_refresh or not self._cache.products: +847 self.refresh_products(**kwargs) +848 return self._cache.products +
Query all products and return the raw dict info. Takes all the +same arguments as product_get.
+ +On first invocation this will contact bugzilla and internally +cache the results. Subsequent getproducts calls or accesses to +self.products will return this cached data only.
+ +Parameters
+ +-
+
- force_refresh: force refreshing via refresh_products() +
+
+
+
+
+
+
+
+
+
+ products
+
+
+
+
+
+ 851 fget=lambda self: self.getproducts(),
+Helper for accessing the products cache. If nothing has been cached yet, this calls getproducts()
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getcomponentsdetails(self, product, force_refresh=False):
+
+
+
+
+
+ 871 def getcomponentsdetails(self, product, force_refresh=False): +872 """ +873 Wrapper around Product.get(include_fields=["components"]), +874 returning only the "components" data for the requested product, +875 slightly reworked to a dict mapping of components.name: components, +876 for historical reasons. +877 +878 This uses the product cache, but will update it if the product +879 isn't found or "components" isn't cached for the product. +880 +881 In cases like bugzilla.redhat.com where there are tons of +882 components for some products, this API will time out. You +883 should use product_get instead. +884 """ +885 proddict = self._lookup_product_in_cache(product) +886 +887 if (force_refresh or not proddict or "components" not in proddict): +888 self.refresh_products(names=[product], +889 include_fields=["name", "id", "components"]) +890 proddict = self._lookup_product_in_cache(product) +891 +892 ret = {} +893 for compdict in proddict["components"]: +894 ret[compdict["name"]] = compdict +895 return ret +
Wrapper around Product.get(include_fields=["components"]), +returning only the "components" data for the requested product, +slightly reworked to a dict mapping of components.name: components, +for historical reasons.
+ +This uses the product cache, but will update it if the product +isn't found or "components" isn't cached for the product.
+ +In cases like bugzilla.redhat.com where there are tons of +components for some products, this API will time out. You +should use product_get instead.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getcomponentdetails(self, product, component, force_refresh=False):
+
+
+
+
+
+ 897 def getcomponentdetails(self, product, component, force_refresh=False): +898 """ +899 Helper for accessing a single component's info. This is a wrapper +900 around getcomponentsdetails, see that for explanation +901 """ +902 d = self.getcomponentsdetails(product, force_refresh) +903 return d[component] +
Helper for accessing a single component's info. This is a wrapper +around getcomponentsdetails, see that for explanation
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getcomponents(self, product, force_refresh=False):
+
+
+
+
+
+ 905 def getcomponents(self, product, force_refresh=False): +906 """ +907 Return a list of component names for the passed product. +908 +909 On first invocation the value is cached, and subsequent calls +910 will return the cached data. +911 +912 :param force_refresh: Force refreshing the cache, and return +913 the new data +914 """ +915 proddict = self._lookup_product_in_cache(product) +916 product_id = proddict.get("id", None) +917 +918 if (force_refresh or product_id is None or +919 "components" not in proddict): +920 self.refresh_products( +921 names=[product], +922 include_fields=["name", "id", "components.name"]) +923 proddict = self._lookup_product_in_cache(product) +924 if "id" not in proddict: +925 raise BugzillaError("Product '%s' not found" % product) +926 product_id = proddict["id"] +927 +928 if product_id not in self._cache.component_names: +929 names = [] +930 for comp in proddict.get("components", []): +931 name = comp.get("name") +932 if name: +933 names.append(name) +934 self._cache.component_names[product_id] = names +935 +936 return self._cache.component_names[product_id] +
Return a list of component names for the passed product.
+ +On first invocation the value is cached, and subsequent calls +will return the cached data.
+ +Parameters
+ +-
+
- force_refresh: Force refreshing the cache, and return +the new data +
+
+
+
+
+
+
+
+
+
+
+ def
+ addcomponent(self, data):
+
+
+
+
+
+ 965 def addcomponent(self, data): +966 """ +967 A method to create a component in Bugzilla. Takes a dict, with the +968 following elements: +969 +970 product: The product to create the component in +971 component: The name of the component to create +972 description: A one sentence summary of the component +973 default_assignee: The bugzilla login (email address) of the initial +974 owner of the component +975 default_qa_contact (optional): The bugzilla login of the +976 initial QA contact +977 default_cc: (optional) The initial list of users to be CC'ed on +978 new bugs for the component. +979 is_active: (optional) If False, the component is hidden from +980 the component list when filing new bugs. +981 """ +982 data = data.copy() +983 self._component_data_convert(data) +984 return self._backend.component_create(data) +
A method to create a component in Bugzilla. Takes a dict, with the +following elements:
+ +product: The product to create the component in +component: The name of the component to create +description: A one sentence summary of the component +default_assignee: The bugzilla login (email address) of the initial + owner of the component +default_qa_contact (optional): The bugzilla login of the + initial QA contact +default_cc: (optional) The initial list of users to be CC'ed on + new bugs for the component. +is_active: (optional) If False, the component is hidden from + the component list when filing new bugs.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ editcomponent(self, data):
+
+
+
+
+
+ 986 def editcomponent(self, data): +987 """ +988 A method to edit a component in Bugzilla. Takes a dict, with +989 mandatory elements of product. component, and initialowner. +990 All other elements are optional and use the same names as the +991 addcomponent() method. +992 """ +993 data = data.copy() +994 self._component_data_convert(data, update=True) +995 return self._backend.component_update(data) +
A method to edit a component in Bugzilla. Takes a dict, with +mandatory elements of product. component, and initialowner. +All other elements are optional and use the same names as the +addcomponent() method.
+
+
+
+
+
+
+
+
+
+
+ bug_autorefresh
+
+
+
+
+
+ 1029 def _get_bug_autorefresh(self): +1030 """ +1031 This value is passed to Bug.autorefresh for all fetched bugs. +1032 If True, and an uncached attribute is requested from a Bug, +1033 the Bug will update its contents and try again. +1034 """ +1035 return self._bug_autorefresh +
This value is passed to Bug.autorefresh for all fetched bugs. +If True, and an uncached attribute is requested from a Bug, + the Bug will update its contents and try again.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getbug( self, objid, include_fields=None, exclude_fields=None, extra_fields=None):
+
+
+
+
+
+ 1132 def getbug(self, objid, +1133 include_fields=None, exclude_fields=None, extra_fields=None): +1134 """ +1135 Return a Bug object with the full complement of bug data +1136 already loaded. +1137 """ +1138 data = self._getbug(objid, +1139 include_fields=include_fields, exclude_fields=exclude_fields, +1140 extra_fields=extra_fields) +1141 return Bug(self, dict=data, autorefresh=self.bug_autorefresh) +
Return a Bug object with the full complement of bug data +already loaded.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getbugs( self, idlist, include_fields=None, exclude_fields=None, extra_fields=None, permissive=True):
+
+
+
+
+
+ 1143 def getbugs(self, idlist, +1144 include_fields=None, exclude_fields=None, extra_fields=None, +1145 permissive=True): +1146 """ +1147 Return a list of Bug objects with the full complement of bug data +1148 already loaded. If there's a problem getting the data for a given id, +1149 the corresponding item in the returned list will be None. +1150 """ +1151 data = self._getbugs(idlist, include_fields=include_fields, +1152 exclude_fields=exclude_fields, extra_fields=extra_fields, +1153 permissive=permissive) +1154 return [(b and Bug(self, dict=b, +1155 autorefresh=self.bug_autorefresh)) or None +1156 for b in data] +
Return a list of Bug objects with the full complement of bug data +already loaded. If there's a problem getting the data for a given id, +the corresponding item in the returned list will be None.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ get_comments(self, idlist):
+
+
+
+
+
+ 1158 def get_comments(self, idlist): +1159 """ +1160 Returns a dictionary of bugs and comments. The comments key will +1161 be empty. See bugzilla docs for details +1162 """ +1163 return self._backend.bug_comments(idlist, {}) +
Returns a dictionary of bugs and comments. The comments key will +be empty. See bugzilla docs for details
+
+
+
+
+
+
+
+
+
+
+
+ def
+ build_query( self, product=None, component=None, version=None, long_desc=None, bug_id=None, short_desc=None, cc=None, assigned_to=None, reporter=None, qa_contact=None, status=None, blocked=None, dependson=None, keywords=None, keywords_type=None, url=None, url_type=None, status_whiteboard=None, status_whiteboard_type=None, fixed_in=None, fixed_in_type=None, flag=None, alias=None, qa_whiteboard=None, devel_whiteboard=None, bug_severity=None, priority=None, target_release=None, target_milestone=None, emailtype=None, include_fields=None, quicksearch=None, savedsearch=None, savedsearch_sharer_id=None, sub_component=None, tags=None, exclude_fields=None, extra_fields=None, limit=None, resolution=None):
+
+
+
+
+
+ 1170 def build_query(self, +1171 product=None, +1172 component=None, +1173 version=None, +1174 long_desc=None, +1175 bug_id=None, +1176 short_desc=None, +1177 cc=None, +1178 assigned_to=None, +1179 reporter=None, +1180 qa_contact=None, +1181 status=None, +1182 blocked=None, +1183 dependson=None, +1184 keywords=None, +1185 keywords_type=None, +1186 url=None, +1187 url_type=None, +1188 status_whiteboard=None, +1189 status_whiteboard_type=None, +1190 fixed_in=None, +1191 fixed_in_type=None, +1192 flag=None, +1193 alias=None, +1194 qa_whiteboard=None, +1195 devel_whiteboard=None, +1196 bug_severity=None, +1197 priority=None, +1198 target_release=None, +1199 target_milestone=None, +1200 emailtype=None, +1201 include_fields=None, +1202 quicksearch=None, +1203 savedsearch=None, +1204 savedsearch_sharer_id=None, +1205 sub_component=None, +1206 tags=None, +1207 exclude_fields=None, +1208 extra_fields=None, +1209 limit=None, +1210 resolution=None): +1211 """ +1212 Build a query string from passed arguments. Will handle +1213 query parameter differences between various bugzilla versions. +1214 +1215 Most of the parameters should be self-explanatory. However, +1216 if you want to perform a complex query, and easy way is to +1217 create it with the bugzilla web UI, copy the entire URL it +1218 generates, and pass it to the static method +1219 +1220 Bugzilla.url_to_query +1221 +1222 Then pass the output to Bugzilla.query() +1223 +1224 For details about the specific argument formats, see the bugzilla docs: +1225 https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#search-bugs +1226 """ +1227 query = { +1228 "alias": alias, +1229 "product": listify(product), +1230 "component": listify(component), +1231 "version": version, +1232 "id": bug_id, +1233 "short_desc": short_desc, +1234 "bug_status": status, +1235 "bug_severity": bug_severity, +1236 "priority": priority, +1237 "target_release": target_release, +1238 "target_milestone": target_milestone, +1239 "tag": listify(tags), +1240 "quicksearch": quicksearch, +1241 "savedsearch": savedsearch, +1242 "sharer_id": savedsearch_sharer_id, +1243 "limit": limit, +1244 "resolution": resolution, +1245 +1246 # RH extensions... don't add any more. See comment below +1247 "sub_components": listify(sub_component), +1248 } +1249 +1250 def add_bool(bzkey, value, bool_id, booltype=None): +1251 value = listify(value) +1252 if value is None: +1253 return bool_id +1254 +1255 query["query_format"] = "advanced" +1256 for boolval in value: +1257 def make_bool_str(prefix): +1258 # pylint: disable=cell-var-from-loop +1259 return "%s%i-0-0" % (prefix, bool_id) +1260 +1261 query[make_bool_str("field")] = bzkey +1262 query[make_bool_str("value")] = boolval +1263 query[make_bool_str("type")] = booltype or "substring" +1264 +1265 bool_id += 1 +1266 return bool_id +1267 +1268 # RH extensions that we have to maintain here for back compat, +1269 # but all future custom fields should be specified via +1270 # cli --field option, or via extending the query dict() manually. +1271 # No more supporting custom fields in this API +1272 bool_id = 0 +1273 bool_id = add_bool("keywords", keywords, bool_id, keywords_type) +1274 bool_id = add_bool("blocked", blocked, bool_id) +1275 bool_id = add_bool("dependson", dependson, bool_id) +1276 bool_id = add_bool("bug_file_loc", url, bool_id, url_type) +1277 bool_id = add_bool("cf_fixed_in", fixed_in, bool_id, fixed_in_type) +1278 bool_id = add_bool("flagtypes.name", flag, bool_id) +1279 bool_id = add_bool("status_whiteboard", +1280 status_whiteboard, bool_id, status_whiteboard_type) +1281 bool_id = add_bool("cf_qa_whiteboard", qa_whiteboard, bool_id) +1282 bool_id = add_bool("cf_devel_whiteboard", devel_whiteboard, bool_id) +1283 +1284 def add_email(key, value, count): +1285 if value is None: +1286 return count +1287 if not emailtype: +1288 query[key] = value +1289 return count +1290 +1291 query["query_format"] = "advanced" +1292 query['email%i' % count] = value +1293 query['email%s%i' % (key, count)] = True +1294 query['emailtype%i' % count] = emailtype +1295 return count + 1 +1296 +1297 email_count = 1 +1298 email_count = add_email("cc", cc, email_count) +1299 email_count = add_email("assigned_to", assigned_to, email_count) +1300 email_count = add_email("reporter", reporter, email_count) +1301 email_count = add_email("qa_contact", qa_contact, email_count) +1302 +1303 if long_desc is not None: +1304 query["query_format"] = "advanced" +1305 query["longdesc"] = long_desc +1306 query["longdesc_type"] = "allwordssubstr" +1307 +1308 # 'include_fields' only available for Bugzilla4+ +1309 # 'extra_fields' is an RHBZ extension +1310 query.update(self._process_include_fields( +1311 include_fields, exclude_fields, extra_fields)) +1312 +1313 # Strip out None elements in the dict +1314 for k, v in query.copy().items(): +1315 if v is None: +1316 del query[k] +1317 +1318 self.pre_translation(query) +1319 return query +
Build a query string from passed arguments. Will handle +query parameter differences between various bugzilla versions.
+ +Most of the parameters should be self-explanatory. However, +if you want to perform a complex query, and easy way is to +create it with the bugzilla web UI, copy the entire URL it +generates, and pass it to the static method
+ + + +Then pass the output to Bugzilla.query()
+ +For details about the specific argument formats, see the bugzilla docs: +https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#search-bugs
+
+
+
+
+
+
+
+
+
+
+
+ def
+ query_return_extra(self, query):
+
+
+
+
+
+ 1322 def query_return_extra(self, query): +1323 """ +1324 Same as `query()`, but the return value is altered to be +1325 (buglist, values), where `values` is raw dictionary output from +1326 the API call, excluding the bug content. For example this may +1327 include a `limit` value if the bugzilla instance puts an implied +1328 limit on returned result numbers. +1329 """ +1330 try: +1331 r = self._backend.bug_search(query) +1332 log.debug("bug_search returned:\n%s", str(r)) +1333 except Exception as e: +1334 # Try to give a hint in the error message if url_to_query +1335 # isn't supported by this bugzilla instance +1336 if ("query_format" not in str(e) or +1337 not BugzillaError.get_bugzilla_error_code(e) or +1338 self._get_version() >= 5.0): +1339 raise +1340 raise BugzillaError("%s\nYour bugzilla instance does not " +1341 "appear to support API queries derived from bugzilla " +1342 "web URL queries." % e) from None +1343 +1344 rawbugs = r.pop("bugs") +1345 log.debug("Query returned %s bugs", len(rawbugs)) +1346 bugs = [Bug(self, dict=b, +1347 autorefresh=self.bug_autorefresh) for b in rawbugs] +1348 +1349 return bugs, r +
Same as query(), but the return value is altered to be
+(buglist, values), where values is raw dictionary output from
+the API call, excluding the bug content. For example this may
+include a limit value if the bugzilla instance puts an implied
+limit on returned result numbers.
+
+
+
+
+
+
+
+
+
+
+ def
+ query(self, query):
+
+
+
+
+
+ 1351 def query(self, query): +1352 """ +1353 Pass search terms to bugzilla and and return a list of matching +1354 Bug objects. +1355 +1356 See `build_query` for more details about constructing the +1357 `query` dict parameter. +1358 """ +1359 bugs, dummy = self.query_return_extra(query) +1360 return bugs +
Pass search terms to bugzilla and and return a list of matching +Bug objects.
+ +See build_query for more details about constructing the
+query dict parameter.
+
+
+
+
+
+
+
+
+
+
+ def
+ pre_translation(self, query):
+
+
+
+
+
+ 1362 def pre_translation(self, query): +1363 """ +1364 In order to keep the API the same, Bugzilla4 needs to process the +1365 query and the result. This also applies to the refresh() function +1366 """ +1367 if self._is_redhat_bugzilla: +1368 _RHBugzillaConverters.pre_translation(query) +1369 query.update(self._process_include_fields( +1370 query.get("include_fields", []), None, None)) +
In order to keep the API the same, Bugzilla4 needs to process the +query and the result. This also applies to the refresh() function
+
+
+
+
+
+
+
+
+
+
+
+ def
+ post_translation(self, query, bug):
+
+
+
+
+
+ 1372 def post_translation(self, query, bug): +1373 """ +1374 In order to keep the API the same, Bugzilla4 needs to process the +1375 query and the result. This also applies to the refresh() function +1376 """ +1377 if self._is_redhat_bugzilla: +1378 _RHBugzillaConverters.post_translation(query, bug) +
In order to keep the API the same, Bugzilla4 needs to process the +query and the result. This also applies to the refresh() function
+
+
+
+
+
+
+
+
+
+
+
+ def
+ bugs_history_raw(self, bug_ids):
+
+
+
+
+
+ 1380 def bugs_history_raw(self, bug_ids): +1381 """ +1382 Experimental. Gets the history of changes for +1383 particular bugs in the database. +1384 """ +1385 return self._backend.bug_history(bug_ids, {}) +
Experimental. Gets the history of changes for +particular bugs in the database.
+
+
+
+
+
+
+
+
+
+
+
+
+ def
+ update_bugs(self, ids, updates):
+
+
+
+
+
+ 1394 def update_bugs(self, ids, updates): +1395 """ +1396 A thin wrapper around bugzilla Bug.update(). Used to update all +1397 values of an existing bug report, as well as add comments. +1398 +1399 The dictionary passed to this function should be generated with +1400 build_update(), otherwise we cannot guarantee back compatibility. +1401 """ +1402 tmp = updates.copy() +1403 return self._backend.bug_update(listify(ids), tmp) +
A thin wrapper around bugzilla Bug.update(). Used to update all +values of an existing bug report, as well as add comments.
+ +The dictionary passed to this function should be generated with +build_update(), otherwise we cannot guarantee back compatibility.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ update_flags(self, idlist, flags):
+
+
+
+
+
+ 1421 def update_flags(self, idlist, flags): +1422 """ +1423 A thin back compat wrapper around build_update(flags=X) +1424 """ +1425 return self.update_bugs(idlist, self.build_update(flags=flags)) +
A thin back compat wrapper around build_update(flags=X)
+
+
+
+
+
+
+
+
+
+
+
+ def
+ build_update( self, alias=None, assigned_to=None, blocks_add=None, blocks_remove=None, blocks_set=None, depends_on_add=None, depends_on_remove=None, depends_on_set=None, cc_add=None, cc_remove=None, is_cc_accessible=None, comment=None, comment_private=None, component=None, deadline=None, dupe_of=None, estimated_time=None, groups_add=None, groups_remove=None, keywords_add=None, keywords_remove=None, keywords_set=None, op_sys=None, platform=None, priority=None, product=None, qa_contact=None, is_creator_accessible=None, remaining_time=None, reset_assigned_to=None, reset_qa_contact=None, resolution=None, see_also_add=None, see_also_remove=None, severity=None, status=None, summary=None, target_milestone=None, target_release=None, url=None, version=None, whiteboard=None, work_time=None, fixed_in=None, qa_whiteboard=None, devel_whiteboard=None, internal_whiteboard=None, sub_component=None, flags=None, comment_tags=None, minor_update=None):
+
+
+
+
+
+ 1428 def build_update(self, +1429 alias=None, +1430 assigned_to=None, +1431 blocks_add=None, +1432 blocks_remove=None, +1433 blocks_set=None, +1434 depends_on_add=None, +1435 depends_on_remove=None, +1436 depends_on_set=None, +1437 cc_add=None, +1438 cc_remove=None, +1439 is_cc_accessible=None, +1440 comment=None, +1441 comment_private=None, +1442 component=None, +1443 deadline=None, +1444 dupe_of=None, +1445 estimated_time=None, +1446 groups_add=None, +1447 groups_remove=None, +1448 keywords_add=None, +1449 keywords_remove=None, +1450 keywords_set=None, +1451 op_sys=None, +1452 platform=None, +1453 priority=None, +1454 product=None, +1455 qa_contact=None, +1456 is_creator_accessible=None, +1457 remaining_time=None, +1458 reset_assigned_to=None, +1459 reset_qa_contact=None, +1460 resolution=None, +1461 see_also_add=None, +1462 see_also_remove=None, +1463 severity=None, +1464 status=None, +1465 summary=None, +1466 target_milestone=None, +1467 target_release=None, +1468 url=None, +1469 version=None, +1470 whiteboard=None, +1471 work_time=None, +1472 fixed_in=None, +1473 qa_whiteboard=None, +1474 devel_whiteboard=None, +1475 internal_whiteboard=None, +1476 sub_component=None, +1477 flags=None, +1478 comment_tags=None, +1479 minor_update=None): +1480 """ +1481 Returns a python dict() with properly formatted parameters to +1482 pass to update_bugs(). See bugzilla documentation for the format +1483 of the individual fields: +1484 +1485 https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#create-bug +1486 """ +1487 ret = {} +1488 rhbzret = {} +1489 +1490 # These are only supported for rhbugzilla +1491 # +1492 # This should not be extended any more. +1493 # If people want to handle custom fields, manually extend the +1494 # returned dictionary. +1495 rhbzargs = { +1496 "fixed_in": fixed_in, +1497 "devel_whiteboard": devel_whiteboard, +1498 "qa_whiteboard": qa_whiteboard, +1499 "internal_whiteboard": internal_whiteboard, +1500 "sub_component": sub_component, +1501 } +1502 if self._is_redhat_bugzilla: +1503 rhbzret = _RHBugzillaConverters.convert_build_update( +1504 component=component, **rhbzargs) +1505 else: +1506 for key, val in rhbzargs.items(): +1507 if val is not None: +1508 raise ValueError("bugzilla instance does not support " +1509 "updating '%s'" % key) +1510 +1511 def s(key, val, convert=None): +1512 if val is None: +1513 return +1514 if convert: +1515 val = convert(val) +1516 ret[key] = val +1517 +1518 def add_dict(key, add, remove, _set=None): +1519 if add is remove is _set is None: +1520 return +1521 +1522 newdict = {} +1523 if add is not None: +1524 newdict["add"] = listify(add) +1525 if remove is not None: +1526 newdict["remove"] = listify(remove) +1527 if _set is not None: +1528 newdict["set"] = listify(_set) +1529 ret[key] = newdict +1530 +1531 +1532 s("alias", alias) +1533 s("assigned_to", assigned_to) +1534 s("is_cc_accessible", is_cc_accessible, bool) +1535 s("component", component) +1536 s("deadline", deadline) +1537 s("dupe_of", dupe_of, int) +1538 s("estimated_time", estimated_time, int) +1539 s("op_sys", op_sys) +1540 s("platform", platform) +1541 s("priority", priority) +1542 s("product", product) +1543 s("qa_contact", qa_contact) +1544 s("is_creator_accessible", is_creator_accessible, bool) +1545 s("remaining_time", remaining_time, float) +1546 s("reset_assigned_to", reset_assigned_to, bool) +1547 s("reset_qa_contact", reset_qa_contact, bool) +1548 s("resolution", resolution) +1549 s("severity", severity) +1550 s("status", status) +1551 s("summary", summary) +1552 s("target_milestone", target_milestone) +1553 s("target_release", target_release) +1554 s("url", url) +1555 s("version", version) +1556 s("whiteboard", whiteboard) +1557 s("work_time", work_time, float) +1558 s("flags", flags) +1559 s("comment_tags", comment_tags, listify) +1560 s("minor_update", minor_update, bool) +1561 +1562 add_dict("blocks", blocks_add, blocks_remove, blocks_set) +1563 add_dict("depends_on", depends_on_add, depends_on_remove, depends_on_set) +1564 add_dict("cc", cc_add, cc_remove) +1565 add_dict("groups", groups_add, groups_remove) +1566 add_dict("keywords", keywords_add, keywords_remove, keywords_set) +1567 add_dict("see_also", see_also_add, see_also_remove) +1568 +1569 if comment is not None: +1570 ret["comment"] = {"comment": comment} +1571 if comment_private: +1572 ret["comment"]["is_private"] = comment_private +1573 +1574 ret.update(rhbzret) +1575 return ret +
Returns a python dict() with properly formatted parameters to +pass to update_bugs(). See bugzilla documentation for the format +of the individual fields:
+ +https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#create-bug
+
+
+
+
+
+
+
+
+
+
+
+ def
+ attachfile(self, idlist, attachfile, description, **kwargs):
+
+
+
+
+
+ 1582 def attachfile(self, idlist, attachfile, description, **kwargs): +1583 """ +1584 Attach a file to the given bug IDs. Returns the ID of the attachment +1585 or raises XMLRPC Fault if something goes wrong. +1586 +1587 attachfile may be a filename (which will be opened) or a file-like +1588 object, which must provide a 'read' method. If it's not one of these, +1589 this method will raise a TypeError. +1590 description is the short description of this attachment. +1591 +1592 Optional keyword args are as follows: +1593 file_name: this will be used as the filename for the attachment. +1594 REQUIRED if attachfile is a file-like object with no +1595 'name' attribute, otherwise the filename or .name +1596 attribute will be used. +1597 comment: An optional comment about this attachment. +1598 is_private: Set to True if the attachment should be marked private. +1599 is_patch: Set to True if the attachment is a patch. +1600 content_type: The mime-type of the attached file. Defaults to +1601 application/octet-stream if not set. NOTE that text +1602 files will *not* be viewable in bugzilla unless you +1603 remember to set this to text/plain. So remember that! +1604 +1605 Returns the list of attachment ids that were added. If only one +1606 attachment was added, we return the single int ID for back compat +1607 """ +1608 if isinstance(attachfile, str): +1609 f = open(attachfile, "rb") +1610 elif hasattr(attachfile, 'read'): +1611 f = attachfile +1612 else: +1613 raise TypeError("attachfile must be filename or file-like object") +1614 +1615 # Back compat +1616 if "contenttype" in kwargs: +1617 kwargs["content_type"] = kwargs.pop("contenttype") +1618 if "ispatch" in kwargs: +1619 kwargs["is_patch"] = kwargs.pop("ispatch") +1620 if "isprivate" in kwargs: +1621 kwargs["is_private"] = kwargs.pop("isprivate") +1622 if "filename" in kwargs: +1623 kwargs["file_name"] = kwargs.pop("filename") +1624 +1625 kwargs['summary'] = description +1626 +1627 data = f.read() +1628 if not isinstance(data, bytes): # pragma: no cover +1629 data = data.encode(locale.getpreferredencoding()) +1630 +1631 if 'file_name' not in kwargs and hasattr(f, "name"): +1632 kwargs['file_name'] = os.path.basename(f.name) +1633 if 'content_type' not in kwargs: +1634 ctype = None +1635 if kwargs['file_name']: +1636 ctype = mimetypes.guess_type( +1637 kwargs['file_name'], strict=False)[0] +1638 kwargs['content_type'] = ctype or 'application/octet-stream' +1639 +1640 ret = self._backend.bug_attachment_create( +1641 listify(idlist), data, kwargs) +1642 +1643 if "attachments" in ret: +1644 # Up to BZ 4.2 +1645 ret = [int(k) for k in ret["attachments"].keys()] +1646 elif "ids" in ret: +1647 # BZ 4.4+ +1648 ret = ret["ids"] +1649 +1650 if isinstance(ret, list) and len(ret) == 1: +1651 ret = ret[0] +1652 return ret +
Attach a file to the given bug IDs. Returns the ID of the attachment +or raises XMLRPC Fault if something goes wrong.
+ +attachfile may be a filename (which will be opened) or a file-like +object, which must provide a 'read' method. If it's not one of these, +this method will raise a TypeError. +description is the short description of this attachment.
+ +Optional keyword args are as follows: + file_name: this will be used as the filename for the attachment. + REQUIRED if attachfile is a file-like object with no + 'name' attribute, otherwise the filename or .name + attribute will be used. + comment: An optional comment about this attachment. + is_private: Set to True if the attachment should be marked private. + is_patch: Set to True if the attachment is a patch. + content_type: The mime-type of the attached file. Defaults to + application/octet-stream if not set. NOTE that text + files will not be viewable in bugzilla unless you + remember to set this to text/plain. So remember that!
+ +Returns the list of attachment ids that were added. If only one +attachment was added, we return the single int ID for back compat
+
+
+
+
+
+
+
+
+
+
+
+ def
+ openattachment_data(self, attachment_dict):
+
+
+
+
+
+ 1654 def openattachment_data(self, attachment_dict): +1655 """ +1656 Helper for turning passed API attachment dictionary into a +1657 filelike object +1658 """ +1659 ret = BytesIO() +1660 data = attachment_dict["data"] +1661 +1662 if hasattr(data, "data"): +1663 # This is for xmlrpc Binary +1664 content = data.data # pragma: no cover +1665 else: +1666 import base64 +1667 content = base64.b64decode(data) +1668 +1669 ret.write(content) +1670 ret.name = attachment_dict["file_name"] +1671 ret.seek(0) +1672 return ret +
Helper for turning passed API attachment dictionary into a +filelike object
+
+
+
+
+
+
+
+
+
+
+
+ def
+ openattachment(self, attachid):
+
+
+
+
+
+ 1674 def openattachment(self, attachid): +1675 """ +1676 Get the contents of the attachment with the given attachment ID. +1677 Returns a file-like object. +1678 """ +1679 attachments = self.get_attachments(None, attachid) +1680 data = attachments["attachments"][str(attachid)] +1681 return self.openattachment_data(data) +
Get the contents of the attachment with the given attachment ID. +Returns a file-like object.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ updateattachmentflags(self, bugid, attachid, flagname, **kwargs):
+
+
+
+
+
+ 1683 def updateattachmentflags(self, bugid, attachid, flagname, **kwargs): +1684 """ +1685 Updates a flag for the given attachment ID. +1686 Optional keyword args are: +1687 status: new status for the flag ('-', '+', '?', 'X') +1688 requestee: new requestee for the flag +1689 """ +1690 # Bug ID was used for the original custom redhat API, no longer +1691 # needed though +1692 ignore = bugid +1693 +1694 flags = {"name": flagname} +1695 flags.update(kwargs) +1696 attachment_ids = [int(attachid)] +1697 update = {'flags': [flags]} +1698 +1699 return self._backend.bug_attachment_update(attachment_ids, update) +
Updates a flag for the given attachment ID. +Optional keyword args are: + status: new status for the flag ('-', '+', '?', 'X') + requestee: new requestee for the flag
+
+
+
+
+
+
+
+
+
+
+
+ def
+ get_attachments(self, ids, attachment_ids, include_fields=None, exclude_fields=None):
+
+
+
+
+
+ 1701 def get_attachments(self, ids, attachment_ids, +1702 include_fields=None, exclude_fields=None): +1703 """ +1704 Wrapper for Bug.attachments. One of ids or attachment_ids is required +1705 +1706 :param ids: Get attachments for this bug ID +1707 :param attachment_ids: Specific attachment ID to get +1708 +1709 https://bugzilla.readthedocs.io/en/latest/api/core/v1/attachment.html#get-attachment +1710 """ +1711 params = {} +1712 if include_fields: +1713 params["include_fields"] = listify(include_fields) +1714 if exclude_fields: +1715 params["exclude_fields"] = listify(exclude_fields) +1716 +1717 if attachment_ids: +1718 return self._backend.bug_attachment_get(attachment_ids, params) +1719 return self._backend.bug_attachment_get_all(ids, params) +
Wrapper for Bug.attachments. One of ids or attachment_ids is required
+ +Parameters
+ +-
+
- ids: Get attachments for this bug ID +
- attachment_ids: Specific attachment ID to get +
https://bugzilla.readthedocs.io/en/latest/api/core/v1/attachment.html#get-attachment
+
+
+
+ createbug_required =
+('product', 'component', 'summary', 'version', 'description')
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ def
+ build_createbug( self, product=None, component=None, version=None, summary=None, description=None, comment_private=None, blocks=None, cc=None, assigned_to=None, keywords=None, depends_on=None, groups=None, op_sys=None, platform=None, priority=None, qa_contact=None, resolution=None, severity=None, status=None, target_milestone=None, target_release=None, url=None, sub_component=None, alias=None, comment_tags=None):
+
+
+
+
+
+ 1729 def build_createbug(self, +1730 product=None, +1731 component=None, +1732 version=None, +1733 summary=None, +1734 description=None, +1735 comment_private=None, +1736 blocks=None, +1737 cc=None, +1738 assigned_to=None, +1739 keywords=None, +1740 depends_on=None, +1741 groups=None, +1742 op_sys=None, +1743 platform=None, +1744 priority=None, +1745 qa_contact=None, +1746 resolution=None, +1747 severity=None, +1748 status=None, +1749 target_milestone=None, +1750 target_release=None, +1751 url=None, +1752 sub_component=None, +1753 alias=None, +1754 comment_tags=None): +1755 """ +1756 Returns a python dict() with properly formatted parameters to +1757 pass to createbug(). See bugzilla documentation for the format +1758 of the individual fields: +1759 +1760 https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#update-bug +1761 """ +1762 +1763 localdict = {} +1764 if blocks: +1765 localdict["blocks"] = listify(blocks) +1766 if cc: +1767 localdict["cc"] = listify(cc) +1768 if depends_on: +1769 localdict["depends_on"] = listify(depends_on) +1770 if groups is not None: +1771 localdict["groups"] = listify(groups) +1772 if keywords: +1773 localdict["keywords"] = listify(keywords) +1774 if description: +1775 localdict["description"] = description +1776 if comment_private: +1777 localdict["comment_is_private"] = True +1778 +1779 # Most of the machinery and formatting here is the same as +1780 # build_update, so reuse that as much as possible +1781 ret = self.build_update(product=product, component=component, +1782 version=version, summary=summary, op_sys=op_sys, +1783 platform=platform, priority=priority, qa_contact=qa_contact, +1784 resolution=resolution, severity=severity, status=status, +1785 target_milestone=target_milestone, +1786 target_release=target_release, url=url, +1787 assigned_to=assigned_to, sub_component=sub_component, +1788 alias=alias, comment_tags=comment_tags) +1789 +1790 ret.update(localdict) +1791 return ret +
Returns a python dict() with properly formatted parameters to +pass to createbug(). See bugzilla documentation for the format +of the individual fields:
+ +https://bugzilla.readthedocs.io/en/latest/api/core/v1/bug.html#update-bug
+
+
+
+
+
+
+
+
+
+
+
+ def
+ createbug(self, *args, **kwargs):
+
+
+
+
+
+ 1824 def createbug(self, *args, **kwargs): +1825 """ +1826 Create a bug with the given info. Returns a new Bug object. +1827 Check bugzilla API documentation for valid values, at least +1828 product, component, summary, version, and description need to +1829 be passed. +1830 """ +1831 data = self._validate_createbug(*args, **kwargs) +1832 rawbug = self._backend.bug_create(data) +1833 return Bug(self, bug_id=rawbug["id"], +1834 autorefresh=self.bug_autorefresh) +
Create a bug with the given info. Returns a new Bug object. +Check bugzilla API documentation for valid values, at least +product, component, summary, version, and description need to +be passed.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getuser(self, username):
+
+
+
+
+
+ 1841 def getuser(self, username): +1842 """ +1843 Return a bugzilla User for the given username +1844 +1845 :arg username: The username used in bugzilla. +1846 :raises XMLRPC Fault: Code 51 if the username does not exist +1847 :returns: User record for the username +1848 """ +1849 ret = self.getusers(username) +1850 return ret and ret[0] +
Return a bugzilla User for the given username
+ +:arg username: The username used in bugzilla.
+ +Raises
+ +-
+
- XMLRPC Fault: Code 51 if the username does not exist +:returns: User record for the username +
+
+
+
+
+
+
+
+
+
+
+ def
+ getusers(self, userlist):
+
+
+
+
+
+ 1852 def getusers(self, userlist): +1853 """ +1854 Return a list of Users from . +1855 +1856 :userlist: List of usernames to lookup +1857 :returns: List of User records +1858 """ +1859 userlist = listify(userlist) +1860 rawusers = self._backend.user_get({"names": userlist}) +1861 userobjs = [User(self, **rawuser) for rawuser in +1862 rawusers.get('users', [])] +1863 +1864 # Return users in same order they were passed in +1865 ret = [] +1866 for u in userlist: +1867 for uobj in userobjs[:]: +1868 if uobj.email == u: +1869 userobjs.remove(uobj) +1870 ret.append(uobj) +1871 break +1872 ret += userobjs +1873 return ret +
Return a list of Users from .
+ +:userlist: List of usernames to lookup +:returns: List of User records
+
+
+
+
+
+
+
+
+
+
+
+ def
+ searchusers(self, pattern):
+
+
+
+
+
+ 1876 def searchusers(self, pattern): +1877 """ +1878 Return a bugzilla User for the given list of patterns +1879 +1880 :arg pattern: List of patterns to match against. +1881 :returns: List of User records +1882 """ +1883 rawusers = self._backend.user_get({"match": listify(pattern)}) +1884 return [User(self, **rawuser) for rawuser in +1885 rawusers.get('users', [])] +
Return a bugzilla User for the given list of patterns
+ +:arg pattern: List of patterns to match against. +:returns: List of User records
+
+
+
+
+
+
+
+
+
+
+
+ def
+ createuser(self, email, name='', password=''):
+
+
+
+
+
+ 1887 def createuser(self, email, name='', password=''): +1888 """ +1889 Return a bugzilla User for the given username +1890 +1891 :arg email: The email address to use in bugzilla +1892 :kwarg name: Real name to associate with the account +1893 :kwarg password: Password to set for the bugzilla account +1894 :raises XMLRPC Fault: Code 501 if the username already exists +1895 Code 500 if the email address isn't valid +1896 Code 502 if the password is too short +1897 Code 503 if the password is too long +1898 :return: User record for the username +1899 """ +1900 args = {"email": email} +1901 if name: +1902 args["name"] = name +1903 if password: +1904 args["password"] = password +1905 self._backend.user_create(args) +1906 return self.getuser(email) +
Return a bugzilla User for the given username
+ +:arg email: The email address to use in bugzilla +:kwarg name: Real name to associate with the account +:kwarg password: Password to set for the bugzilla account
+ +Raises
+ +-
+
- XMLRPC Fault: Code 501 if the username already exists +Code 500 if the email address isn't valid +Code 502 if the password is too short +Code 503 if the password is too long +
Returns
+ +++User record for the username
+
+
+
+
+
+
+
+
+
+
+
+ def
+ updateperms(self, user, action, groups):
+
+
+
+
+
+ 1908 def updateperms(self, user, action, groups): +1909 """ +1910 A method to update the permissions (group membership) of a bugzilla +1911 user. +1912 +1913 :arg user: The e-mail address of the user to be acted upon. Can +1914 also be a list of emails. +1915 :arg action: add, remove, or set +1916 :arg groups: list of groups to be added to (i.e. ['fedora_contrib']) +1917 """ +1918 groups = listify(groups) +1919 if action == "rem": +1920 action = "remove" +1921 if action not in ["add", "remove", "set"]: +1922 raise BugzillaError("Unknown user permission action '%s'" % action) +1923 +1924 update = { +1925 "names": listify(user), +1926 "groups": { +1927 action: groups, +1928 } +1929 } +1930 +1931 return self._backend.user_update(update) +
A method to update the permissions (group membership) of a bugzilla +user.
+ +:arg user: The e-mail address of the user to be acted upon. Can + also be a list of emails. +:arg action: add, remove, or set +:arg groups: list of groups to be added to (i.e. ['fedora_contrib'])
+
+
+
+
+
+
+
+
+
+
+
+ def
+ getgroup(self, name, membership=False):
+
+
+
+
+
+ 1958 def getgroup(self, name, membership=False): +1959 """ +1960 Return a bugzilla Group for the given name +1961 +1962 :arg name: The group name used in bugzilla. +1963 :raises XMLRPC Fault: Code 51 if the name does not exist +1964 :raises XMLRPC Fault: Code 805 if the user does not have enough +1965 permissions to view groups +1966 :returns: Group record for the name +1967 """ +1968 ret = self.getgroups(name, membership=membership) +1969 return ret and ret[0] +
Return a bugzilla Group for the given name
+ +:arg name: The group name used in bugzilla.
+ +Raises
+ +-
+
- XMLRPC Fault: Code 51 if the name does not exist +
- XMLRPC Fault: Code 805 if the user does not have enough +permissions to view groups +:returns: Group record for the name +
+
+
+
+
+
+
+
+
+
+
+ def
+ getgroups(self, grouplist, membership=False):
+
+
+
+
+
+ 1971 def getgroups(self, grouplist, membership=False): +1972 """ +1973 Return a list of Groups from . +1974 +1975 :userlist: List of group names to lookup +1976 :returns: List of Group records +1977 """ +1978 grouplist = listify(grouplist) +1979 groupobjs = [ +1980 Group(self, **rawgroup) +1981 for rawgroup in self._getgroups( +1982 names=grouplist, membership=membership).get('groups', []) +1983 ] +1984 +1985 # Return in same order they were passed in +1986 ret = [] +1987 for g in grouplist: +1988 for gobj in groupobjs[:]: +1989 if gobj.name == g: +1990 groupobjs.remove(gobj) +1991 ret.append(gobj) +1992 break +1993 ret += groupobjs +1994 return ret +
Return a list of Groups from .
+ +:userlist: List of group names to lookup +:returns: List of Group records
+
+
+
+
+
+
+
+
+
+
+
+ def
+ add_external_tracker( self, bug_ids, ext_bz_bug_id, ext_type_id=None, ext_type_description=None, ext_type_url=None, ext_status=None, ext_description=None, ext_priority=None):
+
+
+
+
+
+ 2001 def add_external_tracker(self, bug_ids, ext_bz_bug_id, ext_type_id=None, +2002 ext_type_description=None, ext_type_url=None, +2003 ext_status=None, ext_description=None, +2004 ext_priority=None): +2005 """ +2006 Wrapper method to allow adding of external tracking bugs using the +2007 ExternalBugs::WebService::add_external_bug method. +2008 +2009 This is documented at +2010 https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#add-external-bug +2011 +2012 bug_ids: A single bug id or list of bug ids to have external trackers +2013 added. +2014 ext_bz_bug_id: The external bug id (ie: the bug number in the +2015 external tracker). +2016 ext_type_id: The external tracker id as used by Bugzilla. +2017 ext_type_description: The external tracker description as used by +2018 Bugzilla. +2019 ext_type_url: The external tracker url as used by Bugzilla. +2020 ext_status: The status of the external bug. +2021 ext_description: The description of the external bug. +2022 ext_priority: The priority of the external bug. +2023 """ +2024 param_dict = {'ext_bz_bug_id': ext_bz_bug_id} +2025 if ext_type_id is not None: +2026 param_dict['ext_type_id'] = ext_type_id +2027 if ext_type_description is not None: +2028 param_dict['ext_type_description'] = ext_type_description +2029 if ext_type_url is not None: +2030 param_dict['ext_type_url'] = ext_type_url +2031 if ext_status is not None: +2032 param_dict['ext_status'] = ext_status +2033 if ext_description is not None: +2034 param_dict['ext_description'] = ext_description +2035 if ext_priority is not None: +2036 param_dict['ext_priority'] = ext_priority +2037 params = { +2038 'bug_ids': listify(bug_ids), +2039 'external_bugs': [param_dict], +2040 } +2041 return self._backend.externalbugs_add(params) +
Wrapper method to allow adding of external tracking bugs using the +ExternalBugs::WebService::add_external_bug method.
+ +This is documented at +https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#add-external-bug
+ +bug_ids: A single bug id or list of bug ids to have external trackers + added. +ext_bz_bug_id: The external bug id (ie: the bug number in the + external tracker). +ext_type_id: The external tracker id as used by Bugzilla. +ext_type_description: The external tracker description as used by + Bugzilla. +ext_type_url: The external tracker url as used by Bugzilla. +ext_status: The status of the external bug. +ext_description: The description of the external bug. +ext_priority: The priority of the external bug.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ update_external_tracker( self, ids=None, ext_type_id=None, ext_type_description=None, ext_type_url=None, ext_bz_bug_id=None, bug_ids=None, ext_status=None, ext_description=None, ext_priority=None):
+
+
+
+
+
+ 2043 def update_external_tracker(self, ids=None, ext_type_id=None, +2044 ext_type_description=None, ext_type_url=None, +2045 ext_bz_bug_id=None, bug_ids=None, +2046 ext_status=None, ext_description=None, +2047 ext_priority=None): +2048 """ +2049 Wrapper method to allow adding of external tracking bugs using the +2050 ExternalBugs::WebService::update_external_bug method. +2051 +2052 This is documented at +2053 https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#update-external-bug +2054 +2055 ids: A single external tracker bug id or list of external tracker bug +2056 ids. +2057 ext_type_id: The external tracker id as used by Bugzilla. +2058 ext_type_description: The external tracker description as used by +2059 Bugzilla. +2060 ext_type_url: The external tracker url as used by Bugzilla. +2061 ext_bz_bug_id: A single external bug id or list of external bug ids +2062 (ie: the bug number in the external tracker). +2063 bug_ids: A single bug id or list of bug ids to have external tracker +2064 info updated. +2065 ext_status: The status of the external bug. +2066 ext_description: The description of the external bug. +2067 ext_priority: The priority of the external bug. +2068 """ +2069 params = {} +2070 if ids is not None: +2071 params['ids'] = listify(ids) +2072 if ext_type_id is not None: +2073 params['ext_type_id'] = ext_type_id +2074 if ext_type_description is not None: +2075 params['ext_type_description'] = ext_type_description +2076 if ext_type_url is not None: +2077 params['ext_type_url'] = ext_type_url +2078 if ext_bz_bug_id is not None: +2079 params['ext_bz_bug_id'] = listify(ext_bz_bug_id) +2080 if bug_ids is not None: +2081 params['bug_ids'] = listify(bug_ids) +2082 if ext_status is not None: +2083 params['ext_status'] = ext_status +2084 if ext_description is not None: +2085 params['ext_description'] = ext_description +2086 if ext_priority is not None: +2087 params['ext_priority'] = ext_priority +2088 return self._backend.externalbugs_update(params) +
Wrapper method to allow adding of external tracking bugs using the +ExternalBugs::WebService::update_external_bug method.
+ +This is documented at +https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#update-external-bug
+ +ids: A single external tracker bug id or list of external tracker bug + ids. +ext_type_id: The external tracker id as used by Bugzilla. +ext_type_description: The external tracker description as used by + Bugzilla. +ext_type_url: The external tracker url as used by Bugzilla. +ext_bz_bug_id: A single external bug id or list of external bug ids + (ie: the bug number in the external tracker). +bug_ids: A single bug id or list of bug ids to have external tracker + info updated. +ext_status: The status of the external bug. +ext_description: The description of the external bug. +ext_priority: The priority of the external bug.
+
+
+
+
+
+
+
+
+
+
+
+ def
+ remove_external_tracker( self, ids=None, ext_type_id=None, ext_type_description=None, ext_type_url=None, ext_bz_bug_id=None, bug_ids=None):
+
+
+
+
+
+ 2090 def remove_external_tracker(self, ids=None, ext_type_id=None, +2091 ext_type_description=None, ext_type_url=None, +2092 ext_bz_bug_id=None, bug_ids=None): +2093 """ +2094 Wrapper method to allow removal of external tracking bugs using the +2095 ExternalBugs::WebService::remove_external_bug method. +2096 +2097 This is documented at +2098 https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#remove-external-bug +2099 +2100 ids: A single external tracker bug id or list of external tracker bug +2101 ids. +2102 ext_type_id: The external tracker id as used by Bugzilla. +2103 ext_type_description: The external tracker description as used by +2104 Bugzilla. +2105 ext_type_url: The external tracker url as used by Bugzilla. +2106 ext_bz_bug_id: A single external bug id or list of external bug ids +2107 (ie: the bug number in the external tracker). +2108 bug_ids: A single bug id or list of bug ids to have external tracker +2109 info updated. +2110 """ +2111 params = {} +2112 if ids is not None: +2113 params['ids'] = listify(ids) +2114 if ext_type_id is not None: +2115 params['ext_type_id'] = ext_type_id +2116 if ext_type_description is not None: +2117 params['ext_type_description'] = ext_type_description +2118 if ext_type_url is not None: +2119 params['ext_type_url'] = ext_type_url +2120 if ext_bz_bug_id is not None: +2121 params['ext_bz_bug_id'] = listify(ext_bz_bug_id) +2122 if bug_ids is not None: +2123 params['bug_ids'] = listify(bug_ids) +2124 return self._backend.externalbugs_remove(params) +
Wrapper method to allow removal of external tracking bugs using the +ExternalBugs::WebService::remove_external_bug method.
+ +This is documented at +https://bugzilla.redhat.com/docs/en/html/integrating/api/Bugzilla/Extension/ExternalBugs/WebService.html#remove-external-bug
+ +ids: A single external tracker bug id or list of external tracker bug + ids. +ext_type_id: The external tracker id as used by Bugzilla. +ext_type_description: The external tracker description as used by + Bugzilla. +ext_type_url: The external tracker url as used by Bugzilla. +ext_bz_bug_id: A single external bug id or list of external bug ids + (ie: the bug number in the external tracker). +bug_ids: A single bug id or list of bug ids to have external tracker + info updated.
+
+ version =
+'3.3.0'
+
+
+
+
+
+
+
+