Python client for PMEase QuickBuild¶
Package supports sync and async syntax with same code base.
from quickbuild import AsyncQBClient, QBClient
Documentation¶
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: str | None = None, password: str | None = None, *, content_type: ContentType = ContentType.PARSE, verify: bool = True, timeout: float | None = None, retry: dict | None = None, auth_update_callback: Callable[[], Tuple[str, str]] | None = 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))
- factor:
statuses:
List[int]
HTTP statues retries on. (default [])- methods:
List[str]
list of HTTP methods to retry, idempotent methods are used by default.
- methods:
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: str | None = None, password: str | None = None, *, content_type: ContentType = ContentType.PARSE, verify: bool = True, timeout: float | None = None, retry: dict | None = None, auth_update_callback: Callable[[], Awaitable[Tuple[str, str]]] | None = 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))
- factor:
statuses:
List[int]
HTTP statues retries on. (default [])- methods:
List[str]
list of HTTP methods to retry, idempotent methods are used by default.
- methods:
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)
- body¶
Alias for field number 2
- headers¶
Alias for field number 1
- status¶
Alias for field number 0
- class quickbuild.core.QuickBuild(content_type: ContentType | None)¶
NB: somehow using -H Accept: application/json,application/xml,*/* leads to server error.
Agents¶
- class quickbuild.endpoints.agents.Agents(quickbuild)¶
- get_active() List[dict] | str ¶
Get list of active build agents.
- Returns:
list of active build agents.
- Return type:
List[dict]
- get_inactive() List[dict] | str ¶
Get list of inactive build agents.
- Returns:
list of inactive build agents.
- Return type:
List[dict]
- get_unauthorized() 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) 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: str | None = None, source: str | None = None, action: str | None = None, since: str | None = None, until: str | None = None, first: int | None = 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: ContentType | None = None) 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: int | None = None) 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: int | None = None, recursive: bool | None = False, from_date: str | None = None, to_date: str | None = None, version: str | None = None, status: str | None = None, user_id: int | None = None, master_node: str | None = None, promoted_from_id: int | None = None, request_id: int | None = None, first: int | None = 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: int | None = None, recursive: bool | None = False, from_date: str | None = None, to_date: str | None = None, version: str | None = None, status: str | None = None, user_id: int | None = None, promoted_from_id: int | None = None, request_id: int | None = 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: int | None = None, from_build: int | None = None, to_build: int | None = None, from_date: str | None = None, to_date: str | None = None, date_pattern: str | None = None, repository: str | None = None, committer: str | None = 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: int | None = None, from_build: int | None = None, to_build: int | None = None, date_pattern: str | None = None, from_date: str | None = None, to_date: str | None = None, repository: int | None = None, committer: int | None = None, offset: int | None = None, limit: int | None = None, asc: bool | None = 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: ContentType | None = None) 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: date | None = None, to_date: date | None = 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: date | None = None, to_date: date | None = 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: ContentType | None = None) 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: ContentType | None = None) 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: str | None = None, period: str | None = None, start_time: str | None = None, end_time: str | None = None, metric: str | None = None, date_pattern: str | None = None) 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: ContentType | None = None) 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) 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) 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: ContentType | None = None) 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: int | None = None, trigger_user_id: int | None = 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
System¶
- class quickbuild.endpoints.system.System(quickbuild)¶
- get_version() ServerVersion ¶
Show server version information.
- Returns:
major, minor, patch version and qualifier.
- Return type:
ServerVersion
- 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: str | None = 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: ContentType | None = None) 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)