Python client for PMEase QuickBuild ¶

Coverage status Version status Downloads status

Package supports sync and async syntax with same code base.

from quickbuild import AsyncQBClient, QBClient

Documentation¶

Package Read the Docs

Official REST API documentation

Available REST API Clients

Installation¶

pip3 install quickbuild

Examples¶

Get server version:

from quickbuild import QBClient

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

Get server version in async way (be careful AsyncQBClient must be called inside async function):

import asyncio
from quickbuild import AsyncQBClient

async def main():
    client = AsyncQBClient('https://server', 'user', 'password')
    version = await client.system.get_version()
    print(version)
    await client.close()

asyncio.run(main())

Stop build:

from quickbuild import QBClient

client = QBClient('https://server', 'user', 'password')
client.builds.stop(123)

Update credentials handler:

import asyncio
import aiohttp
from quickbuild import AsyncQBClient

async def get_credentials():
    async with aiohttp.ClientSession() as session:
        async with session.get('...') as resp:
            response = await resp.json()
            return response['user'], response['password']

async def main():
    client = AsyncQBClient('http://server', 'user', 'password',
                            auth_update_callback=get_credentials)

    # let's suppose credentials are valid now
    print(await client.builds.get_status(12345))

    # now, after some time, password of user somehow changed, so our callback
    # will be called, new credentials will be using for retry and future here
    # we get also correct build info instead of QBUnauthorizedError exception
    print(await client.builds.get_status(12345))

    await client.close()

asyncio.run(main())

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 three types of content were indtoduced, this type and behavior 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: ContentType = ContentType.PARSE, verify: bool = True, timeout: Optional[float] = None, retry: Optional[dict] = None, auth_update_callback: Optional[Callable[[], Tuple[str, str]]] = None)¶

QuickBuild client class.

Parameters

url (str) – URL of QuickBuild server.
user (Optional[str]) – User name.
password (Optional[str]) – Password for user.
verify (Optional[bool]) – Verify SSL (default: true).
content_type (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 [])
methods: List[str] list of HTTP methods to retry, idempotent
methods are used by 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

auth_update_callback (Optional[Callable[[], Tuple[str, str]]]) – Callback function which will be called on QBUnauthorizedError to update user and password and retry request again.

Returns

Client instance

close() → None¶: Close client session

class quickbuild.AsyncQBClient(url: str, user: Optional[str] = None, password: Optional[str] = None, *, content_type: ContentType = ContentType.PARSE, verify: bool = True, timeout: Optional[float] = None, retry: Optional[dict] = None, auth_update_callback: Optional[Callable[[], Awaitable[Tuple[str, str]]]] = None)¶

QuickBuild async client class.

Parameters

url (str) – URL of QuickBuild server, must include API version.
user (Optional[str]) – User name.
password (Optional[str]) – Password for user.
content_type (ContentType) – How to process server content, get native XML as string, or parsing XML to Python types, or uses native JSON if QB10+ used.
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 [])
- methods: List[str] list of HTTP methods to retry, idempotent
  methods are used by default.
Example:
```
retry = dict(
    total=10,
    factor=1,
    statuses=[500]
)
```
auth_update_callback (Optional[Callable[[], Tuple[str, str]]) – Callback coroutine which will be called on QBUnauthorizedError to update user and password and retry request again.

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[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.

Note

This feature is available since QuickBuild 5.1.24

Parameters: node_address (str) – Address of target node.
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

Authorizations¶

class quickbuild.endpoints.authorizations.Authorizations(quickbuild)¶

get() → List[dict]¶

Get all authorizations in the system.

Returns: list of all authorizations in the system.
Return type: List[dict]

get_info(authorization_id: int, *, content_type: Optional[ContentType] = None) → Union[dict, str]¶

Get authorization info by id.

Parameters

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

Returns

authorization info.

Return type

Union[dict, str]

get_by_group(group_id: int) → dict¶

Get authorization info by group id.

Parameters: group_id (int) – Group identifier.
Returns: authorization info.
Return type: dict

get_by_configuration(configuration_id: int) → dict¶

Get authorization info by configuration_id.

Parameters: configuration_id (int) – Configuration identifier.
Returns: authorization info.
Return type: dict

update(configuration: str) → int¶

Update an authorization using XML configuration.

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

Parameters: configuration (str) – XML document.
Returns: authorization id being updated.
Return type: int

create(configuration: str) → int¶

Create an authorization using XML/JSON configuration.

Please note that: posted XML should NOT contain the id element; otherwise QuickBuild will treat the post as an updating to the authorization with that id. Normally you do not need to create the XML from scratch: you may retrieve XML representation of a templating authorization using http GET method, remove the id element, modify certain parts and post back to above url.

Parameters: configuration (str) – XML/JSON document.
Returns: newly created authorizations id.
Return type: int
Raises: QBError – XML validation error

delete(configuration_id: int) → None¶

Delete authorization by configuration_id.

Parameters: configuration_id (int) – Configuration identifier.
Returns: None

Builds¶

class quickbuild.endpoints.builds.Builds(quickbuild)¶

get_info(build_id: int, *, content_type: Optional[ContentType] = None) → Union[dict, str]¶

Get build info as raw XML string.

Parameters

build_id (int) – Build identifier.
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 identifier.
Returns: Build status, for example: SUCCESS
Return type: str

get_begin_date(build_id: int) → datetime¶

Get build begin date.

Parameters: build_id (int) – Build identifier.
Returns: return datetime from stdlib.
Return type: datetime

get_version(build_id: int) → str¶

Get build version.

Parameters: build_id (int) – Build identifier.
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 identifier.
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 identifier.
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 identifier.
Returns: builds steps as XML document
Return type: str

get_repositories(build_id: int) → str¶

Get build repositories.

Parameters: build_id (int) – Build identifier.
Returns: builds repositories as XML document
Return type: str

get_dependencies(build_id: int) → str¶

Get build dependencies.

Parameters: build_id (int) – Build identifier.
Returns: builds dependencies as XML document
Return type: str

get_dependents(build_id: int) → str¶

Get build dependents.

Parameters: build_id (int) – Build identifier.
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. This service simply deletes the build object in database, and is different from build cancellation. You may follow below steps to cancel a running build:

Get build request id using get_request_id()
Delete the build request with build request id if it is not empty using requests.delete()

Or using stop() which wraps above calls.

Parameters: build_id (int) – Build identifier.
Returns: None

stop(build_id: int) → None¶

Stop build, it’s just wrapper for two calls.

Parameters: build_id (int) – Build identifier.
Returns: None

Changes¶

class quickbuild.endpoints.changes.Changes(quickbuild)¶

https://wiki.pmease.com/display/QB10/Interact+with+Changes

Data structure of the changes:

In QuickBuild, we use Changeset and Modification to represent a SCM commit. A changeset is an atomic collection of changes to files in a repository and it usually contains several modifications. A modification means developer made a specific action to a file when committed to a repository.

In QuickBuild, the actions include: * ADD * MODIFY * DELETE

The action in some SCM, for example, git, mercurial, have more actions, like rename, in QuickBuild, it will be speared into two actions, i.e. DELETE first, and then ADD, and maybe there are also other actions, QuickBuild will use MODIFY action to represent.

get_version() → str¶

Get the data version of changes.

Returns: changes version.
Return type: str

get_commit_stats(configuration: str, *, build: Optional[int] = None, from_build: Optional[int] = None, to_build: Optional[int] = None, from_date: Optional[str] = None, to_date: Optional[str] = None, date_pattern: Optional[str] = None, repository: Optional[str] = None, committer: Optional[str] = None) → dict¶

Get the commit stats

Parameters

configuration (str) – Specify the configuration. By default, specify configuration id here, also, you can specify the configuration path directly.
build (Optional[int]) – Specify the build id you want.
from_build (Optional[int]) – Specify the from build when finding changes in a build range.
to_build (Optional[int]) – Specify the to build when finding changes in a build range.
from_date (Optional[str]) – Specify the from date when finding changes in a build range.
to_date (Optional[str]) – Specify the to date when finding changes in a build range.
date_pattern (Optional[str]) –
Specify the date pattern when query by a date range, by default the pattern is yyyyMMdd. Valid date pattern can be found here

https://docs.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html
repository (Optional[str]) – Get the changes only in a specific repository.
committer (Optional[str]) – Get the changes only committed by a specified committer

Returns

commit stats

Return type

dict

get_changesets(configuration: str, *, build: Optional[int] = None, from_build: Optional[int] = None, to_build: Optional[int] = None, date_pattern: Optional[str] = None, from_date: Optional[str] = None, to_date: Optional[str] = None, repository: Optional[int] = None, committer: Optional[int] = None, offset: Optional[int] = None, limit: Optional[int] = None, asc: Optional[bool] = None) → List[dict]¶

Get changesets.

Parameters

configuration (str) – Specify the configuration. By default, specify configuration id here, also, you can specify the configuration path directly.
build (Optional[int]) – Specify the build id you want.
from_build (Optional[int]) – Specify the from build when finding changes in a build range, must be specified with to_build.
to_build (Optional[int]) – Specify the to build when finding changes in a build range, must be specified with from_build.
date_pattern (Optional[str]) –
Specify the date pattern when query by a date range, by default the pattern is yyyyMMdd. Valid date pattern can be found here

https://docs.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html
from_date (Optional[str]) – Specify the from date when finding changes in a build range.
to_date (Optional[str]) – Specify the to date when finding changes in a build range.
repository (Optional[int]) – Get the changes only in a specific repository.
committer (Optional[int]) – Get the changes only committed by the specified committer.
offset (Optional[int]) – Specify the first record when iterate the records, by default, the offset is 0.
limit (Optional[int]) – Specify the number of total records you want to retrieve, by default, the limit is 50.
asc (Optional[bool]) – Boolean type, specify the order by commit date ascendent or descendent, by default, it is descendent.

Returns

changesets list.

Return type

List[dict]

get_build_commits_changesets(build_id: int) → List[dict]¶

Get the changesets of the build_id lively.

Most of the aforementioned APIs are only callable when build finish. Sometimes, you may want to query the changesets during the build is still running.

Parameters: build_id (int) – Build id.
Returns: changesets list.
Return type: List[dict]

get_build_stats_changesets(build_id: int) → List[dict]¶

Get the stats of the changesets of the build_id lively.

Most of the aforementioned APIs are only callable when build finish. Sometimes, you may want to query the changesets during the build is still running.

Parameters: build_id (int) – Build id.
Returns: changesets list.
Return type: List[dict]

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[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 info.

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[date] = None, to_date: Optional[date] = None) → int¶

Get configuration average duration.

Parameters

configuration_id (int) – Configuration identifier.
from_date (Optiona[datetime.date]) – Date from search starts.
to_date (Optiona[datetime.date]) – Date where search ends.

Returns

milliseconds of average build duration.

Return type

int

get_success_rate(configuration_id: int, *, from_date: Optional[date] = None, to_date: Optional[date] = None) → int¶

Get configuration success rate.

Parameters

configuration_id (int) – Configuration identifier.
from_date (Optiona[datetime.date]) – Date from search starts.
to_date (Optiona[datetime.date]) – Date where search ends.

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 a 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.

Note

This feature is available since QuickBuild 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[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) – 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[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

Union[dict, str]

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.

Note

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) – Fully qualified name.
Returns: dashboard identifier.
Return type: int
Raises: QBProcessingError – will be raised if resource is not found.

Issues¶

class quickbuild.endpoints.issues.Issues(quickbuild)¶

https://wiki.pmease.com/display/QB10/Interact+with+Issues

get_tracker(name: str) → Tracker¶

Since QuickBuild 4.0, you can retrieve issues via RESTful APIs. The base URI for changes RESTful APIs is: /rest/{tracker}

Here, tracker is the type of your issue tracker in QuickBuild:

Jira - /rest/jira
Trac - /rest/trac
Bugzilla - /rest/bugzilla

Returns: Tracker instance
Return type: Tracker

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[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.

Example:

Assume id of user robin is 2, id of group developer is 1, and id of group tester is 2.
Get memberships of user robin using get_by_user(2) method.
Analyze response of above command to find out the membership with group id.
Modify response and change the group element to use value of 2.
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.

Example:

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

<com.pmease.quickbuild.model.Membership>
  <user>2</user>
  <group>3</group>
</com.pmease.quickbuild.model.Membership>

Parameters: representation (str) – Representation of a membership.
Returns: newly created membership id.
Return type: int

delete(membership_id: int) → None¶

Delete membership.

Example:

User robin (assume id is 2) from group tester (assume the id is 3).
Get memberships of user robin with get_by_user(2)
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.
Delete the found membership id 100.

Parameters: membership_id (str) – membership identifier.

Retruns:: None

Nodes¶

class quickbuild.endpoints.nodes.Nodes(quickbuild)¶

Interact with attributes of grid node.

https://wiki.pmease.com/display/QB10/Get+and+Set+User+Attributes+of+Grid+Node https://wiki.pmease.com/display/QB10/Get+System+Attributes+of+Grid+Node

get_user_attributes(name: str) → dict¶

Get user attributes of grid node.

Note

This feature is available since QuickBuild 5.0.26

Parameters: name (str) – Node name.
Returns: attributes
Return type: dict

set_user_attributes(name: str, data: str) → None¶

Set user attributes of grid node.

Note

This feature is available since QuickBuild 5.0.26

Parameters

name (str) – Node name.
group_id (int) – Group identifier.

Returns

None

get_system_attributes(name: str) → dict¶

Get system attributes of grid node.

Note

This feature is available since QuickBuild 5.1.22

Parameters: name (str) – Node name.
Returns: attributes
Return type: dict

Profiles¶

class quickbuild.endpoints.profiles.Profiles(quickbuild)¶

get() → List[dict]¶

Get all cloud profiles in the system.

Returns: list of users.
Return type: List[dict]

get_info(cloud_profile_id: int, *, content_type: Optional[ContentType] = None) → Union[dict, str]¶

Get information about cloud profile.

Parameters

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

Returns

information cloud profile.

Return type

Union[dict, str]

update(configuration: str) → int¶

Update a cloud profile 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: cloud profile id being updated.
Return type: int

create(configuration: str) → int¶

Create a cloud profile using XML/JSON configuration.

Please note that:

The posted XML should NOT contain the id element; otherwise, QuickBuild will treat the post as an updating to the cloud profile with that id. Normally you do not need to create the XML from scratch: you may retrieve XML representation of a templating cloud profile using get_info() method, remove the id element, modify certain parts and post back to above url.

Parameters: configuration (str) – XML/JSON document.
Returns: id of newly created cloud profile.
Return type: int
Raises: QBError – XML validation error

delete(cloud_profile_id: int) → None¶

Delete cloud profile.

Parameters: cloud_profile_id (int) – Cloud profile id.
Returns: None

Reports¶

class quickbuild.endpoints.reports.Reports(quickbuild)¶

https://wiki.pmease.com/display/QB10/Interact+with+Reports

get_tracker(name: str) → Tracker¶

Here, tracker is the type of your reports tracker in QuickBuild:

Parameters: name (str) – report tracker name, examples table below.

Report category	Name
Build Stats	buildstats
SCM Changes	changes
CheckStyle	checkstyle
Cobertura	cobertura
JaCoCo	jacoco
CPD	cpd
EMMA	emma
FindBugs	findbugs
Fxcop	fxcop
JUnit	junit
MBUnit	mbunit
MSTest	mstest
NCover	ncover
NUnit	nunit
PMD	pmd
TestNG	testng
Boost Test	boost

Returns: Tracker instance
Return type: Tracker

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.

Resources¶

class quickbuild.endpoints.resources.Resources(quickbuild)¶

get() → List[dict]¶

Get all resources in the system.

Returns: list of resources.
Return type: List[dict]

get_by_id(resource_id: int) → dict¶

Get resource by identifier.

Parameters: resource_id (int) – Identifier of a resources.
Returns: resource.
Return type: dict

get_total_count(resource_id: int) → int¶

Get total resource count across nodes.

Parameters: resource_id (int) – Identifier of a resources.
Returns: total resources count.
Return type: int

get_available_count(resource_id: int) → int¶

Get available resource count across nodes.

Parameters: resource_id (int) – Identifier of a resources.
Returns: total resources count.
Return type: int

update(configuration: str) → int¶

Update resource.

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

Parameters: configuration (str) – Resource configuration.
Returns: resource id being updated.
Return type: int

create(configuration: str) → int¶

Create resource.

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

Normally you do not need to create the configuration from scratch: you may retrieve configuration representation of a templating resource using get_*() methods, remove the id element, modify certain parts and use it as new configuration.

Parameters: configuration (str) – Resource configuration.
Returns: resource id being created.
Return type: int

delete(resource_id: int) → None¶

Delete resource.

Parameters: resource_id (int) – Identifier of a resources.
Returns: None

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() → ServerVersion¶

Show server version information.

Returns: major, minor, patch version and qualifier.
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: int = 8811) → str¶

Authorize a build agent to join the build grid.

Parameters

agent_ip (str) – The build agent IP address.
agent_port (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: int = 8811) → str¶

Unauthorize an already authorized build agent.

Parameters

agent_ip (str) – The build agent IP address.
agent_port (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[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

Union[dict, str]

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.QBUnauthorizedError¶: Raises when request return HTTP code 401 (unauthorized)

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)

Python client for PMEase QuickBuild ¶

Documentation¶

Installation¶

Examples¶

Content type¶

Development¶

Testing¶

Contributing¶

API endpoints¶

Core¶

Agents¶

Audits¶

Authorizations¶

Builds¶

Changes¶

Configurations¶

Dashboards¶

Groups¶

Identifiers¶

Issues¶

Measurements¶

Memberships¶

Nodes¶

Profiles¶

Reports¶

Requests¶

Resources¶

Shares¶

System¶

Tokens¶

Users¶

Exceptions¶

Home page

Navigation

Python client for PMEase QuickBuild¶

Documentation¶

Installation¶

Examples¶

Content type¶

Development¶

Testing¶

Contributing¶

API endpoints¶

Core¶

Agents¶

Audits¶

Authorizations¶

Builds¶

Changes¶

Configurations¶

Dashboards¶

Groups¶

Identifiers¶

Issues¶

Measurements¶

Memberships¶

Nodes¶

Profiles¶

Reports¶

Requests¶

Resources¶

Shares¶

System¶

Tokens¶

Users¶

Exceptions¶

Python client for PMEase QuickBuild ¶