Welcome to rt’s documentation!¶
Contents:
Rt - Python interface to Request Tracker API¶
Description of Request Tracker REST API: http://requesttracker.wikia.com/wiki/REST
Provided functionality:
login to RT
logout
getting, creating and editing tickets
getting attachments
getting history of ticket
replying to ticket requestors
adding comments
getting and editing ticket links
searching
providing lists of last updated tickets
providing tickets with new correspondence
merging tickets
take tickets
steal tickets
untake tickets
-
rt.rt.
DEFAULT_QUEUE
= 'General'¶ Default queue used.
-
class
rt.rt.
Rt
(url: str, default_login: Optional[str] = None, default_password: Optional[str] = None, cookies: Optional[dict] = None, proxy: Optional[str] = None, default_queue: str = 'General', skip_login: bool = False, verify_cert: Optional[Union[str, bool]] = True, http_auth: Optional[requests.auth.AuthBase] = None)[source]¶ API for Request Tracker according to http://requesttracker.wikia.com/wiki/REST. Interface is based on REST architecture, which is based on HTTP/1.1 protocol. This module is therefore mainly sending and parsing special HTTP messages.
Note
Use only ASCII LF as newline (
\n
). Time is returned in UTC. All strings returned are encoded in UTF-8 and the same is expected as input for string values.-
comment
(ticket_id: Union[str, int], text: str = '', cc: str = '', bcc: str = '', content_type: str = 'text/plain', files: Optional[List[Tuple[str, IO, Optional[str]]]] = None) → bool[source]¶ Adds comment to the given ticket.
Form of message according to documentation:
id: <ticket-id> Action: comment Text: the text comment second line starts with the same indentation as first Attachment: an attachment filename/path
Example:
>>> tracker = Rt('http://tracker.example.com/REST/1.0/', 'rt-username', 'top-secret') >>> attachment_name = sys.argv[1] >>> message_text = ' '.join(sys.argv[2:]) >>> ret = tracker.comment(ticket_id, text=message_text, ... files=[(attachment_name, open(attachment_name, 'rb'))]) >>> if not ret: ... print('Error: could not send attachment', file=sys.stderr) ... exit(1)
- Parameters
ticket_id – ID of ticket to which comment belongs
text – Content of comment
content_type – Content type of comment, default to text/plain
files – Files to attach as multipart/form-data List of 2/3 tuples: (filename, file-like object, [content type])
- Returns
True
Operation was successful
False
Sending failed (status code != 200)
- Raises
BadRequest – When ticket does not exist
-
create_queue
(Name: str, **kwargs: Any) → int[source]¶ Create queue (undocumented API feature).
- Parameters
Name – Queue name (required)
kwargs – Optional fields to set (see edit_queue)
- Returns
ID of new queue or False when create fails
- Raises
BadRequest – When queue already exists
InvalidUse – When invalid fields are set
-
create_ticket
(Queue: Optional[Union[str, object]] = None, files: Optional[List[Tuple[str, IO, Optional[str]]]] = None, **kwargs: Any) → int[source]¶ Create new ticket and set given parameters.
Example of message sended to
http://tracker.example.com/REST/1.0/ticket/new
:content=id: ticket/new Queue: General Owner: Nobody Requestors: somebody@example.com Subject: Ticket created through REST API Text: Lorem Ipsum
In case of success returned message has this form:
RT/3.8.7 200 Ok # Ticket 123456 created. # Ticket 123456 updated.
Otherwise:
RT/3.8.7 200 Ok # Required: id, Queue
list of some key, value pairs, probably default values.
- Parameters
Queue – Queue where to create ticket
files – Files to attach as multipart/form-data List of 2/3 tuples: (filename, file-like object, [content type])
kwargs –
Other arguments possible to set:
Requestors, Subject, Cc, AdminCc, Owner, Status, Priority, InitialPriority, FinalPriority, TimeEstimated, Starts, Due, Text,… (according to RT fields)
Custom fields CF.{<CustomFieldName>} could be set with keywords CF_CustomFieldName.
- Returns
ID of new ticket or
-1
, if creating failed
-
create_user
(Name: str, EmailAddress: str, **kwargs: Any) → Union[int, bool][source]¶ Create user (undocumented API feature).
- Parameters
Name – User name (login for privileged, required)
EmailAddress – Email address (required)
kwargs – Optional fields to set (see edit_user)
- Returns
ID of new user or False when create fails
- Raises
BadRequest – When user already exists
InvalidUse – When invalid fields are set
-
edit_link
(ticket_id: Union[str, int], link_name: str, link_value: Union[str, int], delete: bool = False) → bool[source]¶ Creates or deletes a link between the specified tickets (undocumented API feature).
- Parameters
ticket_id – ID of ticket to edit
link_name – Name of link to edit (DependsOn, DependedOnBy, RefersTo, ReferredToBy, HasMember or MemberOf)
link_value – Either ticker ID or external link.
delete – if True the link is deleted instead of created
- Returns
True
Operation was successful
False
Ticket with given ID does not exist or link to delete is not found
- Raises
InvalidUse – When none or more then one links are specified. Also when wrong link name is used.
-
edit_queue
(queue_id: Union[str, int], **kwargs: Any) → Union[str, bool][source]¶ Edit queue (undocumented API feature).
- Parameters
queue_id – Identification of queue by name (str) or ID (int)
kwargs –
Other fields to edit from the following list:
Name
Description
CorrespondAddress
CommentAddress
InitialPriority
FinalPriority
DefaultDueIn
- Returns
ID or name of edited queue or False when edit fails
- Raises
BadRequest – When queue does not exist
InvalidUse – When invalid fields are set
-
edit_ticket
(ticket_id: Union[str, int], **kwargs: Any) → bool[source]¶ Edit ticket values.
- Parameters
ticket_id – ID of ticket to edit
kwargs –
Other arguments possible to set:
Requestors, Subject, Cc, AdminCc, Owner, Status, Priority, InitialPriority, FinalPriority, TimeEstimated, Starts, Due, Text,… (according to RT fields)
Custom fields CF.{<CustomFieldName>} could be set with keywords CF_CustomFieldName.
- Returns
True
Operation was successful
False
Ticket with given ID does not exist or unknown parameter was set (in this case all other valid fields are changed)
-
edit_ticket_links
(ticket_id: Union[str, int], **kwargs: Any) → bool[source]¶ Edit ticket links.
Warning
This method is deprecated in favour of edit_link method, because there exists bug in RT 3.8 REST API causing mapping created links to ticket/1. The only drawback is that edit_link cannot process multiple links all at once.
- Parameters
ticket_id – ID of ticket to edit
kwargs – Other arguments possible to set: DependsOn, DependedOnBy, RefersTo, ReferredToBy, Members, MemberOf. Each value should be either ticker ID or external link. Int types are converted. Use empty string as value to delete existing link.
- Returns
True
Operation was successful
False
Ticket with given ID does not exist or unknown parameter was set (in this case all other valid fields are changed)
-
edit_user
(user_id: Union[str, int], **kwargs: Any) → Union[int, bool][source]¶ Edit user profile (undocumented API feature).
- Parameters
user_id – Identification of user by username (str) or user ID (int)
kwargs –
Other fields to edit from the following list:
Name
Password
EmailAddress
RealName
NickName
Gecos
Organization
Address1
Address2
City
State
Zip
Country
HomePhone
WorkPhone
MobilePhone
PagerPhone
ContactInfo
Comments
Signature
Lang
EmailEncoding
WebEncoding
ExternalContactInfoId
ContactInfoSystem
ExternalAuthId
AuthSystem
Privileged
Disabled
- Returns
ID of edited user or False when edit fails
- Raises
BadRequest – When user does not exist
InvalidUse – When invalid fields are set
-
get_attachment
(ticket_id: Union[str, int], attachment_id: Union[str, int]) → Optional[dict][source]¶ Get attachment.
- Parameters
ticket_id – ID of ticket
attachment_id – ID of attachment for obtain
- Returns
Attachment as dictionary with these keys:
Transaction
ContentType
Parent
Creator
Created
Filename
Content (bytes type)
Headers
MessageId
ContentEncoding
id
Subject
All these fields are strings, just ‘Headers’ holds another dictionary with attachment headers as strings e.g.:
Delivered-To
From
Return-Path
Content-Length
To
X-Seznam-User
X-QM-Mark
Domainkey-Signature
RT-Message-ID
X-RT-Incoming-Encryption
X-Original-To
Message-ID
X-Spam-Status
In-Reply-To
Date
Received
X-Country
X-Spam-Checker-Version
X-Abuse
MIME-Version
Content-Type
Subject
Warning
Content-Length parameter is set after opening ticket in web interface!
Set of headers available depends on mailservers sending emails not on Request Tracker!
Returns None if ticket or attachment does not exist.
- Raises
UnexpectedMessageFormat – Unexpected format of returned message.
-
get_attachment_content
(ticket_id: Union[str, int], attachment_id: Union[str, int]) → Optional[bytes][source]¶ Get content of attachment without headers.
This function is necessary to use for binary attachment, as it can contain
\n
chars, which would disrupt parsing of message ifget_attachment()
is used.Format of message:
RT/3.8.7 200 Ok
Start of the content…End of the content
- param ticket_id
ID of ticket
- param attachment_id
ID of attachment
- Returns: Bytes with content of attachment or None if ticket or
attachment does not exist.
-
get_attachments
(ticket_id: Union[str, int]) → Optional[List[Tuple[str, str, str, str]]][source]¶ Get attachment list for a given ticket
- Parameters
ticket_id – ID of ticket
- Returns
List of tuples for attachments belonging to given ticket. Tuple format: (id, name, content_type, size) Returns None if ticket does not exist.
-
get_attachments_ids
(ticket_id: Union[str, int]) → Optional[List[int]][source]¶ Get IDs of attachments for given ticket.
- Parameters
ticket_id – ID of ticket
- Returns
List of IDs (type int) of attachments belonging to given ticket. Returns None if ticket does not exist.
-
get_history
(ticket_id: Union[str, int], transaction_id: Optional[Union[str, int]] = None) → Optional[List[dict]][source]¶ Get set of history items.
- Parameters
ticket_id – ID of ticket
transaction_id – If set to None, all history items are returned, if set to ID of valid transaction just one history item is returned
- Returns
List of history items ordered increasingly by time of event. Each history item is dictionary with following keys:
Description, Creator, Data, Created, TimeTaken, NewValue, Content, Field, OldValue, Ticket, Type, id, Attachments
All these fields are strings, just ‘Attachments’ holds list of pairs (attachment_id,filename_with_size).
Returns None if ticket or transaction does not exist.
- Raises
UnexpectedMessageFormat – Unexpected format of returned message.
-
get_links
(ticket_id: Union[str, int]) → Optional[Dict[str, List[str]]][source]¶ Gets the ticket links for a single ticket.
- Parameters
ticket_id – ticket ID
- Returns
Links as lists of strings in dictionary with these keys (just those which are defined):
id
Members
MemberOf
RefersTo
ReferredToBy
DependsOn
DependedOnBy
None is returned if ticket does not exist.
- Raises
UnexpectedMessageFormat – In case that returned status code is not 200
-
get_queue
(queue_id: Union[str, int]) → Optional[Dict[str, str]][source]¶ Get queue details.
- Parameters
queue_id – Identification of queue by name (str) or queue ID (int)
- Returns
Queue details as strings in dictionary with these keys if queue exists (otherwise None):
id
Name
Description
CorrespondAddress
CommentAddress
InitialPriority
FinalPriority
DefaultDueIn
- Raises
UnexpectedMessageFormat – In case that returned status code is not 200
-
get_short_history
(ticket_id: Union[str, int]) → Optional[List[Tuple[int, str]]][source]¶ Get set of short history items
- Parameters
ticket_id – ID of ticket
- Returns
List of history items ordered increasingly by time of event. Each history item is a tuple containing (id, Description). Returns None if ticket does not exist.
-
get_ticket
(ticket_id: Union[str, int]) → Optional[dict][source]¶ Fetch ticket by its ID.
- Parameters
ticket_id – ID of demanded ticket
- Returns
Dictionary with key, value pairs for ticket with ticket_id or None if ticket does not exist. List of keys:
id
numerical_id
Queue
Owner
Creator
Subject
Status
Priority
InitialPriority
FinalPriority
Requestors
Cc
AdminCc
Created
Starts
Started
Due
Resolved
Told
TimeEstimated
TimeWorked
TimeLeft
- Raises
UnexpectedMessageFormat – Unexpected format of returned message.
-
get_user
(user_id) → Optional[Dict[str, str]][source]¶ Get user details.
- Parameters
user_id – Identification of user by username (str) or user ID (int)
- Returns
User details as strings in dictionary with these keys for RT users:
Lang
RealName
Privileged
Disabled
Gecos
EmailAddress
Password
id
Name
Or these keys for external users (e.g. Requestors replying to email from RT:
RealName
Disabled
EmailAddress
Password
id
Name
None is returned if user does not exist.
- Raises
UnexpectedMessageFormat – In case that returned status code is not 200
-
last_updated
(since: str, queue: Optional[Union[str, object]] = None) → List[dict][source]¶ Obtains tickets changed after given date.
- Parameters
since – Date as string in form ‘2011-02-24’
queue – Queue where to search
- Returns
List of tickets with LastUpdated parameter later than since ordered in decreasing order by LastUpdated. Each tickets is dictionary, the same as in
get_ticket()
.
-
login
(login: Optional[str] = None, password: Optional[str] = None) → bool[source]¶ Login with default or supplied credetials.
Note
Calling this method is not necessary when HTTP basic or HTTP digest_auth authentication is used and RT accepts it as external authentication method, because the login in this case is done transparently by requests module. Anyway this method can be useful to check whether given credentials are valid or not.
- Parameters
login – Username used for RT, if not supplied together with password
default_login
anddefault_password
are used insteadpassword – Similarly as login
- Returns
True
Successful login
False
Otherwise
- Raises
AuthorizationError – In case that credentials are not supplied neither during inicialization or call of this method.
-
logout
() → bool[source]¶ Logout of user.
- Returns
True
Successful logout
False
Logout failed (mainly because user was not login)
-
merge_ticket
(ticket_id: Union[str, int], into_id: Union[str, int]) → bool[source]¶ Merge ticket into another (undocumented API feature).
- Parameters
ticket_id – ID of ticket to be merged
into – ID of destination ticket
- Returns
True
Operation was successful
False
Either origin or destination ticket does not exist or user does not have ModifyTicket permission.
-
new_correspondence
(queue: Optional[Union[str, object]] = None) → List[dict][source]¶ Obtains tickets changed by other users than the system one.
- Parameters
queue – Queue where to search
- Returns
List of tickets which were last updated by other user than the system one ordered in decreasing order by LastUpdated. Each ticket is dictionary, the same as in
get_ticket()
.
-
reply
(ticket_id: Union[str, int], text: str = '', cc: str = '', bcc: str = '', content_type: str = 'text/plain', files: Optional[List[Tuple[str, IO, Optional[str]]]] = None) → bool[source]¶ Sends email message to the contacts in
Requestors
field of given ticket with subject as is set inSubject
field.Form of message according to documentation:
id: <ticket-id> Action: correspond Text: the text comment second line starts with the same indentation as first Cc: <...> Bcc: <...> TimeWorked: <...> Attachment: an attachment filename/path
- Parameters
ticket_id – ID of ticket to which message belongs
text – Content of email message
content_type – Content type of email message, default to text/plain
cc – Carbon copy just for this reply
bcc – Blind carbon copy just for this reply
files – Files to attach as multipart/form-data List of 2/3 tuples: (filename, file-like object, [content type])
- Returns
True
Operation was successful
False
Sending failed (status code != 200)
- Raises
BadRequest – When ticket does not exist
-
search
(Queue: Optional[Union[str, object]] = None, order: Optional[str] = None, raw_query: Optional[str] = None, Format: str = 'l', **kwargs: Any) → List[dict][source]¶ Search arbitrary needles in given fields and queue.
Example:
>>> tracker = Rt('http://tracker.example.com/REST/1.0/', 'rt-username', 'top-secret') >>> tracker.login() >>> tickets = tracker.search(CF_Domain='example.com', Subject__like='warning') >>> tickets = tracker.search(Queue='General', order='Status', raw_query="id='1'+OR+id='2'+OR+id='3'")
- Parameters
Queue – Queue where to search. If you wish to search across all of your queues, pass the ALL_QUEUES object as the argument.
order – Name of field sorting result list, for descending order put - before the field name. E.g. -Created will put the newest tickets at the beginning
raw_query – A raw query to provide to RT if you know what you are doing. You may still pass Queue and order kwargs, so use these instead of including them in the raw query. You can refer to the RT query builder. If passing raw_query, all other **kwargs will be ignored.
Format – Format of the query: - i: only `id’ fields are populated - s: only `id’ and `subject’ fields are populated - l: multi-line format, all fields are populated
kwargs –
Other arguments possible to set if not passing raw_query:
Requestors, Subject, Cc, AdminCc, Owner, Status, Priority, InitialPriority, FinalPriority, TimeEstimated, Starts, Due, Text,… (according to RT fields)
Custom fields CF.{<CustomFieldName>} could be set with keywords CF_CustomFieldName.
To alter lookup operators you can append one of the following endings to each keyword:
__exact for operator = (default) __notexact for operator != __gt for operator > __lt for operator < __like for operator LIKE __notlike for operator NOT LIKE __is for operator IS __isnot for operator IS NOT
Setting values to keywords constrain search result to the tickets satisfying all of them.
- Returns
List of matching tickets. Each ticket is the same dictionary as in
get_ticket()
.- Raises
UnexpectedMessageFormat: Unexpected format of returned message. InvalidQueryError: If raw query is malformed
-
static
split_header
(line: str) → Sequence[str][source]¶ Split a header line into field name and field value.
Note that custom fields may contain colons inside the curly braces, so we need a special test for them.
- Parameters
line – A message line to be split.
- Returns
(Field name, field value) tuple.
-
steal
(ticket_id: Union[str, int]) → bool[source]¶ Steal ticket
- Parameters
ticket_id – ID of ticket to be merged
- Returns
True
Operation was successful
False
Either the ticket does not exist or user does not have StealTicket permission.
-
Exceptions collection for the rt library.
-
exception
rt.exceptions.
AuthorizationError
[source]¶ Exception raised when module cannot access API due to invalid or missing credentials.
-
exception
rt.exceptions.
BadRequest
[source]¶ Exception raised when HTTP code 400 (Bad Request) is received.
-
exception
rt.exceptions.
ConnectionError
(message: str, cause: Exception)[source]¶ Encapsulation of various exceptions indicating network problems.
-
exception
rt.exceptions.
InvalidQueryError
[source]¶ Exception raised when attempting to search RT with an invalid raw query.
-
exception
rt.exceptions.
NotAllowed
[source]¶ Exception raised when request cannot be finished due to insufficient privileges.
Get rt module¶
Using pip:
$ pip install rt
Using project git repository:
$ git clone https://github.com/CZ-NIC/python-rt