Python client for QuickBuild

Status

Build status Docs status Coverage status Version status Downloads status

Documentation

Read the Docs

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()

Development

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

Build locally:

docker build . -t quickbuild:10
docker run -d -p 8810:8810 quickbuild:10

Or using existed images:

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 contributions

API endpoints

Core

class quickbuild.QBClient(url: str, user: Optional[str] = None, password: Optional[str] = None, *, 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).

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

  • retry (Optional[dict]) –

    Retry options to prevent failures if server restarting or temporary network problem.

    • total: int Total retries count. (default 0)

    • factor: int Sleep between retries (default 0)

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

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

    Example:

    retry = dict(
        attempts=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, *, 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.

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

    • total: int Total retries count. (default 0)

    • factor: int Sleep between retries (default 0)

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

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

    Example:

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

Returns

AsyncClient instance

async close()None

Close client session

class quickbuild.core.Response(status, body)

Create new instance of Response(status, body)

property body

Alias for field number 1

property status

Alias for field number 0

class quickbuild.core.QuickBuild

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, as_xml: Optional[bool] = False)Union[dict, str]

Get build info as raw XML string.

Parameters
  • build_id (int) – build id.

  • as_xml (Optional[bool]) – By default returns dict representation of a build, original XML representation might be usefull to update or create new build.

Returns

build information.

Return type

dict

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_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

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

Please note that: - The posted xml should NOT contain the id element; otherwise, QuickBuild

will treat the post as an updating to the build with that id.

  • 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, remove the id element, modify certain parts and post back to above url.

Parameters

configuration (str) – XML document.

Returns

build id of the the newly created build.

Return type

int

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, as_xml: Optional[bool] = False)Union[dict, str]

Get full configuration info.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration content.

Return type

Union[str, dict]

get_path(configuration_id: int)str

Get configuration path.

Parameters

configuration_id (int) – configuration identifier.

Returns

configuration path.

Return type

str

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

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, as_xml: Optional[bool] = False)Union[dict, str]

Get information about specified group.

Parameters

group_id (int) – group identifier.

Returns

group information.

Return type

dict

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

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

Parameters

configuration (str) – XML document.

Returns

group id being created.

Return type

int

delete(group_id: int)None

Delete specified group.

Parameters

group_id (int) – group identifier.

Returns

group id being created.

Return type

int

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.

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 – if system haven`t paused.

resume()None

Resumed system.

Raises

QBError – if system haven`t resumed.

get_pause_information()None

Get system pause information including pause reason.

Returns

NamedTuple with major, minor and patch version.

Return type

ServerVersion

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, as_xml: Optional[bool] = False)Union[dict, str]

Get information about specified user.

Parameters

user_id (int) – user identifier.

Returns

information about user.

Return type

dict

get_display_name(user_id: int)str

Get display name for specified user.

Returns

user name.

Return type

str

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

Please note that the posted XML should NOT contain the id element; otherwise, QuickBuild will treat the post as an update to the user with that id. 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 post back to above url.

Parameters

configuration (str) – XML document.

Returns

id of the newly created user.

Return type

int

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)