Python client for QuickBuild

Status

Build status Docs status Coverage status Version status Downloads status

Documentation

Read the Docs

Official REST API documentation

Installation

pip3 install -U quickbuild

Examples

Get server version:

from quickbuild import QBClient

client = QBClient('http://server', 'login', 'password')
version = client.system.get_version()
print(version)

With async client:

import asyncio
from quickbuild import AsyncQBClient

client = AsyncQBClient('http://server', 'login', 'password')

async def example():
    await client.system.get_version()

loop = asyncio.get_event_loop()
try:
    loop.run_until_complete(example())
finally:
    loop.run_until_complete(client.close())
    loop.close()

Content type

By default QuickBuild returns XML content, but starting from 10 version it also has native support of JSON content, usually it’s much more convenient to use native Python types (parsed XML) instead of pure XML string.

So, that is why current package introducing three types of content, this type and behaviour can be set globally for client instances, and can be rewritten for some methods.

  • PARSE (using by default)
    • GET: parse XML to native Python types.

    • POST: pure XML string.

  • XML
    • GET: return native XML without any transformations.

    • POST: pure XML string.

  • JSON (QuickBuild 10+)
    • GET: parsed JSON string.

    • POST: dumps object to JSON string.

Development

It’s possible to run QuickBuild community edition locally using docker:

Build locally:

docker build .  -f docker/QB10.Dockerfile -t quickbuild:10
docker run --restart always --name qb10 -d -p 8810:8810 quickbuild:10

Or run prepared image:

docker run --restart always --name qb10 -d -p 8810:8810 pbelskiy/quickbuild:10

Then open http://localhost:8810/

Testing

Prerequisites: tox

Then just run tox, all dependencies and checks will run automatically

tox

Contributing

Feel free for any contributions.

API endpoints

Core

class quickbuild.QBClient(url: str, user: Optional[str] = None, password: Optional[str] = None, *, content_type: Optional[quickbuild.helpers.ContentType] = ContentType.PARSE, verify: bool = True, timeout: Optional[float] = None, retry: Optional[dict] = None)

QuickBuild client class.

Parameters
  • url (str) – Url of QuickBuild server.

  • user (Optional[str]) – User name, login.

  • password (Optional[str]) – Password for user.

  • verify (Optional[bool]) – Verify SSL (default: true).

  • content_type (Optional[ContentType]) – How to process server content, get native XML as string, or parsing XML to Python types, or uses native JSON if QB10+ used.

  • timeout (Optional[float]) – HTTP request timeout.

  • retry (Optional[dict]) –

    Retry options to prevent failures if server restarting or temporary network problem. Disabled by default use total > 0 to enable.

    • total: int Total retries count.

    • factor: int Sleep between retries (default 1)

      {factor} * (2 ** ({number of total retries} - 1))

    • statuses: List[int] HTTP statues retries on. (default [])

    Example:

    retry = dict(
        total=10,
        factor=1,
        statuses=[500]
    )
    

    With factor = 1

    Retry number

    Sleep

    1

    0.5 seconds

    2

    1.0 seconds

    3

    2.0 seconds

    4

    4.0 seconds

    5

    8.0 seconds

    6

    16.0 seconds

    7

    32.0 seconds

    8

    1.1 minutes

    9

    2.1 minutes

    10

    4.3 minutes

    11

    8.5 minutes

    12

    17.1 minutes

    13

    34.1 minutes

    14

    1.1 hours

    15

    2.3 hours

    16

    4.6 hours

    17

    9.1 hours

    18

    18.2 hours

    19

    36.4 hours

    20

    72.8 hours

Returns

Client instance

close() None

Close client session

class quickbuild.AsyncQBClient(url: str, user: Optional[str] = None, password: Optional[str] = None, *, content_type: Optional[quickbuild.helpers.ContentType] = ContentType.PARSE, loop: Optional[asyncio.events.AbstractEventLoop] = None, verify: bool = True, timeout: Optional[float] = None, retry: Optional[dict] = None)

QuickBuild async client class.

Parameters
  • url (str) – Url of QuickBuild server, must include API version.

  • user (Optional[str]) – User name, login.

  • password (Optional[str]) – Password for user.

  • content_type (Optional[ContentType]) – How to process server content, get native XML as string, or parsing XML to Python types, or uses native JSON if QB10+ used.

  • loop (Optional[AbstractEventLoop]) – Asyncio current event loop.

  • verify (Optional[bool]) – Verify SSL (default: true).

  • timeout (Optional[int]) – HTTP request timeout.

  • retry (Optional[dict]) –

    Retry options to prevent failures if server restarting or temporary network problem. Disabled by default use total > 0 to enable.

    • total: int Total retries count.

    • factor: int Sleep between retries (default 1)

      {factor} * (2 ** ({number of total retries} - 1))

    • statuses: List[int] HTTP statues retries on. (default [])

    Example:

    retry = dict(
        total=10,
        factor=1,
        statuses=[500]
    )
    

Returns

AsyncClient instance

async close() None

Close client session

class quickbuild.core.Response(status, headers, body)

Create new instance of Response(status, headers, body)

property body

Alias for field number 2

property headers

Alias for field number 1

property status

Alias for field number 0

class quickbuild.core.QuickBuild(content_type: Optional[quickbuild.helpers.ContentType])

NB: somehow using -H “Accept: application/json,application/xml,*/*” leads to server error.

Agents

class quickbuild.endpoints.agents.Agents(quickbuild)
get_active() Union[List[dict], str]

Get list of active build agents.

Returns

list of active build agents.

Return type

List[dict]

get_inactive() Union[List[dict], str]

Get list of inactive build agents.

Returns

list of inactive build agents.

Return type

List[dict]

get_unauthorized() Union[List[dict], str]

Get list of unauthorized build agents.

Returns

list of unauthorized build agents.

Return type

List[dict]

get_running_steps(node_address: str) Union[List[dict], str]

Get list of running steps on specified build agent (since 5.1.24).

Returns

list of running steps.

Return type

List[dict]

Audits

class quickbuild.endpoints.audits.Audits(quickbuild)
get(count: int, *, username: Optional[str] = None, source: Optional[str] = None, action: Optional[str] = None, since: Optional[str] = None, until: Optional[str] = None, first: Optional[int] = None) List[dict]

Get all users in the system.

Parameters
  • count (int) – Specified number of audit entries to return. This param must be specified in order not to mistakenly return all audits to stress the system.

  • username (Optional[str]) – Name of the user to audit. If not specified, audit log of all users will be searched.

  • source (Optional[str]) – Specify source of audit to match. The character * can be used in the source string to do wildcard match. If not specified, audits from all sources will be matched.

  • action (Optional[str]) – Action of the audit to match. If left empty, any action will be matched.

  • since (Optional[str]) – In the format of yyyy-MM-dd HH:mm, for example: 2009-11-12 13:00. If specified, search audits generated after this date.

  • until (Optional[str]) – In the format of yyyy-MM-dd HH:mm, for example: 2009-11-12 14:00. If specified, search builds generated before this date.

  • first (Optional[int]) – Specified first audit entry to return. If not specified, value 0 is assumed.

Returns

list of audits.

Return type

List[dict]

count() int

Get count of audits.

Returns

count of audits.

Return type

int

Builds

class quickbuild.endpoints.builds.Builds(quickbuild)
get_info(build_id: int, *, content_type: Optional[quickbuild.helpers.ContentType] = None) Union[dict, str]

Get build info as raw XML string.

Parameters
  • build_id (int) – build id.

  • content_type (Optional[ContentType]) – Select needed content type if not set, default value of client instance is used.

Returns

build information.

Return type

Union[dict, str]

get_status(build_id: int) str

Get build status.

Parameters

build_id (int) – build id.

Returns

Build status, for example: SUCCESS

Return type

str

get_begin_date(build_id: int) datetime.datetime

Get build begin date.

Parameters

build_id (int) – build id.

Returns

return datetime from stdlib.

Return type

datetime

get_version(build_id: int) str

Get build version.

Parameters

build_id (int) – build id.

Returns

build version

Return type

str

get_duration(build_id: int) int

Get build duration in ms. QBProcessingError will be raised if build is not finished.

Parameters

build_id (int) – build id.

Returns

build duration in ms

Return type

int

get_request_id(build_id: int) str

Get request id. QBProcessingError will be raised if build is finished.

Parameters

build_id (int) – build id.

Returns

request id. Example: fd2339a1-bc71-429d-b4ee-0ac650c342fe

Return type

str

get_id_by_request_id(identifier: int) int

Get build id by request id.

Parameters

identifier (int) – request identifier.

Returns

build identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_id_by_build_name(name: str) int

Get build id by build name.

For example how to get id of latest build in configuration with id 1, name will be 1.latest

Parameters

name (str) – build name.

Returns

build identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_steps(build_id: int) str

Get build steps.

Parameters

build_id (int) – build id.

Returns

builds steps as XML document

Return type

str

get_repositories(build_id: int) str

Get build repositories.

Parameters

build_id (int) – build id.

Returns

builds repositories as XML document

Return type

str

get_dependencies(build_id: int) str

Get build dependencies.

Parameters

build_id (int) – build id.

Returns

builds dependencies as XML document

Return type

str

get_dependents(build_id: int) str

Get build dependents.

Parameters

build_id (int) – build id.

Returns

builds dependents as XML document

Return type

str

get_files(build_id: int, path: str) str

Get information about published files.

Parameters
  • build_id (int) – Build id.

  • path (str) – Represents the relative path under publish directory of the specified build.

Returns

information about files and directories under the specified path.

Return type

str

Raises

QBProcessingError – will be raised if specified path does not exist.

get_notifications(last_notified_build_id: Optional[int] = None) Union[List[dict], str]

Get notifications belonging to current user, specified when client instance was initialized.

Parameters

last_notified_build_id (Optional[int]) – If not specified, the most recent notification will be returned; otherwise, all notifications after specified build will be returned.

Returns

list of builds to be notified.

Return type

Union[List[dict], str]

search(count: int, *, configuration_id: Optional[int] = None, recursive: Optional[bool] = False, from_date: Optional[str] = None, to_date: Optional[str] = None, version: Optional[str] = None, status: Optional[str] = None, user_id: Optional[int] = None, master_node: Optional[str] = None, promoted_from_id: Optional[int] = None, request_id: Optional[int] = None, first: Optional[int] = None) List[dict]

Search builds by criteria.

Parameters
  • count (int) – Specify number of builds to return. This parameter is required.

  • configuration_id (Optional[int]) – This tells QuickBuild under which configuration id to search builds. If not specified, all configurations will be searched.

  • recursive (Optional[bool]) – If set to true, QuickBuild will also search builds in all descendent configurations of specified configuration. The value is assumed as false if not specified.

  • from_date (Optional[str]) – In the format of yyyy-MM-dd, for example: 2009-11-12. If specified, search builds generated after this date.

  • to_date (Optional[str]) – In the format of yyyy-MM-dd, for example: 2009-11-12. If specified, search builds generated before this date.

  • version (Optional[str]) – Specify the build version to match. The character * can be used in the version string to do wildcard match. If not specified, all versions will be matched.

  • status (Optional[str]) – Status of the build to match. Valid build statuses are: SUCCESSFUL, FAILED, RECOMMENDED, CANCELLED, RUNNING, TIMEOUT. If left empty, any build status will be matched.

  • user_id (Optional[int]) – Match builds which is triggered by specified user. If not specified, builds triggered by any user will be matched.

  • master_node (Optional[str]) – Match builds with master step running on specified node if specified.

  • promoted_from_id (Optional[int]) – Match builds promoted from specified build id if specified.

  • request_id (Optional[int]) – If specified, match builds with specified build request id.

  • first (Optional[int]) – Specify start position of search results. Position 0 is assumed if this param is not specified.

Returns

builds search result list.

Return type

List[dict]

count(*, configuration_id: Optional[int] = None, recursive: Optional[bool] = False, from_date: Optional[str] = None, to_date: Optional[str] = None, version: Optional[str] = None, status: Optional[str] = None, user_id: Optional[int] = None, promoted_from_id: Optional[int] = None, request_id: Optional[int] = None) int

Get builds count by criteria.

Parameters
  • configuration_id (Optional[int]) – This tells QuickBuild under which configuration id to search builds. If not specified, all configurations will be searched.

  • recursive (Optional[bool]) – If set to true, QuickBuild will also search builds in all descendent configurations of specified configuration. The value is assumed as false if not specified.

  • from_date (Optional[str]) – In the format of yyyy-MM-dd, for example: 2009-11-12. If specified, search builds generated after this date.

  • to_date (Optional[str]) – In the format of yyyy-MM-dd, for example: 2009-11-12. If specified, search builds generated before this date.

  • version (Optional[str]) – Specify the build version to match. The character * can be used in the version string to do wildcard match. If not specified, all versions will be matched.

  • status (Optional[str]) – Status of the build to match. Valid build statuses are: SUCCESSFUL, FAILED, RECOMMENDED, CANCELLED, RUNNING, TIMEOUT. If left empty, any build status will be matched.

  • user_id (Optional[int]) – Match builds which is triggered by specified user. If not specified, builds triggered by any user will be matched.

  • promoted_from_id (Optional[int]) – Match builds promoted from specified build id if specified.

  • request_id (Optional[int]) – If specified, match builds with specified build request id.

Returns

builds count.

Return type

int

update(configuration: str) int

Update build using XML configuration.

Please note that the configuration element denotes id of the belonging configuration. Normally you do not need to create the XML from scratch, you may retrieve XML representation of the build, modify certain parts of the XML and post back to above url.

Parameters

configuration (str) – XML document.

Returns

build id being updated.

Return type

int

create(configuration: str) int

Create a build using XML/JSON configuration.

The configuration element denotes id of the belonging configuration. Normally you do not need to create the XML from scratch: you may retrieve XML representation of a templating build or using get_info() with content_type=ContentType.XML, remove the id element, modify certain parts and use it as configuration for create method.

Parameters

configuration (str) – XML/JSON configuration.

Returns

build id of the the newly created build.

Return type

int

Raises

QBError – configuration validation error

delete(build_id: int) None

Delete build.

Parameters

build_id (int) – build id.

Returns

None

Configurations

class quickbuild.endpoints.configurations.Configurations(quickbuild)
get() List[dict]

Get all configurations in the system. For performance reason, only brief information of the configuration will be returned here, including id, name, description, schedule, runMode, errorMessage, parent id. You may get the full xml representation using id if necessary.

Returns

list of configurations.

Return type

List[dict]

get_child(parent_id: int) List[dict]

Get a list of child configurations.

Parameters

parent_id (int) – parent configuration identifier.

Returns

list of child configurations.

Return type

List[dict]

get_descendent(parent_id: int) List[dict]

Get a list of descendent configurations.

Parameters

parent_id (int) – parent configuration identifier.

Returns

list of descendent configurations.

Return type

List[dict]

get_info(configuration_id: int, *, content_type: Optional[quickbuild.helpers.ContentType] = None) Union[dict, str]

Get full configuration info.

Parameters
  • configuration_id (int) – Configuration identifier.

  • content_type (Optional[ContentType]) – Select needed content type if not set, default value of client instance is used.

Returns

configuration content.

Return type

Union[dict, str]

get_path(configuration_id: int) str

Get configuration path.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration path.

Return type

str

get_id_by_path(path: str) int

Get configuration id by path.

Parameters

path (str) – configuration path.

Returns

configuration identifier.

Return type

int

get_name(configuration_id: int) str

Get configuration name.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration name.

Return type

str

get_description(configuration_id: int) str

Get configuration description.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration description.

Return type

str

get_error_message(configuration_id: int) str

Get configuration error message.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration error message.

Return type

str

get_run_mode(configuration_id: int) str

Get configuration run mode.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration run mode.

Return type

str

get_schedule(configuration_id: int) dict

Get configuration schedule.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration schedule.

Return type

dict

Raises

QBProcessingError – will be raised if schedule is inherited from parent configuration.

get_average_duration(configuration_id: int, *, from_date: Optional[datetime.date], to_date: Optional[datetime.date]) int

Get configuration average duration.

Parameters

configuration_id (int) – configuration identifier.

Returns

milliseconds of average build duration.

Return type

int

get_success_rate(configuration_id: int, *, from_date: Optional[datetime.date], to_date: Optional[datetime.date]) int

Get configuration success rate.

Parameters

configuration_id (int) – configuration identifier.

Returns

value in the range of 0~100, with 0 stands for 0%, and 100

stands for 100%.

Return type

int

get_parent(configuration_id: int) int

Get parent configuration id.

Parameters

configuration_id (int) – configuration identifier.

Returns

id of parent configuration.

Return type

int

Raises

QBProcessingError – the configuration is root configuration and does not have parent.

update(configuration: str) int

Update a configuration using XML configuration.

Normally you do not need to create the XML from scratch: you may get XML representation of the configuration using get_info() method with content_type=ContentType.XML and modify certain parts of the XML.

Parameters

configuration (str) – XML document.

Returns

configuration id being updated.

Return type

int

create(configuration: str) int

Create a configuration using XML/JSON configuration.

Please note that:

  • The parent element denotes id of the parent configuration. Normally you do not need to create the xml from scratch: you may retrieve xml representation of a templating configuration using various configuration access methods or get_info() with content_type=ContentType.XML, remove the id element, modify certain parts and use it for create() method.

  • Secret elements (Elements with attribute “secret=encrypt” in XML representation of an existing configuration, typically they are repository passwords, secret variable values, etc.) should not contain the “secret” attribute; otherwise QuickBuild will think that the password has already been encrypted. However if you creating configuration by copying existing one and want to remain the passwords, the “secret” attribute should then be preserved.

Parameters

configuration (str) – XML/JSON document.

Returns

configuration id of newly created configuration.

Return type

int

Raises

QBError – XML validation error

delete(configuration_id: int) None

Delete configuration.

Parameters

configuration_id (int) – configuration id.

Returns

None

copy(configuration_id: int, parent_id: int, name: str, recursive: bool) int

Copy configuration (available since version 4.0.72)

Parameters
  • configuration_id (int) – Configuration id to be copied.

  • parent_id (int) – Configuration id of the parent to place newly copied configuration.

  • name (str) – Name of the newly copied configuration.

  • recursive (bool) – Specify parameter recursive=true to copy specified configuration and all its descendant configurations recursively; otherwise, only the configuration itself will be copied.

Returns

configuration id of the newly copied configuration.

Return type

int

Dashboards

class quickbuild.endpoints.dashboards.Dashboards(quickbuild)
get() List[dict]

Get all dashboards in the system.

Returns

list of all dashboards.

Return type

List[dict]

get_info(dashboard_id: int, *, content_type: Optional[quickbuild.helpers.ContentType] = None) Union[dict, str]

Get information about specified dashboard.

Parameters
  • dashboard_id (int) – Dashboard identifier.

  • content_type (Optional[ContentType]) – Select needed content type, if not set default value of client instance is used.

Returns

dashboard detailed information.

Return type

Union[dict, str]

get_id_by_fqn(fqn: str) int

Get dashboard id by dashboard fqn (fully qualified name).

<dashboard fqn> is of the form <user id>.<dashboard name>.

Parameters

fqn (str) – fqn (fully qualified name).

Returns

dashboard identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

update(configuration: str) int

Update a dashboard using XML/JSON configuration.

Normally you do not need to create the configuration from scratch, you may retrieve it representation of the dashboard using get_info(), modify certain parts and use it as new configuration.

Parameters

configuration (str) – XML/JSON document.

Returns

dashboard id being updated.

Return type

int

create(configuration: str) int

Create a dashboard using XML/JSON configuration.

Please note that the posted configuration should NOT contain the id element; otherwise, QuickBuild will treat the post as an updating to the dashboard with that id.

Normally you do not need to create the configuration from scratch, you may retrieve it representation of the dashboard using get_info(), modify certain parts and use it as new configuration.

Parameters

configuration (str) – XML/JSON document.

Returns

dashboard id being created.

Return type

int

Raises

QBError – configuration validation error

delete(dashboard_id: int) None

Delete specified dashboard.

Parameters

dashboard_id (int) – dashboard identifier.

Returns

dashboard id being deleted.

Return type

int

Groups

class quickbuild.endpoints.groups.Groups(quickbuild)
get() List[dict]

Get all groups in the system.

Returns

list of groups.

Return type

List[dict]

get_info(group_id: int, *, content_type: Optional[quickbuild.helpers.ContentType] = None) Union[dict, str]

Get information about specified group.

Parameters
  • group_id (int) – Group identifier.

  • content_type (Optional[ContentType]) – Select needed content type if not set, default value of client instance is used.

Returns

group information.

Return type

dict

get_id_by_name(name: str) int

Get group id by name.

Parameters

name (str) – group name.

Returns

group identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

update(configuration: str) int

Update a group using XML configuration.

Normally you do not need to create the XML from scratch: you may retrieve XML representation of the group using get_info() method, modify certain parts of the XML and post back to above url.

Parameters

configuration (str) – XML document.

Returns

group id being updated.

Return type

int

create(configuration: str) int

Create a group using XML/JSON configuration.

Normally you do not need to create the XML from scratch: you may retrieve XML representation of a templating group using get_info() method with content_type=ContentType.XML, remove the id element, modify certain parts and use i XML as configuration for create method.

Parameters

configuration (str) – XML/JSON configuration.

Returns

group id being created.

Return type

int

Raises

QBError – XML validation error

delete(group_id: int) None

Delete specified group.

Parameters

group_id (int) – group identifier.

Returns

group id being deleted.

Return type

int

Identifiers

class quickbuild.endpoints.identifiers.Identifiers(quickbuild)

Most of QuickBuild RESTful API relies on identifier of the object, which can be retrieved with the id service explained here.

https://wiki.pmease.com/display/QB10/Retrieve+Object+Identifier

get_resource_id_by_name(name: str) int

Get resource id by name.

This feature is available since 6.1.35

Parameters

name (str) – resource path.

Returns

resource identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_configuration_id_by_path(path: str) int

Get configuration id by path.

Parameters

path (str) – configuration path.

Returns

configuration identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_user_id_by_name(name: str) int

Get user id by name.

Parameters

name (str) – user name.

Returns

user identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_group_id_by_name(name: str) int

Get group id by name.

Parameters

name (str) – group name.

Returns

group identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_queue_id_by_name(name: str) int

Get queue id by name.

Parameters

name (str) – queue name.

Returns

queue identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_build_id_by_request_id(identifier: int) int

Get build id by request id.

Parameters

identifier (int) – request identifier.

Returns

build identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_build_id_by_build_name(name: str) int

Get build id by build name.

For example how to get id of latest build in configuration with id 1, name will be 1.latest

Parameters

name (str) – build name.

Returns

build identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

get_dashboard_id_by_dashboard_fqn(fqn: str) int

Get dashboard id by dashboard fqn (fully qualified name).

<dashboard fqn> is of the form <user id>.<dashboard name>.

Parameters

fqn (str) – fqn (fully qualified name).

Returns

dashboard identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

Measurements

class quickbuild.endpoints.measurements.Measurements(quickbuild)
get(*, source: Optional[str] = None, period: Optional[str] = None, start_time: Optional[str] = None, end_time: Optional[str] = None, metric: Optional[str] = None, date_pattern: Optional[str] = None) Union[List[dict], str]

Get information about published files. Without any arguments server will return all measurements collected from all nodes in the last one hour.

Parameters
  • source (Optional[str]) – Specify the node you want to query. If not specified, then all nodes will be used. (Example: myagent:8811)

  • period (Optional[str]) – Specify the time range you want to query. by default, period is LAST_HOUR, this param can be one of: LAST_HOUR, LAST_2_HOURS, LAST_4_HOURS, LAST_DAY, LAST_WEEK, LAST_MONTH.

  • start_time (Optional[str]) – Specify the start time you want to query. If not specified, then an hour ago of to_date will be used.

  • end_time (Optional[str]) – Specify the end time you want to query. If not specified, then current time will be used.

  • metric (Optional[str]) –

    Specify the metric name you want to query. See below section for all available metric names. (Example: disk.usage)

    Available measurement metrics: https://wiki.pmease.com/display/QB10/Query+Grid+Measurements

  • date_pattern (Optional[str]) – Specify the date pattern you are using for from_date and to_date. By default, ISO 8601 is used.

Returns

list of measurements.

Return type

Union[List[dict], str]

get_version() str

Get current version for the measurements related REST API.

Returns

measurements version.

Return type

str

Memberships

class quickbuild.endpoints.memberships.Memberships(quickbuild)
get() List[dict]

Get all memberships in the system.

Returns

list of all memberships.

Return type

List[dict]

get_info(membership_id: int, *, content_type: Optional[quickbuild.helpers.ContentType] = None) Union[dict, str]

Get full membership info.

Parameters
  • membership_id (int) – Membership identifier.

  • content_type (Optional[ContentType]) – Select needed content type if not set, default value of client instance is used.

Returns

membership content.

Return type

Union[str, dict]

get_by_user(user_id: int) Union[List[dict], str]

Get memberships of particular user.

Parameters

user_id (int) – user identifier.

Returns

user membership content.

Return type

Union[List[dict], str]

get_by_group(group_id: int) Union[List[dict], str]

Get memberships of particular group.

Parameters

group_id (int) – group identifier.

Returns

group membership content.

Return type

Union[List[dict], str]

update(configuration: str) int

Update membership using XML/JSON representation of the membership.

Normally you do not need to create the representation from scratch, you may retrieve XML/JSON representation of the membership using get_info() method, modify certain parts and use it as new representation for update.

  1. Assume id of user robin is 2, id of group developer is 1, and id of group tester is 2.

  2. Get memberships of user robin using get_by_user(2) method.

  3. Analyze response of above command to find out the membership with group id.

  4. Modify response and change the group element to use value of 2.

  5. Use it as new membership membership to this update() method.

Parameters

representation (str) – representation of membership.

Returns

membership id being updated.

Return type

int

create(configuration: str) int

Create membership using XML/JSON representation of the membership.

Normally you do not need to create the representation from scratch, you may retrieve XML/JSON representation of the membership using get_info() method, modify certain parts and use it as new representation for create.

How to add user robin (assume id is 2) to group tester (assume the id is 3).

Parameters

representation (str) – representation of membership.

Returns

newly created membership id.

Return type

int

delete(membership_id: int) None

Delete membership.

  1. User robin (assume id is 2) from group tester (assume the id is 3).

  2. Get memberships of user robin with get_by_user(2)

  3. Analyze response of above command to find out id of the membership associated with group id 3, assume id of the found membership is 100.

  4. Delete the found membership id 100.

Parameters

membership_id (str) – membership identifier.

Requests

class quickbuild.endpoints.requests.Requests(quickbuild)

Build request object can be used to request new build or cancel running build.

get(*, configuration_id: Optional[int] = None, trigger_user_id: Optional[int] = None) List[dict]

Get build info as raw XML string.

Parameters
  • configuration_id (Optional[int]) – Identifier of a configuration to filter on, if missing, QB will return all build requests in the system.

  • trigger_user_id (Optional[int]) – Identifier of the user triggering the request to filter on, if this param is missing, QB will return build requests triggered by all users in the system.

Returns

list of build requests.

Return type

List[dict]

create(configuration: str) dict

New build can be requested by posting XML representation of the build request object.

Parameters

configuration (str) – XML of build request object.

Returns

content is XML representation of request result including the generated build request id.

Return type

dict

Raises

QBProcessingError – will be raised if the request is aggregated.

trigger(configuration_id: int) dict

Since QuickBuild 6.0.14, one can also trigger new build.

Parameters

configuration_id (int) – Identifier of a configuration.

Returns

content is XML representation of request result including the generated build request id.

Return type

dict

Raises

QBProcessingError – will be raised if the request is aggregated.

delete(request_id: str) None

Delete existing build request. If the build associated with the build request is already running, it will be forcibly stopped.

Parameters

request_id (str) – Identifier of a build request.

Shares

class quickbuild.endpoints.shares.Shares(quickbuild)

Share is the object used to control dashboard sharing with users or groups.

System

class quickbuild.endpoints.system.System(quickbuild)
get_version() quickbuild.endpoints.system.ServerVersion

Show server version information.

Returns

NamedTuple with major, minor and patch version.

Return type

ServerVersion

pause() None

Pause system.

Raises

QBError – system has not paused.

resume() None

Resume system.

Raises

QBError – system has not resumed.

get_pause_information() str

Get system pause information including pause reason.

Returns

pause information.

Return type

str

Raises

QBProcessingError – will be raised if system is not paused.

backup(configuration: str) str

Backup database using XML configuration.

Parameters

configuration (str) – XML document.

Returns

Absolute path to the backup file.

Return type

str

Tokens

class quickbuild.endpoints.tokens.Tokens(quickbuild)

By operating tokens, one can authorize/unauthorize agents, or access agent details including token value and latest usage information.

get(agent_address: Optional[str] = None) List[dict]

Get token value and latest used information of agents.

Parameters

agent_address (Optional[str]) – Build agent address, eg. my-agent:8811. If param address is set to None, details of all agents will be returned.

Returns

List of token and agent details

Return type

List[dict]

authorize(agent_ip: str, agent_port: Optional[int] = 8811) str

Authorize a build agent to join the build grid.

Parameters
  • agent_ip (str) – The build agent IP address.

  • agent_port (Optional[int]) – The build agent port (default: 8811).

Returns

identifier of the newly created token for the build agent

Return type

str

unauthorize(agent_ip: str, agent_port: Optional[int] = 8811) str

Unauthorize an already authorized build agent.

Parameters
  • agent_ip (str) – The build agent IP address.

  • agent_port (Optional[int]) – The build agent port (default: 8811).

Returns

identifier of the removed token representing the build agent.

Return type

str

Users

class quickbuild.endpoints.users.Users(quickbuild)
get() List[dict]

Get all users in the system.

Returns

list of users.

Return type

List[dict]

get_info(user_id: int, *, content_type: Optional[quickbuild.helpers.ContentType] = None) Union[dict, str]

Get information about specified user.

Parameters
  • user_id (int) – User identifier.

  • content_type (Optional[ContentType]) – Select needed content type if not set, default value of client instance is used.

Returns

information about user.

Return type

dict

get_display_name(user_id: int) str

Get display name for specified user.

Parameters

user_id (int) – user identifier.

Returns

user name.

Return type

str

get_id_by_name(name: str) int

Get user id by name.

Parameters

name (str) – user name.

Returns

user identifier.

Return type

int

Raises

QBProcessingError – will be raised if resource is not found.

update(configuration: str) int

Update user using XML configuration.

Normally you do not need to create the xml from scratch: you may retrieve XML representation of the user using get_info() method, modify certain parts of the XML and post back to above url.

Parameters

configuration (str) – XML document.

Returns

user id being updated.

Return type

int

create(configuration: str) int

Create a new user using XML/JSON configuration.

Normally you do not need to create the XML from scratch: you may retrieve XML representation of a templating user using get_info(), remove the id element, modify certain parts and use it.

Parameters

configuration (str) – XML/JSON document.

Returns

id of the newly created user.

Return type

int

Raises

QBError – configuration validation error.

delete(user_id: int) None

Delete user by user id.

Parameters

user_id (int) – user identifier.

Returns

None

Exceptions

exception quickbuild.exceptions.QBError

Core library exception

exception quickbuild.exceptions.QBProcessingError

Raises when request return HTTP code 204 (no content)

exception quickbuild.exceptions.QBForbiddenError

Raises when request return HTTP code 403 (forbidden)

exception quickbuild.exceptions.QBNotFoundError

Raises when request return HTTP code 404 (not found)

exception quickbuild.exceptions.QBServerError

Raises when request return HTTP code 500 (server error)