Client¶
- class rtcclient.client.RTCClient(url, username, password, email=None, proxies=None, searchpath=None, ends_with_jazz=True, verify: bool | str = False, old_rtc_authentication=False, **kwargs)[source]¶
A wrapped class for
RTC Client
to perform all related operations- Parameters:
url – the rtc url (e.g. https://your_domain:9443/jazz)
username – the rtc username
password – the rtc password
proxies – (optional) Dictionary mapping protocol to the URL of the proxy.
searchpath – (optional) the folder to store your templates. If None, the default search path (/your/site-packages/rtcclient/templates) will be loaded.
ends_with_jazz (bool) – (optional but important) Set to True (default) if the url ends with ‘jazz’, otherwise to False if with ‘ccm’ (Refer to issue #68 for details)
Tips: You can also customize your preferred properties to be returned by specified returned_properties when the called methods have this optional parameter, which can also GREATLY IMPROVE the performance of this client especially when getting or querying lots of workitems.
Important Note: returned_properties is an advanced parameter, the returned properties can be found in ClassInstance.field_alias.values(), e.g. myworkitem1.field_alias.values(). If you don’t care the performance, just leave it alone with None.
- checkProjectAreaID(projectarea_id, archived=False)[source]¶
Check the validity of
rtcclient.project_area.ProjectArea
id- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idarchived – (default is False) whether the project area is archived
- Returns:
True or False
- Return type:
- checkType(item_type, projectarea_id)[source]¶
Check the validity of
rtcclient.workitem.Workitem
type- Parameters:
item_type – the type of the workitem (e.g. Story/Defect/Epic)
projectarea_id – the
rtcclient.project_area.ProjectArea
id
- Returns:
True or False
- Return type:
- copyWorkitem(copied_from, title=None, description=None, prefix=None)[source]¶
Create a workitem by copying from an existing one
- Parameters:
copied_from – the to-be-copied workitem id
title – the new workitem title/summary. If None, will copy that from a to-be-copied workitem
description – the new workitem description. If None, will copy that from a to-be-copied workitem
prefix – used to add a prefix to the copied title and description
- Returns:
the
rtcclient.workitem.Workitem
object- Return type:
- createWorkitem(item_type, title, description=None, projectarea_id=None, projectarea_name=None, template=None, copied_from=None, keep=False, **kwargs)[source]¶
Create a workitem
- Parameters:
item_type – the type of the workitem (e.g. task/defect/issue)
title – the title of the new created workitem
description – the description of the new created workitem
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
template – The template to render. The template is actually a file, which is usually generated by
rtcclient.template.Templater.getTemplate
and can also be modified by user accordingly.copied_from – the to-be-copied workitem id
keep – refer to keep in
rtcclient.template.Templater.getTemplate
. Only works when template is not specifiedkwargs – Optional/mandatory arguments when creating a new workitem. More details, please refer to kwargs in
rtcclient.template.Templater.render
- Returns:
the
rtcclient.workitem.Workitem
object- Return type:
- getFiledAgainst(filedagainst_name, projectarea_id=None, projectarea_name=None, archived=False)[source]¶
Get
rtcclient.models.FiledAgainst
object by its name- Parameters:
filedagainst_name – the filedagainst name
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the filedagainst is archived
- Returns:
the
rtcclient.models.FiledAgainst
object- Return type:
- getFiledAgainsts(projectarea_id=None, projectarea_name=None, archived=False)[source]¶
Get all
rtcclient.models.FiledAgainst
objects by project area id or nameIf both projectarea_id and projectarea_name are None, all the filedagainsts in all project areas will be returned.
If no
rtcclient.models.FiledAgainst
objects are retrieved, None is returned.- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the filedagainsts are archived
- Returns:
a
list
that contains all thertcclient.models.FiledAgainst
objects- Return type:
- getFoundIn(foundin_name, projectarea_id=None, projectarea_name=None, archived=False)[source]¶
Get
rtcclient.models.FoundIn
object by its name- Parameters:
foundin_name – the foundin name
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the foundin is archived
- Returns:
the
rtcclient.models.FoundIn
object- Return type:
- getFoundIns(projectarea_id=None, projectarea_name=None, archived=False)[source]¶
Get all
rtcclient.models.FoundIn
objects by project area id or nameIf both projectarea_id and projectarea_name are None, all the foundins in all project areas will be returned.
If no
rtcclient.models.FoundIn
objects are retrieved, None is returned.- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the foundins are archived
- Returns:
a
list
that contains all thertcclient.models.FoundIn
objects- Return type:
- getPlannedFor(plannedfor_name, projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]¶
Get
rtcclient.models.PlannedFor
object by its name- Parameters:
plannedfor_name – the plannedfor name
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the plannedfor is archived
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanations
- Returns:
the
rtcclient.models.PlannedFor
object- Return type:
- getPlannedFors(projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]¶
Get all
rtcclient.models.PlannedFor
objects by project area id or nameIf both projectarea_id and projectarea_name are None, all the plannedfors in all project areas will be returned.
If no
rtcclient.models.PlannedFor
objecs are retrieved, None is returned.- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the plannedfors are archived
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanations
- Returns:
a
list
that contains all thertcclient.models.PlannedFor
objects- Return type:
- getPriorities(projectarea_id=None, projectarea_name=None)[source]¶
Get all
rtcclient.models.Priority
objects by project area id or nameAt least either of projectarea_id and projectarea_name is given.
If no
rtcclient.models.Priority
is retrieved, None is returned.- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
- Returns:
a
list
contains all thertcclient.models.Priority
objects- Return type:
- getPriority(priority_name, projectarea_id=None, projectarea_name=None)[source]¶
Get
rtcclient.models.Priority
object by its nameAt least either of projectarea_id and projectarea_name is given
- Parameters:
priority_name – the priority name
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
- Returns:
the
rtcclient.models.Priority
object- Return type:
- getProjectArea(projectarea_name, archived=False, returned_properties=None)[source]¶
Get
rtcclient.project_area.ProjectArea
object by its name- Parameters:
projectarea_name – the project area name
archived – (default is False) whether the project area is archived
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanations
- Returns:
the
rtcclient.project_area.ProjectArea
object- Return type:
- getProjectAreaByID(projectarea_id, archived=False, returned_properties=None)[source]¶
Get
rtcclient.project_area.ProjectArea
object by its id- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idarchived – (default is False) whether the project area is archived
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanations
- Returns:
the
rtcclient.project_area.ProjectArea
object- Return type:
- getProjectAreaID(projectarea_name, archived=False)[source]¶
Get
rtcclient.project_area.ProjectArea
id by its name- Parameters:
projectarea_name – the project area name
archived – (default is False) whether the project area is archived
- Returns:
the
string
object- Return type:
string
- getProjectAreaIDs(projectarea_name=None, archived=False)[source]¶
Get all
rtcclient.project_area.ProjectArea
id(s) by project area nameIf projectarea_name is None, all the
rtcclient.project_area.ProjectArea
id(s) will be returned.
- getProjectAreas(archived=False, returned_properties=None)[source]¶
Get all
rtcclient.project_area.ProjectArea
objectsIf no
rtcclient.project_area.ProjectArea
objects are retrieved, None is returned.- Parameters:
archived – (default is False) whether the project area is archived
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanations
- Returns:
A
list
that contains all thertcclient.project_area.ProjectArea
objects- Return type:
- getSeverities(projectarea_id=None, projectarea_name=None)[source]¶
Get all
rtcclient.models.Severity
objects by project area id or nameAt least either of projectarea_id and projectarea_name is given
If no
rtcclient.models.Severity
is retrieved, None is returned.- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
- Returns:
a
list
that contains all thertcclient.models.Severity
objects- Return type:
- getSeverity(severity_name, projectarea_id=None, projectarea_name=None)[source]¶
Get
rtcclient.models.Severity
object by its nameAt least either of projectarea_id and projectarea_name is given
- Parameters:
severity_name – the severity name
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
- Returns:
the
rtcclient.models.Severity
object- Return type:
- getTeamArea(teamarea_name, projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]¶
Get
rtcclient.models.TeamArea
object by its nameIf projectarea_id or projectarea_name is specified, then the matched
rtcclient.models.TeamArea
in that project area will be returned. Otherwise, only return the first foundrtcclient.models.TeamArea
with that name.- Parameters:
teamarea_name – the team area name
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the team area is archived
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanations
- Returns:
the
rtcclient.models.TeamArea
object- Return type:
- getTeamAreas(projectarea_id=None, projectarea_name=None, archived=False, returned_properties=None)[source]¶
Get all
rtcclient.models.TeamArea
objects by project area id or nameIf both projectarea_id and projectarea_name are None, all team areas in all project areas will be returned.
If no
rtcclient.models.TeamArea
objects are retrieved, None is returned.- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
archived – (default is False) whether the team areas are archived
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanations
- Returns:
a
list
that contains all thertcclient.models.TeamArea
objects- Return type:
- getTemplate(copied_from, template_name=None, template_folder=None, keep=False, encoding='UTF-8')[source]¶
Get template from some to-be-copied workitems
More details, please refer to
rtcclient.template.Templater.getTemplate
- getTemplates(workitems, template_folder=None, template_names=None, keep=False, encoding='UTF-8')[source]¶
Get templates from a group of to-be-copied workitems and write them to files named after the names in template_names respectively.
More details, please refer to
rtcclient.template.Templater.getTemplates
- getWorkitem(workitem_id, returned_properties=None, skip_full_attributes=True)[source]¶
Get
rtcclient.workitem.Workitem
object by its id/number- Parameters:
workitem_id – the workitem id/number (integer or equivalent string)
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanationsskip_full_attributes – flag to retrieve all attributes.
- Returns:
the
rtcclient.workitem.Workitem
object- Return type:
- getWorkitems(projectarea_id=None, projectarea_name=None, returned_properties=None, archived=False, skip_full_attributes=True)[source]¶
Get all
rtcclient.workitem.Workitem
objects by project area id or nameIf both projectarea_id and projectarea_name are None, all the workitems in all project areas will be returned.
If no
rtcclient.workitem.Workitem
objects are retrieved, None is returned.You can also customize your preferred properties to be returned by specified returned_properties
- Parameters:
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanationsarchived – (default is False) whether the workitems are archived
- Returns:
a
list
that contains all thertcclient.workitem.Workitem
objects- Return type:
- listFields(template)[source]¶
List all the attributes to be rendered from the template file
- Parameters:
template – The template to render. The template is actually a file, which is usually generated by
rtcclient.template.Templater.getTemplate
and can also be modified by user accordingly.- Returns:
a
set
that contains all the needed attributes- Return type:
More details, please refer to
rtcclient.template.Templater.listFieldsFromWorkitem
- listFieldsFromWorkitem(copied_from, keep=False)[source]¶
List all the attributes to be rendered directly from some to-be-copied workitems
More details, please refer to
rtcclient.template.Templater.listFieldsFromWorkitem
- queryWorkitems(query_str, projectarea_id=None, projectarea_name=None, returned_properties=None, archived=False)[source]¶
Query workitems with the query string in a certain project area
At least either of projectarea_id and projectarea_name is given
- Parameters:
query_str – a valid query string
projectarea_id – the
rtcclient.project_area.ProjectArea
idprojectarea_name – the project area name
returned_properties – the returned properties that you want. Refer to
rtcclient.client.RTCClient
for more explanationsarchived – (default is False) whether the workitems are archived
- Returns:
a
list
that contains the queriedrtcclient.workitem.Workitem
objects- Return type: