# Welcome to rt’s documentation!

Contents:

- Glossary

## 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, proxy: Optional[str] = None, default_queue: str = 'General', skip_login: bool = False, verify_cert: Optional[Union[str, bool]] = True, http_auth: requests.auth.AuthBase = None)

  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

    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

    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

    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]

    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

    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]

    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

    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

    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]

    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]

    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]

    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 if `get_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]]]

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

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

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

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

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

    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]

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

    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]

    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

    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` and `default_password` are used instead

      - password – 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

    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

    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]

    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

    Sends email message to the contacts in `Requestors` field of given ticket with subject as is set in `Subject` 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]

    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

        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]

    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

    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.

  `take`(ticket_id: Union[str, int]) → bool

    Take 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 TakeTicket permission.

  `untake`(ticket_id: Union[str, int]) → bool

    Untake 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 own the ticket.

Exceptions collection for the rt library.

exception `rt.exceptions.``APISyntaxError`

  Exception raised when syntax error is received.

exception `rt.exceptions.``AuthorizationError`

  Exception raised when module cannot access API due to invalid or missing credentials.

exception `rt.exceptions.``BadRequest`

  Exception raised when HTTP code 400 (Bad Request) is received.

exception `rt.exceptions.``ConnectionError`(message: str, cause: Exception)

  Encapsulation of various exceptions indicating network problems.

exception `rt.exceptions.``InvalidQueryError`

  Exception raised when attempting to search RT with an invalid raw query.

exception `rt.exceptions.``InvalidUse`

  Exception raised when API method is not used correctly.

exception `rt.exceptions.``NotAllowed`

  Exception raised when request cannot be finished due to insufficient privileges.

exception `rt.exceptions.``RtError`

  Super class of all Rt Errors

exception `rt.exceptions.``UnexpectedMessageFormat`

  Exception raised when response has bad status code (not the HTTP code, but code in the first line of the body as 200 in RT/4.0.7 200 Ok) or message parsing fails because of unexpected format.

exception `rt.exceptions.``UnexpectedResponse`

  Exception raised when unexpected HTTP code is received.

# Get rt module

Using pip:

    $ pip install rt

Using project git repository:

    $ git clone https://github.com/CZ-NIC/python-rt

# Indices and tables

- Index

- Module Index

- Search Page