Issue and metric API examples

These examples are written in Python, but should be simple enough to understand even without an in-depth knowledge of that language.

All of the examples below use demosthenes, a C/C++ sample project installed with the Validate package at <server_install>/samples/demosthenes. The demosthenes sample project is only available when the entire Validate package is installed; it is not included with the Validate Server package. See the README file in that directory for instructions on how to set up the sample project.

You can try out the example scripts on the sample project, or on your own project. If you use them on your own project, you need to change the value for project. You may also need to change the value for host from localhost to your own Klocwork Server host.

For additional information on request parameters, you can visit http(s)://<klocwork_server_host>:<klocwork_server_port>/review/api.

For most of the examples below, with the exception of printing the project list, you can specify a stream by including the full path in the project field. For example: project = "myProj/myStream1/subVariant"

About error handling in these examples

When curl calls are made using the Web API, any errors that are encountered are printed to the console automatically. Note that the Python examples in this topic provide simplified error handling, for example:

Copy
builds = report(url, project, user, action)
print("Existing builds:")
for build in builds:
    print(build)

To better handle errors in your own Python scripts, use a try block:

Copy
try:
    builds = report(url, project, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Existing builds:")
    for build in builds:
        print(build)

About the following examples

This module (kwutil), which is used by the examples below, handles reading ltokens from your system. It has been made into a separate module for readability. Be sure to copy and paste the code below to create the kwutil module.

Copy
import os.path


def get_token(host, port, user):
    ltoken = os.path.normpath(os.path.expanduser("~/.klocwork/ltoken"))
    ltoken_file = open(ltoken, 'r')
    for r in ltoken_file:
        rd = r.strip().split(';')
        if rd[0] == host and rd[1] == str(port) and rd[2] == user:
            ltoken_file.close()
            return rd[3]
    ltoken_file.close()

Example: Search for all critical issues

This example script searches for all critical issues (with severities 1, 2 and 3) in the latest build of the Demosthenes sample project.

Copy
import getpass
import json
import time
import urllib.parse
import urllib.request

import kwutil


class Issue(object):
    def __init__(self, attrs):
        self.id = attrs["id"]
        self.message = attrs["message"]
        self.file = attrs["file"]
        self.method = attrs["method"]
        self.code = attrs["code"]
        self.severity = attrs["severity"]
        self.severityCode = attrs["severityCode"]
        self.supportLevel = attrs["supportLevel"]
        self.supportLevelCode = attrs["supportLevelCode"]
        self.state = attrs["state"]
        self.status = attrs["status"]
        self.taxonomyName = attrs["taxonomyName"]
        self.url = attrs["url"]
        self.created = time.ctime(attrs["dateOriginated"] / 1000)


    def __str__(self):
        return "[%d] %s\n\t%s | %s\n\tCode %s | Severity: %s(%d) | Support Level: %s(%d) | State: %s | Status: %s | Taxonomy: %s | Created: %s\n\t%s" % (
            self.id, self.message, self.file, self.method, self.code, self.severity, self.severityCode, self.supportLevel,
            self.supportLevelCode, self.state,
            self.status, self.taxonomyName, self.created, self.url
        )


def from_json(json_object):
    if 'id' in json_object:
        return Issue(json_object)
    return json_object


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
url = "http://%s:%d/review/api" % (host, port)
values = {"project": project, "user": user, "action": "search"}

login_token = kwutil.get_token(host, port, user)
if login_token is not None:
    values["ltoken"] = login_token

values["query"] = "severity:1-3"
data = urllib.parse.urlencode(values)
data = data.encode('utf-8')
req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
for record in response:
    print(json.loads(record, object_hook=from_json))

Example: Report detected issues

This example shows the distribution of detected issues by component, grouped by state.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Key(object):
    def __init__(self, attrs):
        self.id = attrs["id"]
        self.name = attrs["name"]

    def __str__(self):
        return "%s (%d)" % (self.name, self.id)


class Report(object):
    def __init__(self, attrs):
        self.rows = attrs["rows"]
        self.columns = attrs["columns"]
        self.data = attrs["data"]

    def __str__(self):
        result = ""
        maxRowName = 0
        for r in self.rows:
            maxRowName = max(len(str(r)), maxRowName)
        maxRowName += 1
        header = ' ' * maxRowName
        colPosition = []
        for c in self.columns:
            colPosition.append(len(header) + len(str(r)))
            header += str(c) + ' '
        result += header + '\n'
        for x in range(len(self.rows)):
            rHead = ('%-' + str(maxRowName) + 's') % str(self.rows[x])
            for y in range(len(self.columns)):
                rHead += ('%' + str(len(str(self.columns[y]))) + 's') % str(self.data[x][y]) + ' '
            result += rHead + '\n'
        return result


def from_json(json_object):
    if 'rows' in json_object:
        return Report(json_object)
    if 'id' in json_object:
        return Key(json_object)
    return json_object


def report(url, project, user, x=None, y=None, view=None, xDrilldown=-1, yDrilldown=-1):
    values = {"project": project, "user": user, "action": "report"}
    login_token = kwutil.get_token(host, port, user)
    if x is not None:
        values["x"] = x
    if y is not None:
        values["y"] = y
    if login_token is not None:
        values["ltoken"] = login_token
    if view is not None:
        values["view"] = view
    if xDrilldown != -1:
        values["xDrilldown"] = xDrilldown
    if yDrilldown != -1:
        values["yDrilldown"] = yDrilldown
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    for record in response:
        return json.loads(record, object_hook=from_json)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
url = "http://%s:%d/review/api" % (host, port)

try:
    reports = report(url, project, user, "Component", "State")
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print(reports)

Example: Retrieve issue details

This example shows how to get details about a specified issue ID.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Details(object):
    def __init__(self, attrs):
        self.id = attrs["id"]
        self.code = attrs["code"]
        self.name = attrs["name"]
        self.location = attrs["location"]
        self.build = attrs["build"]
        self.severity = attrs["severity"]
        self.supportLevel = attrs["supportLevel"]
        self.owner = attrs["owner"]
        self.state = attrs["state"]
        self.status = attrs["status"]
        if "history" in attrs:
            self.history = attrs["history"]
        else:
            self.history = None
        if "xSync" in attrs:
            self.xsync = attrs["xsync"]
        else:
            self.xsync = None


    def __str__(self):
        result = "Id:%s, Code:%s, Name:%s, Location:%s, Build:%s, Severity:%s, Support Level%s, Owner:%s, State:%s, Status:%s, History:%s" % (
            self.id, self.code, self.name, self.location, self.build, self.severity, self.supportLevel, self.owner,
            self.state,
            self.status, self.history)
        if self.xsync is not None:
            result = result + ", XSyncInfo:%s" % self.xsync
        return result


def from_json(json_object):
    # print json_object
    return Details(json_object)


def report(url, user, action, project, id, xsync=None):
    values = {"user": user, "action": action, "project": project, "id": id}
    if xsync is not None:
        values['include_xsync'] = xsync
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        # print "R:" ,record
        result.append(from_json(json.loads(record)))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
action = "issue_details"
url = "http://%s:%d/review/api" % (host, port)
project = "demosthenes"
id = "4"
xsync = "false"

try:
    issue_details = report(url, user, action, project, id, xsync)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Issue Details:")
    for details in issue_details:
        print(details)

Example: Retrieve CI issue details

This example shows how to get details about a specified CI issue ID.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Details(object):
    def __init__(self, attrs):
        self.id = attrs["id"]
        self.code = attrs["code"]
        self.name = attrs["name"]
        self.location = attrs["location"]
        self.build = attrs["build"]
        self.severity = attrs["severity"]
        self.supportLevel = attrs["supportLevel"]
        self.owner = attrs["owner"]
        self.status = attrs["status"]
        if "history" in attrs:
            self.history = attrs["history"]
        else:
            self.history = None
        if "xSync" in attrs:
            self.xsync = attrs["xsync"]
        else:
            self.xsync = None


    def __str__(self):
        result = "Id:%s, Code:%s, Name:%s, Location:%s, Build:%s, Severity:%s, Support Level%s, Owner:%s, State:%s, Status:%s, History:%s" % (
            self.id, self.code, self.name, self.location, self.build, self.severity, self.supportLevel, self.owner,
            self.state,
            self.status, self.history)
        if self.xsync is not None:
            result = result + ", XSyncInfo:%s" % self.xsync
        return result


def from_json(json_object):
    # print json_object
    return Details(json_object)


def report(url, user, action, project, id, ci_build_name):
    values = {"user": user, "action": action, "project": project, "id": id, "ci_build_name": ci_build_name}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        # print "R:" ,record
        result.append(from_json(json.loads(record)))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
action = "ci_issue_details"
url = "http://%s:%d/review/api" % (host, port)
project = "demosthenes"
id = "1"
ci_build_name = "ci_build_1"

try:
    ci_issue_details = report(url, user, action, project, id, ci_build_name)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Issue Details:")
    for details in ci_issue_details:
        print(details)

Example: Update issue status

This example shows how to change issue status, comment(s), owner(s), and bug tracker ID for any specified issues.

If you specify bug tracker ID, all other issue status values are ignored.
Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Status(object):
    def __init__(self, attrs):
        self.status_message = attrs["status_message"]

    def __str__(self):
        result = "Status message:%s" % self.status_message
        return result


def from_json(json_object):
    return Status(json_object)


def update_status(url, user, project, ids, status=None, comment=None, owner=None, bug_tracker_id=None):
    values = {'action': 'update_status', 'project': project, 'user': user, 'ids': ids}
    if status is not None:
        values['status'] = status
    if comment is not None:
        values['comment'] = comment
    if owner is not None:
        values['owner'] = owner
    if bug_tracker_id is not None:
        values['bug_tracker_id'] = bug_tracker_id
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
url = "http://%s:%d/review/api" % (host, port)
project = "demosthenes"
id = "1"
status = "Fix"
comment = "Making a status change"
owner = "jsmith" # pass "unowned" to clear the owner

try:
    status_messages = update_status(url, user, project, id, status, comment, owner)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Update Status:")
    for message in status_messages:
        print(message)

Example: Print the project list

This example shows how to print the list of projects.

By default, the query returns a list of base projects only. You can also have the query show all base projects and streams by specifying the include_streams flag with a value of true (default is false). For example, include a query with the following values:

  • action=projects

  • user=someone

  • include_streams=true

...returns the following aggregate results:

{"id":"project1","name":"project1","creator":"someone","description":""}

{"id":"project1_sub1","name":"project1/sub1","creator":"someone","description":"","tags":["s"]}

{"id":"project1_sub2","name":"project1/sub1/sub2","creator":"someone","description":""}

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class View(object):
    def __init__(self, attrs):
        self.name = attrs["name"]

    def __str__(self):
        result = "%s" % self.name
        return result


def from_json(json_object):
    return View(json_object)


def report(url, user, action):
    values = {"user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
action = "projects"
url = "http://%s:%d/review/api" % (host, port)

try:
    projects = report(url, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Existing projects:")
    for project in projects:
        print(project)

Example: Update projects

This example shows how to update the name and description for a specified project.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def update_project(url, name, user, action, description, new_name):
    values = {"name": name, "user": user, "action": action, "description": description, "new_name": new_name}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
name = "demosthenes"
action = "update_project"
description = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
new_name = "demosthenes2"
url = "http://%s:%d/review/api" % (host, port)

try:
    update_project(url, name, user, action, description, new_name)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Project updated!")

You can also use this action to turn on auto-deletion of builds and set how many you would like to keep with the threshold parameter.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def update_project(url, name, user, action, auto_delete_builds, auto_delete_threshold):
    values = {"name": name, "user": user, "action": action, "auto_delete_builds": auto_delete_builds,
              "auto_delete_threshold": auto_delete_threshold}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
name = "demosthenes"
action = "update_project"
auto_delete_builds = "true"
auto_delete_threshold = "30"
url = "http://%s:%d/review/api" % (host, port)

try:
    update_project(url, name, user, action, auto_delete_builds, auto_delete_threshold)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Project updated!")

Example: Create a project

This example shows how to create a new project.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def create_project(url, name, user, action):
    values = {"name": name, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
name = "demosthenes"
action = "create_project"
url = "http://%s:%d/review/api" % (host, port)

try:
    create_project(url, name, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Project created!")

Example: Delete a project

This example shows how to delete a specified project.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def delete_project(url, name, force, user, action):
    values = {"name": name, "force": force, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
name = "demosthenes"
force = True
action = "delete_project"
url = "http://%s:%d/review/api" % (host, port)

try:
    delete_project(url, name, force, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Project and its streams deleted!")

Example: Generate a Project Configuration report

This example shows how to generate a project configuration report for a specified project. The report displays project information such as creation date, Klocwork version and basic code metrics.
Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Config(object):
    def __init__(self, attrs):
        self.build = attrs["build"]
        self.creationDate = attrs["creationDate"]
        self.version = attrs["version"]
        self.numberOfFiles = attrs["numberOfFiles"]
        self.cFilesAnalyzed = attrs["cFilesAnalyzed"]
        self.systemFilesAnalyzed = attrs["systemFilesAnalyzed"]
        self.linesOfCode = attrs["linesOfCode"]
        self.linesOfComments = attrs["linesOfComments"]
        self.numberOfEntities = attrs["numberOfEntities"]
        self.numberOfFunctions = attrs["numberOfFunctions"]
        self.numberOfClasses = attrs["numberOfClasses"]
        self.taxonomies = attrs["taxonomies"]

    def __str__(self):
        result = "Build:%s, Creation Date:%s, Version:%s, Number of Files:%s, C Files Analyzed:%s, System Files Analyzed:%s, Lines of Code:%s, Lines of Comments:%s. Number of Entities:%s, Number of Functions:%s, Number of Classes:%s, Taxonomies:%s" % (
            self.build, self.creationDate, self.version, self.numberOfFiles, self.cFilesAnalyzed,
            self.systemFilesAnalyzed,
            self.linesOfCode, self.linesOfComments, self.numberOfEntities, self.numberOfFunctions, self.numberOfClasses,
            self.taxonomies)
        return result


def from_json(json_object):
    return Config(json_object)


def report(url, user, action, project, build=None):
    values = {"user": user, "action": action, "project": project}
    if build is not None:
        values['build'] = build
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = json.loads(response.read(), object_hook=from_json)
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
action = "project_configuration"
url = "http://%s:%d/review/api" % (host, port)
project = "demosthenes"
build = "build_1"

try:
    result = report(url, user, action, project, build)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Project Configuration:")
    print(result)

Example: Print the list of views

This example shows how to print the list of views.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class View(object):
    def __init__(self, attrs):
        self.name = attrs["name"]
        self.query = attrs["query"]
        self.creator = attrs["creator"]
        if "tags" in attrs:
            self.tags = attrs["tags"]
        else:
            self.tags = ""
        self.is_public = attrs["is_public"]

    def __str__(self):
        result = "Name:%s (Query:%s, Creator:%s, Public:%s) Tags: [" % (
            self.name, self.query, self.creator, self.is_public)
        for x in range(len(self.tags)):
            if not x:
                result = result + self.tags[x]
            else:
                result = result + ',' + self.tags[x]
        result += ']'
        return result


def from_json(json_object):
    return View(json_object)


def report(url, project, user):
    values = {"project": project, "user": user, "action": "views"}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
url = "http://%s:%d/review/api" % (host, port)

try:
    views = report(url, project, user)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    for view in views:
        print(view)

Example: Create a view

This example shows how to create views.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def create_view(url, user, project, name, action, query, tags):
    values = {"project": project, "user": user, "name": name, "action": action, "query": query, "tags": tags}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
name = "Sample View"
action = "create_view"
query = "severity:1-3"
tags = "c,security"
url = "http://%s:%d/review/api" % (host, port)
try:
    create_view(url, user, project, name, action, query, tags)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("View created!")

Example: Update views

This example shows how to update views.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def update_view(url, user, project, name, newname, action, query, is_public, tags):
    values = {"project": project,
              "user": user,
              "name": name,
              "new_name": newname,
              "action": action,
              "query": query,
              "is_public": is_public,
              "tags": tags}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
name = "Sample View"
newname = "Updated Sample View"
action = "update_view"
query = "severity:1"
tags = "c,security,important"
is_public = "true"
url = "http://%s:%d/review/api" % (host, port)
try:
    update_view(url, user, project, name, newname, action, query, is_public, tags)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("View updated!")

Example: Delete a view

This example shows how to delete views.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def delete_view(url, user, name, project, action):
    values = {"project": project, "name": name, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
name = "Sample View"
project = "demosthenes"
action = "delete_view"
url = "http://%s:%d/review/api" % (host, port)
try:
    delete_view(url, user, name, project, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("View deleted!")

Example: Print the list of modules

This example shows how to print the list of modules.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Module(object):
    def __init__(self, attrs):
        self.name = attrs["name"]

    def __str__(self):
        result = "%s" % (self.name)
        return result


def from_json(json_object):
    return Module(json_object)


def list_modules(url, project, user, action):
    values = {"project": project, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
action = "modules"
url = "http://%s:%d/review/api" % (host, port)

try:
    modules = list_modules(url, project, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Existing modules:")
    for module in modules:
        print(module)

Example: Create a module

This example shows how to create modules.

If an access control method has been set, you must have the Project admin role or have the 'manage modules' permission to create and edit modules. In order to add or change access permissions on a module, you need the 'assign role' permission (which a Project admin has by default).

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def create_module(url, user, project, name, action, allow_all, paths):
    values = {"project": project, "user": user, "name": name, "action": action, "allow_all": allow_all, "paths": paths}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
name = "mymodule"
action = "create_module"
allow_all = "true"
paths = "**/test/*"
url = "http://%s:%d/review/api" % (host, port)
try:
    create_module(url, user, project, name, action, allow_all, paths)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Module created!")

Example: Update a module

This example shows how to update a module.

If an access control method has been set, you must have the Project admin role or have the 'manage modules' permission to create and edit modules. In order to add or change access permissions on a module, you need the 'assign role' permission (which a Project admin has by default).

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def update_module(url, user, project, name, new_name, action, allow_all):
    values = {"project": project, "user": user, "name": name, "new_name": new_name, "action": action,
              "allow_all": allow_all}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
name = "mymodule"
new_name = "mymodule2"
action = "update_module"
allow_all = "false"
url = "http://%s:%d/review/api" % (host, port)
try:
    update_module(url, user, project, name, new_name, action, allow_all)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Module updated!")

Example: Delete a module

This example shows how to delete modules.

If an access control method has been set, you must have the Project admin role or have the 'manage modules' permission to create and edit modules. In order to add or change access permissions on a module, you need the 'assign role' permission (which a Project admin has by default).

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def delete_module(url, user, name, project, action):
    values = {"project": project, "name": name, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
name = "mymodule"
project = "demosthenes"
action = "delete_module"
url = "http://%s:%d/review/api" % (host, port)
try:
    delete_module(url, user, name, project, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Module deleted!")

Example: Print the list of builds

This example shows how to print the list of builds. For information on build management, see Managing integration builds.

Copy
import getpass
import json
import time
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Build(object):
    def __init__(self, attrs):
        self.id = attrs["id"]  # build id
        self.name = attrs["name"]  # build name
        self.date = time.ctime(attrs["date"] / 1000)  # build date
        self.keepit = attrs["keepit"]  # sticky flag

    def __str__(self):
        result = "%s: %s" % (self.name, self.date)
        return result


def from_json(json_object):
    return Build(json_object)


def report(url, project, user, action):
    values = {"project": project, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
action = "builds"
url = "http://%s:%d/review/api" % (host, port)

try:
    builds = report(url, project, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Existing builds:")
    for build in builds:
        print(build)

Example: Specify which builds to keep

This example specifies that every second build will not be deleted by the auto-delete feature.

This action also allows you to toggle whether a specific build should be kept by specifying the 'keepit' option.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Build(object):
    def __init__(self, attrs):
        self.id = attrs["id"]
        self.name = attrs["name"]
        self.date = attrs["date"]

    def __str__(self):
        return "Id: %s Name:%s Date:%i" % (self.id, self.name, self.date)


def from_json(json_object):
    return Build(json_object)


def keepit(build_name, login_token):
    print("retain " + build_name)
    values = {"project": project, "user": user, "action": "update_build", "name": build_name, "keepit": "true"}
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


def retain(url, project, user):
    values = {"project": project, "user": user, "action": "builds"}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)

    i = 0
    for record in response:
        build = json.loads(record, object_hook=from_json)

        i += 1
        if not i % 2:
            keepit(build.name, login_token)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
url = "http://%s:%d/review/api" % (host, port)

retain(url, project, user)

Example: Delete a build

This example shows how to delete builds. For information on build management, see Managing integration builds.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def delete_build(url, user, project, build, action):
    values = {"project": project, "name": build, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
build = "demosthenes_3"
action = "delete_build"
url = "http://%s:%d/review/api" % (host, port)
try:
    delete_build(url, user, project, build, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Build deleted!")

Example: Create a CI build

This example shows how to create a CI build.

Copy
import getpass
import json
import time
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class CiBuild(object):
    def __init__(self, attrs):
        self.id = attrs["id"]  # build id
        self.name = attrs["name"]  # build name
        self.date = time.ctime(attrs["date"] / 1000)  # build date

    def __str__(self):
        result = "%s: %s" % (self.name, self.date)
        return result


def from_json(json_object):
    return CiBuild(json_object)


def report(url, project, user, action):
    values = {"project": project, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
action = "ci_builds"
url = "http://%s:%d/review/api" % (host, port)

try:
    ci_builds = report(url, project, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Existing Ci Builds:")
    for ci_build in ci_builds:
        print(ci_build)

Example: Update a CI build

This example shows how to update a CI build.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def rename(url, user, action, project, old_ci_build_name, new_ci_build_name):
    values = {"user": user, "action": action, "project": project, "name": old_ci_build_name, "new_name": new_ci_build_name}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
url = "http://%s:%d/review/api" % (host, port)
action = "update_ci_build"
old_ci_build_name = "ci_build_1"
new_ci_build_name = "win-ci_build_1"


try:
    rename(url, user, action, project, old_ci_build_name, new_ci_build_name)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Ci Build successfully renamed")

Example: Delete a CI build

This example shows how to delete CI builds.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def delete_build(url, user, project, build, action):
    values = {"project": project, "name": build, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
build = "ci_build_1"
action = "delete_ci_build"
url = "http://%s:%d/review/api" % (host, port)
try:
    delete_build(url, user, project, build, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Build deleted!")

Example: Print a list of enabled checkers

This example shows how to print a list of enabled checkers.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class View(object):
    def __init__(self, attrs):
        self.code = attrs["code"]
        self.name = attrs["name"]
        self.enabled = attrs["enabled"]
        self.severity = attrs["severity"]
        self.supportLevel = attrs["supportLevel"]

    def __str__(self):
        result = "Code: %s\nName: %s\nEnabled: %s\nSeverity: %s\nSupport Level: %s\n" % (
            self.code, self.name, self.enabled, self.severity, self.supportLevel)
        return result


def from_json(json_object):
    return View(json_object)


def report(url, project, user, action):
    values = {"project": project, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
action = "defect_types"
taxonomy = "C and C++"
url = "http://%s:%d/review/api" % (host, port)

try:
    defects = report(url, project, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Defect types:")
    for defect in defects:
        print(defect)

Example: Print a list of taxonomies

This example shows how to print a list of taxonomies.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class View(object):
    def __init__(self, attrs):
        self.name = attrs["name"]
        self.is_custom = attrs["is_custom"]

    def __str__(self):
        result = "Name: %s\nIs Custom: %s\n" % (self.name, self.is_custom)
        return result


def from_json(json_object):
    return View(json_object)


def report(url, project, user, action):
    values = {"project": project, "user": user, "action": action}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    result = []
    for record in response:
        result.append(json.loads(record, object_hook=from_json))
    return result


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
action = "taxonomies"
url = "http://%s:%d/review/api" % (host, port)

try:
    taxonomies = report(url, project, user, action)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Taxonomies:")
    for taxonomy in taxonomies:
        print(taxonomy)

Example: Enable and disable checkers

This example shows how to enable and disable checkers.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def set_defect(url, project, user, action, code, enabled, severity):
    values = {"project": project, "user": user, "action": action, "code": code, "enabled": enabled,
              "severity": severity}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
action = "update_defect_type"
code = "VOIDRET"
enabled = "True"
severity = "1"
url = "http://%s:%d/review/api" % (host, port)

try:
    set_defect(url, project, user, action, code, enabled, severity)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())
else:
    print("Defect type %s updated!\nEnabled: %s\nSeverity: %s" % (code, enabled, severity))

Example: Report metrics

The following example reports the number of lines of commented and non-commented lines, the number of executable statements, the maximum nesting level, and cyclomatic complexity metrics for each file in project from last build.

See the Klocwork Metrics Reference for a list of valid metric codes.

Copy
import getpass
import json
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class Metric(object):
    def __init__(self, attrs):
        self.file = attrs["filePath"]
        self.entity = attrs["entity"]
        self.tag = attrs["tag"]
        self.value = attrs["metricValue"]

    def __str__(self):
        return "%s;%s;%d" % (self.file, self.tag, self.value)


def from_json(json_object):
    if 'filePath' in json_object:
        return Metric(json_object)
    return json_object


host = "localhost"
port = 8080
user = getpass.getuser()
project = "demosthenes"
url = "http://%s:%d/review/api" % (host, port)
values = {"project": project, "user": user, "action": "metrics"}

login_token = kwutil.get_token(host, port, user)
if login_token is not None:
    values["ltoken"] = login_token

values["query"] = "metric:+RNOEXSTAT,+LINESCOMM,+NCNBLOC_FILE,+RMAXLEVEL,+RCYCLOMATIC"
data = urllib.parse.urlencode(values)
data = data.encode('utf-8')
req = urllib.request.Request(url, data)
try:
    response = urllib.request.urlopen(req)
    for record in response:
        print(json.loads(record, object_hook=from_json))
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())

Aggregated search results

By default, the metrics API generates results on a per file basis. To generate aggregated search results for all files in a given query, specify the aggregate flag with a value of true (default is false). The following example shows aggregated search results:

A query with the following values:

  • action=metrics
  • user=someone
  • query=metric:+LOC_FILE
  • project=demosthenes
  • aggregate=true

...returns the following aggregate results:

{"tag":"LOC_FILE","sum":8113.0,"min":3.0,"max":966.0,"entries":47}

The aggregate flag is only really useful for data that has relative meaning. In other words, if a metric can be summed, or if max and min values can be determined.

Excluding system files from search results

By default, the metrics API generates results based on all files. You can have the query omit system files by specifying the exclude_system_files flag with a value of true (default is false), for example:

A query with the following values:

  • action=metrics
  • user=someone
  • project=demosthenes
  • aggregate=true
  • exclude_system_files=true
  • query=metric:+LOC_FILE

Example curl request:

curl --data "action=metrics&user=someone&project=demosthenes&exclude_system_files=true&query=metric:%2bLOC_FILE&aggregate=true" http://localhost:8080/review/api

...returns the following results:

{"tag":"LOC_FILE","sum":322.0,"min":3.0,"max":68.0,"entries":13}

Importing server settings, projects and code review

You can also use the API to import server settings, projects or code reviews via the command line. This can be done for each of these methods as follows:

To import server settings

The following example imports authentication configuration, permissions, custom metrics, reports definitions and e-mail subscription settings.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def import_server_configuration(url, user, sourceURL, sourceAdmin, sourcePassword):
    values = {"action": "import_server_configuration",
              "user": user,
              "sourceURL": sourceURL,
              "sourceAdmin": sourceAdmin}
    if sourcePassword is not None:
        values["sourcePassword"] = sourcePassword
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()

sourceURL = "http://oldhost:8080"
sourceAdmin = "old admin user name"
sourcePassword = None

url = "http://%s:%d/review/api" % (host, port)

try:
    import_server_configuration(url, user, sourceURL, sourceAdmin, sourcePassword)
    print("Imported server configuration!")
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())

To import a project

The following example imports data collected by Klocwork for the specified project.

Copy
import getpass
import urllib.error
import urllib.parse
import urllib.request

import kwutil


def import_project(url, user, project, sourceURL, sourceAdmin, sourcePassword):
    values = {"action": "import_project",
              "user": user,
              "project": project,
              "sourceURL": sourceURL,
              "sourceAdmin": sourceAdmin}
    if sourcePassword is not None:
        values["sourcePassword"] = sourcePassword
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


host = "localhost"
port = 8080
user = getpass.getuser()

project = "projectA"
sourceURL = "http://oldhost:8080"
sourceAdmin = "old admin user name"
sourcePassword = None

url = "http://%s:%d/review/api" % (host, port)

try:
    import_project(url, user, project, sourceURL, sourceAdmin, sourcePassword)
    print("Imported project!")
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())

To check import status

You can use this API method to check the status of importing your server settings, project or code review.

Copy
import getpass
import json
import sys
import time
import urllib.error
import urllib.parse
import urllib.request

import kwutil


class ImportStatus(object):
    def __init__(self, project, attrs):
        self.project = project
        self.stage = attrs["stage"]
        self.progress = attrs["progress"]
        self.failed = attrs["failed"]
        self.hasWarnings = attrs["hasWarnings"]
        self.projectReady = attrs["projectReady"]
        self.complete = attrs["complete"]

    def __str__(self):
        return "Project: %s\n\tStage: %s | Progress: %s%% | Failed: %s | Warnings: %s | Project Ready: %s | Complete: %s" % (
            self.project, self.stage, self.progress, self.failed, self.hasWarnings, self.projectReady, self.complete)


def import_status(url, user):
    values = {"action": "import_status", "user": user}
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    response = urllib.request.urlopen(req)
    importStatus = []
    for record in response:
        attrs = json.loads(record)
        for key in attrs.keys():
            importStatus.append(ImportStatus(key, attrs[key]))
    return importStatus


def import_project(url, user, project, sourceURL, sourceAdmin, sourcePassword=None, ):
    values = {"action": "import_project",
              "user": user,
              "project": project,
              "sourceURL": sourceURL,
              "sourceAdmin": sourceAdmin}
    if sourcePassword:
        values["sourcePassword"] = sourcePassword
    login_token = kwutil.get_token(host, port, user)
    if login_token is not None:
        values["ltoken"] = login_token
    data = urllib.parse.urlencode(values)
    data = data.encode('utf-8')
    req = urllib.request.Request(url, data)
    urllib.request.urlopen(req)


def wait_for_import(url, user, project):
    is_timeout = False
    TIME_OUT = time.time() + 60 * 20
    incomplete = [project]

    if len(incomplete) == 0:
        return

    while True:
        for status in import_status(url, user):
            if status.project != project:
                continue

            # If all operations are complete then exit the loop
            if len(incomplete) == 0:
                break

            if status.project in incomplete:
                is_timeout = time.time() > TIME_OUT

            if status.complete or status.failed:
                print(status.stage)
                incomplete.pop(incomplete.index(status.project))
                break
            elif is_timeout:
                print("Import of project '%s' took longer than expected." % status.project)
                print("Check if import is still progressing.")
                sys.exit(-1)

        # If all projects are complete then exit the loop
        if len(incomplete) == 0:
            break

        time.sleep(10)


host = "localhost"
port = 8080
user = getpass.getuser()

url = "http://%s:%d/review/api" % (host, port)

project = "demosthenes"
sourceURL = "http://oldhost:8080"
sourceAdmin = "old admin user name"

try:
    import_project(url, user, project, sourceURL, sourceAdmin)
    print("Import started")
    wait_for_import(url, user, project)
except urllib.error.HTTPError as e:
    print("Request failed:", e.reason, ":", e.read())

To check the Klocwork Server version

This action allows you to retrieve the Klocwork Server version. Here is an example curl command for this action:
curl --data "action=version&user=myself&" http://jsmith.klocwork.com:8080/review/api
The follow listing shows sample output from this command:
              1 {
              2 majorVersion: "10.1"
              3 minorVersion: "1"
              4 }

To list the statuses of all tasks running on the Klocwork Server

This action allows you to list the status of each task running on your Klocwork Server. Here is an example curl command for this action:
curl --data "action=task_status&user=myself&" http://jsmith.klocwork.com:8080/review/api