"""
This type stub file was generated by pyright.
"""

import collections.abc
import dataclasses
import typing
import httpx
from typing import Literal

"""
This type stub file was generated by pyright.
"""
__license__ = ...
__docformat__ = ...
__authors__ = ...
VALID_TICKET_LINK_NAMES = ...
TYPE_VALID_TICKET_LINK_NAMES = Literal['Parent', 'Child', 'RefersTo', 'ReferredToBy', 'DependsOn', 'DependedOnBy']
TYPE_CONTENT_TYPE = Literal['text/plain', 'text/html']
REGEX_PATTERNS = ...
@dataclasses.dataclass
class Attachment:
    """Dataclass representing an attachment."""
    file_name: str
    file_type: str
    file_content: bytes
    def to_dict(self) -> typing.Dict[str, str]:
        """Convert to a dictionary for submitting to the REST API."""
        ...
    
    def multipart_form_element(self) -> typing.Tuple[str, bytes, str]:
        """Convert to a tuple as required for multipart-form-data submission."""
        ...
    


class Rt:
    url: str
    session: httpx.Client
    r""":term:`API` for Request Tracker according to https://docs.bestpractical.com/rt/5.0.2/RT/REST2.html.

    Interface is based on
    :term:`REST` architecture, which is based on HTTP/1.1 protocol. This module
    is therefore mainly sending and parsing special HTTP messages.

    .. warning:: You need at least version 5.0.2 of RT.

    .. 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.
    """
    def __init__(self, url: str, proxy: typing.Optional[str] = ..., verify_cert: typing.Union[str, bool] = ..., http_auth: typing.Optional[httpx.Auth] = ..., token: typing.Optional[str] = ..., http_timeout: typing.Optional[int] = ...) -> None:
        """API initialization.

        :param url: Base URL for Request Tracker API.
                      E.g.: http://tracker.example.com/REST/2.0/
        :param proxy: Proxy server (string with http://user:password@host/ syntax)
        :param http_auth: Specify a http authentication instance, e.g. HTTPBasicAuth(), HTTPDigestAuth(),
                            etc. to be used for authenticating to RT
        :param token: Optional authentication token to be used instead of basic authentication.
        :param http_timeout: HTTP timeout after which a request is aborted.

        :raises ValueError: If the specified `url` is invalid.
        """
        ...
    
    def new_correspondence(self, queue: typing.Optional[typing.Union[str, object]] = ...) -> typing.Iterator[dict]:
        """Obtains tickets changed by other users than the system one.

        :param queue: Queue where to search

        :returns: Iterator of tickets which were last updated by another user than
                  the system one, ordered in decreasing order by LastUpdated.
                  Each ticket is dictionary, the same as in
                  :py:meth:`~Rt.get_ticket`.
        """
        ...
    
    def last_updated(self, since: str, queue: typing.Optional[str] = ...) -> typing.Iterator[dict]:
        """Obtains tickets changed after given date.

        :param since: Date as string in form '2011-02-24'
        :param queue: Queue where to search

        :returns: Iterator of tickets with LastUpdated parameter later than
                  *since* ordered in decreasing order by LastUpdated.
                  Each ticket is a dictionary, the same as in
                  :py:meth:`~Rt.get_ticket`.

        :raises InvalidUseError: If the specified date is of an unsupported format.
        """
        ...
    
    def search(self, queue: typing.Optional[typing.Union[str, object]] = ..., order: typing.Optional[str] = ..., raw_query: typing.Optional[str] = ..., query_format: str = ..., **kwargs: typing.Any) -> typing.Iterator[dict[str, typing.Any]]:
        r"""Search arbitrary needles in given fields and queue.

        Example::

            >>> tracker = Rt('http://tracker.example.com/REST/2.0/', 'rt-username', 'top-secret')
            >>> tickets = list(tracker.search(CF_Domain='example.com', Subject__like='warning'))
            >>> tickets = list(tracker.search(queue='General', order='Status', raw_query="id='1'+OR+id='2'+OR+id='3'"))

        :param queue:      Queue where to search. If you wish to search across
                           all of your queues, pass the ALL_QUEUES object as the
                           argument.
        :param 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
        :param 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.
        :param query_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
        :param 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: Iterator over matching tickets. Each ticket is the same dictionary
                  as in :py:meth:`~Rt.get_ticket`.
        :raises:  UnexpectedMessageFormatError: Unexpected format of returned message.
                  InvalidQueryError: If raw query is malformed
        """
        ...
    
    def get_ticket(self, ticket_id: typing.Union[str, int]) -> dict:
        """Fetch ticket by its ID.

        :param 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 UnexpectedMessageFormatError: Unexpected format of returned message.
        :raises NotFoundError: If there is no ticket with the specified ticket_id.
        """
        ...
    
    def create_ticket(self, queue: str, content_type: TYPE_CONTENT_TYPE = ..., subject: typing.Optional[str] = ..., content: typing.Optional[str] = ..., attachments: typing.Optional[typing.Sequence[Attachment]] = ..., **kwargs: typing.Any) -> int:
        """Create new ticket and set given parameters.

        Example of message sent to ``http://tracker.example.com/REST/2.0/ticket/new``::

            { "Queue": "General",
              "Subject": "Ticket created through REST API",
              "Owner": "Nobody",
              "Requestor": "somebody@example.com",
              "Cc": "user2@example.com",
              "CustomRoles": {"My Role": "staff1@example.com"},
              "Content": "Lorem Ipsum",
              "CustomFields": {"Severity": "Low"}
            }

        :param queue: Queue where to create ticket
        :param content_type: Content-type of the Content parameter; can be either text/plain or text/html.
        :param subject: Optional subject for the ticket.
        :param content: Optional content of the ticket. Must be specified unless attachments are specified.
        :param attachments: Optional list of :py:class:`~rt.rest2.Attachment` objects
        :param kwargs: Other arguments possible to set:

                         Requestor, Cc, AdminCc, Owner, Status,
                         Priority, InitialPriority, FinalPriority,
                         TimeEstimated, Starts, Due

        :returns: ID of new ticket
        :raises ValueError: If the `content_type` is not of a supported format.
        """
        ...
    
    def edit_ticket(self, ticket_id: typing.Union[str, int], **kwargs: typing.Any) -> bool:
        """Edit ticket values.

        :param ticket_id: ID of ticket to edit
        :param 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 can be specified as dict:
                            CustomFields = {"Severity": "Low"}

        :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)
        """
        ...
    
    def get_ticket_history(self, ticket_id: typing.Union[str, int]) -> typing.Optional[typing.List[typing.Dict[str, typing.Any]]]:
        """Get set of short history items.

        :param 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.
        """
        ...
    
    def get_transaction(self, transaction_id: typing.Union[str, int]) -> typing.Dict[str, typing.Any]:
        """Get a transaction.

        :param transaction_id: ID of transaction
        :returns: Return a single transaction.
        """
        ...
    
    def reply(self, ticket_id: typing.Union[str, int], content: str = ..., content_type: TYPE_CONTENT_TYPE = ..., attachments: typing.Optional[typing.Sequence[Attachment]] = ...) -> bool:
        """Sends email message to the contacts in ``Requestors`` field of
        given ticket with subject as is set in ``Subject`` field.

        :param ticket_id: ID of ticket to which message belongs
        :param content: Content of email message (text/plain or text/html)
        :param content_type: Content type of email message, default to text/plain
        :param attachments: Optional list of :py:class:`~rt.rest2.Attachment` objects
        :returns: ``True``
                      Operation was successful
                  ``False``
                      Sending failed (status code != 200)
        :raises BadRequestError: When ticket does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def delete_ticket(self, ticket_id: typing.Union[str, int]) -> None:
        """Mark a ticket as deleted.

        :param ticket_id: ID of ticket

        :raises BadRequestError: When user does not exist
        :raises NotFoundError: If the user does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def comment(self, ticket_id: typing.Union[str, int], content: str = ..., content_type: TYPE_CONTENT_TYPE = ..., attachments: typing.Optional[typing.Sequence[Attachment]] = ...) -> bool:
        """Adds comment to the given ticket.

        :param ticket_id: ID of ticket to which comment belongs
        :param content: Content of comment
        :param content_type: Content type of comment, default to text/plain
        :param attachments: Optional list of :py:class:`~rt.rest2.Attachment` objects
        :returns: ``True``
                      Operation was successful
                  ``False``
                      Sending failed (status code != 200)
        :raises BadRequestError: When ticket does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def get_attachments(self, ticket_id: typing.Union[str, int]) -> typing.Sequence[typing.Dict[str, str]]:
        """Get attachment list for a given ticket.

        Example of a return result:

        .. code-block:: json

            [
                {
                    "id": "17",
                    "Filename": "README.rst",
                    "ContentLength": "3578",
                    "type": "attachment",
                    "ContentType": "test/plain",
                    "_url": "http://localhost:8080/REST/2.0/attachment/17"
                }
            ]

        :param 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.
        """
        ...
    
    def get_attachments_ids(self, ticket_id: typing.Union[str, int]) -> typing.Optional[typing.List[int]]:
        """Get IDs of attachments for given ticket.

        :param ticket_id: ID of ticket
        :returns: List of IDs (type int) of attachments belonging to given
                  ticket. Returns None if ticket does not exist.
        """
        ...
    
    def get_attachment(self, attachment_id: typing.Union[str, int]) -> typing.Optional[dict[str, str]]:
        """Get attachment.

        :param attachment_id: ID of attachment to fetch
        :returns: Attachment as dictionary with these keys:

                      * Transaction
                      * ContentType
                      * Parent
                      * Creator
                      * Created
                      * Filename
                      * Content (base64 encoded string)
                      * 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

                  Set of headers available depends on mailservers sending
                  emails not on Request Tracker!

        :raises UnexpectedMessageFormatError: Unexpected format of returned message.
        :raises NotFoundError: If attachment with specified ID does not exist.
        """
        ...
    
    def get_user(self, user_id: typing.Union[int, str]) -> typing.Dict[str, typing.Any]:
        """Get user details.

        :param 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

        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        :raises NotFoundError: If the user does not exist.
        """
        ...
    
    def user_exists(self, user_id: typing.Union[int, str], privileged: bool = ...) -> bool:
        """Check if a given user_id exists.

        :parameter user_id: User ID to lookup.
        :parameter privileged: If set to True, only return True if the user_id was found and is privileged.

        :returns: bool: True on success, else False.
        """
        ...
    
    def create_user(self, user_name: str, email_address: str, **kwargs: typing.Any) -> str:
        """Create user.

        :param user_name: Username (login for privileged, required)
        :param email_address: Email address (required)
        :param kwargs: Optional fields to set (see edit_user)
        :returns: ID of new user or False when create fails
        :raises BadRequestError: When user already exists
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def edit_user(self, user_id: typing.Union[str, int], **kwargs: typing.Any) -> typing.List[str]:
        """Edit user profile.

        :param user_id: Identification of user by username (str) or user ID
                        (int)
        :param 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: List of status messages
        :raises BadRequestError: When user does not exist
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def delete_user(self, user_id: typing.Union[str, int]) -> None:
        """Disable a user.

        :param user_id: Identification of a user by name (str) or ID (int)

        :raises BadRequestError: When user does not exist
        :raises NotFoundError: If the user does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def get_queue(self, queue_id: typing.Union[str, int]) -> typing.Optional[typing.Dict[str, typing.Any]]:
        """Get queue details.

        Example of a return result:

        .. code-block:: json

            {
                "LastUpdatedBy": {
                    "_url": "http://localhost:8080/REST/2.0/user/RT_System",
                    "type": "user",
                    "id": "RT_System"
                },
                "LastUpdated": "2022-03-06T04:53:38Z",
                "AdminCc": [],
                "SortOrder": "0",
                "CorrespondAddress": "",
                "Creator": {
                    "id": "RT_System",
                    "_url": "http://localhost:8080/REST/2.0/user/RT_System",
                    "type": "user"
                },
                "Lifecycle": "default",
                "Cc": [],
                "Created": "2022-03-06T04:53:38Z",
                "_hyperlinks": [
                    {
                        "_url": "http://localhost:8080/REST/2.0/queue/1",
                        "type": "queue",
                        "id": 1,
                        "ref": "self"
                    },
                    {
                        "ref": "history",
                        "_url": "http://localhost:8080/REST/2.0/queue/1/history"
                    },
                    {
                        "ref": "create",
                        "type": "ticket",
                        "_url": "http://localhost:8080/REST/2.0/ticket?Queue=1"
                    }
                ],
                "SLADisabled": "1",
                "Name": "General",
                "TicketCustomFields": [],
                "Disabled": "0",
                "TicketTransactionCustomFields": [],
                "CustomFields": [],
                "Description": "The default queue",
                "CommentAddress": "",
                "id": 1
            }

        :param queue_id: Identification of queue by name (str) or queue ID
                         (int)
        :returns: Queue details as a dictionary

        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        :raises NotFoundError: In case the queue does not exist
        """
        ...
    
    def get_all_queues(self, include_disabled: bool = ...) -> typing.List[typing.Dict[str, typing.Any]]:
        """Return a list of all queues.

        Example of a return result:

        .. code-block:: json

            [
                {
                    "InitialPriority": "",
                    "_url": "http://localhost:8080/REST/2.0/queue/1",
                    "type": "queue",
                    "Name": "General",
                    "DefaultDueIn": "",
                    "Description": "The default queue",
                    "CorrespondAddress": "",
                    "CommentAddress": "",
                    "id": "1",
                    "FinalPriority": ""
                }
            ]

        :param include_disabled: Set to True to also return disabled queues.

        :returns: Returns a list of dictionaries containing basic information on all queues.

        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        """
        ...
    
    def edit_queue(self, queue_id: typing.Union[str, int], **kwargs: typing.Any) -> typing.List[str]:
        """Edit queue.

        :param queue_id: Identification of queue by name (str) or ID (int)
        :param kwargs: Other fields to edit from the following list:

                          * Name
                          * Description
                          * CorrespondAddress
                          * CommentAddress
                          * Disabled
                          * SLADisabled
                          * Lifecycle
                          * SortOrder

        :returns: List of status messages
        :raises BadRequestError: When queue does not exist
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def create_queue(self, name: str, **kwargs: typing.Any) -> int:
        """Create queue.

        :param name: Queue name (required)
        :param kwargs: Optional fields to set (see edit_queue)
        :returns: ID of new queue or False when create fails
        :raises BadRequestError: When queue already exists
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def delete_queue(self, queue_id: typing.Union[str, int]) -> None:
        """Disable a queue.

        :param queue_id: Identification of queue by name (str) or ID (int)

        :returns: ID or name of edited queue or False when edit fails
        :raises BadRequestError: When queue does not exist
        :raises NotFoundError: If the queue does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def get_links(self, ticket_id: typing.Union[str, int]) -> typing.Optional[typing.List[typing.Dict[str, str]]]:
        """Gets the ticket links for a single ticket.

        Example of a return result:

        .. code-block:: json

            [
                {
                    "id": "13",
                    "type": "ticket",
                    "_url": "http://localhost:8080/REST/2.0/ticket/13",
                    "ref": "depends-on"
                }
            ]

        :param ticket_id: ticket ID
        :returns: Links as lists of strings in dictionary with these keys
                  (just those which are defined):

                        * depends-on
                        * depended-on-by
                        * parent
                        * child
                        * refers-to
                        * referred-to-by

                  None is returned if ticket does not exist.
        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        """
        ...
    
    def edit_link(self, ticket_id: typing.Union[str, int], link_name: TYPE_VALID_TICKET_LINK_NAMES, link_value: typing.Union[str, int], delete: bool = ...) -> bool:
        """Creates or deletes a link between the specified tickets.

        :param ticket_id: ID of ticket to edit
        :param link_name: Name of link to edit ('Parent', 'Child', 'RefersTo',
                           'ReferredToBy', 'DependsOn', 'DependedOnBy')
        :param link_value: Either ticker ID or external link.
        :param 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 InvalidUseError: When none or more than one link is specified. Also,
                            when a wrong link name is used or when trying to link to a deleted ticket.
        """
        ...
    
    def merge_ticket(self, ticket_id: typing.Union[str, int], into_id: typing.Union[str, int]) -> bool:
        """Merge ticket into another.

        :param ticket_id: ID of ticket to be merged
        :param into_id: 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def take(self, ticket_id: typing.Union[str, int]) -> bool:
        """Take ticket.

        :param 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def untake(self, ticket_id: typing.Union[str, int]) -> bool:
        """Untake ticket.

        :param 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    def steal(self, ticket_id: typing.Union[str, int]) -> bool:
        """Steal ticket.

        :param 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    


class AsyncRt:
    r""":term:`API` for Request Tracker according to
    https://docs.bestpractical.com/rt/5.0.2/RT/REST2.html. Interface is based on
    :term:`REST` architecture, which is based on HTTP/1.1 protocol. This module
    is therefore mainly sending and parsing special HTTP messages.

    .. warning:: You need at least version 5.0.2 of RT.

    .. 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.
    """
    def __init__(self, url: str, proxy: typing.Optional[str] = ..., verify_cert: typing.Union[str, bool] = ..., http_auth: typing.Optional[httpx.Auth] = ..., token: typing.Optional[str] = ..., http_timeout: typing.Optional[int] = ...) -> None:
        """API initialization.

        :param url: Base URL for Request Tracker API.
                      E.g.: http://tracker.example.com/REST/2.0/
        :param proxy: Proxy server (string with http://user:password@host/ syntax)
        :param http_auth: Specify a http authentication instance, e.g. HTTPBasicAuth(), HTTPDigestAuth(),
                            etc. to be used for authenticating to RT
        :param token: Optional authentication token to be used instead of basic authentication.
        :param http_timeout: HTTP timeout after which a request is aborted.

        :raises ValueError: If the specified `url` is invalid.
        """
        ...
    
    async def new_correspondence(self, queue: typing.Optional[typing.Union[str, object]] = ...) -> collections.abc.AsyncIterator:
        """Obtains tickets changed by other users than the system one.

        :param queue: Queue where to search

        :returns: Iterator of tickets which were last updated by another user than
                  the system one, ordered in decreasing order by LastUpdated.
                  Each ticket is dictionary, the same as in
                  :py:meth:`~Rt.get_ticket`.
                  collections.abc.AsyncIterator[dict]
        """
        ...
    
    async def last_updated(self, since: str, queue: typing.Optional[str] = ...) -> collections.abc.AsyncIterator:
        """Obtains tickets changed after given date.

        :param since: Date as string in form '2011-02-24'
        :param queue: Queue where to search

        :returns: Iterator of tickets with LastUpdated parameter later than
                  *since* ordered in decreasing order by LastUpdated.
                  Each ticket is a dictionary, the same as in
                  :py:meth:`~Rt.get_ticket`.
                  collections.abc.AsyncIterator[dict]

        :raises InvalidUseError: If the specified date is of an unsupported format.
        """
        ...
    
    async def search(self, queue: typing.Optional[typing.Union[str, object]] = ..., order: typing.Optional[str] = ..., raw_query: typing.Optional[str] = ..., query_format: str = ..., **kwargs: typing.Any) -> collections.abc.AsyncIterator:
        r"""Search arbitrary needles in given fields and queue.

        Example::

            >>> tracker = Rt('http://tracker.example.com/REST/2.0/', 'rt-username', 'top-secret')
            >>> tickets = list(tracker.search(CF_Domain='example.com', Subject__like='warning'))
            >>> tickets = list(tracker.search(queue='General', order='Status', raw_query="id='1'+OR+id='2'+OR+id='3'"))

        :param queue:      Queue where to search. If you wish to search across
                           all of your queues, pass the ALL_QUEUES object as the
                           argument.
        :param 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
        :param 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.
        :param query_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
        :param 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: Iterator over matching tickets. Each ticket is the same dictionary
                  as in :py:meth:`~Rt.get_ticket`.
                  collections.abc.AsyncIterator[dict]
        :raises:  UnexpectedMessageFormatError: Unexpected format of returned message.
                  InvalidQueryError: If raw query is malformed
        """
        ...
    
    async def get_ticket(self, ticket_id: typing.Union[str, int]) -> dict:
        """Fetch ticket by its ID.

        :param 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 UnexpectedMessageFormatError: Unexpected format of returned message.
        :raises NotFoundError: If there is no ticket with the specified ticket_id.
        """
        ...
    
    async def create_ticket(self, queue: str, content_type: TYPE_CONTENT_TYPE = ..., subject: typing.Optional[str] = ..., content: typing.Optional[str] = ..., attachments: typing.Optional[typing.Sequence[Attachment]] = ..., **kwargs: typing.Any) -> int:
        """Create new ticket and set given parameters.

        Example of message sent to ``http://tracker.example.com/REST/2.0/ticket/new``::

            { "Queue": "General",
              "Subject": "Ticket created through REST API",
              "Owner": "Nobody",
              "Requestor": "somebody@example.com",
              "Cc": "user2@example.com",
              "CustomRoles": {"My Role": "staff1@example.com"},
              "Content": "Lorem Ipsum",
              "CustomFields": {"Severity": "Low"}
            }

        :param queue: Queue where to create ticket
        :param content_type: Content-type of the Content parameter; can be either text/plain or text/html.
        :param subject: Optional subject for the ticket.
        :param content: Optional content of the ticket. Must be specified unless attachments are specified.
        :param attachments: Optional list of :py:class:`~rt.rest2.Attachment` objects
        :param kwargs: Other arguments possible to set:

                         Requestors, Cc, AdminCc, Owner, Status,
                         Priority, InitialPriority, FinalPriority,
                         TimeEstimated, Starts, Due

        :returns: ID of new ticket
        :raises ValueError: If the `content_type` is not of a supported format.
        """
        ...
    
    async def edit_ticket(self, ticket_id: typing.Union[str, int], **kwargs: typing.Any) -> bool:
        """Edit ticket values.

        :param ticket_id: ID of ticket to edit
        :param 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 can be specified as dict:
                            CustomFields = {"Severity": "Low"}

        :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)
        """
        ...
    
    async def get_ticket_history(self, ticket_id: typing.Union[str, int]) -> collections.abc.AsyncIterator:
        """Get set of short history items.

        :param ticket_id: ID of ticket
        :returns: Iterator of history items ordered increasingly by time of event.
                  Each history item is a tuple containing (id, Description).
                  collections.abc.AsyncIterator[typing.Dict[str, typing.Any]]
        """
        ...
    
    async def get_transaction(self, transaction_id: typing.Union[str, int]) -> typing.Dict[str, typing.Any]:
        """Get a transaction.

        :param transaction_id: ID of transaction
        :returns: Return a single transaction.
        """
        ...
    
    async def reply(self, ticket_id: typing.Union[str, int], content: str = ..., content_type: TYPE_CONTENT_TYPE = ..., attachments: typing.Optional[typing.Sequence[Attachment]] = ...) -> bool:
        """Sends email message to the contacts in ``Requestors`` field of
        given ticket with subject as is set in ``Subject`` field.

        :param ticket_id: ID of ticket to which message belongs
        :param content: Content of email message (text/plain or text/html)
        :param content_type: Content type of email message, default to text/plain
        :param attachments: Optional list of :py:class:`~rt.rest2.Attachment` objects
        :returns: ``True``
                      Operation was successful
                  ``False``
                      Sending failed (status code != 200)
        :raises BadRequestError: When ticket does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def delete_ticket(self, ticket_id: typing.Union[str, int]) -> None:
        """Mark a ticket as deleted.

        :param ticket_id: ID of ticket

        :raises BadRequestError: When user does not exist
        :raises NotFoundError: If the user does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def comment(self, ticket_id: typing.Union[str, int], content: str = ..., content_type: TYPE_CONTENT_TYPE = ..., attachments: typing.Optional[typing.Sequence[Attachment]] = ...) -> bool:
        """Adds comment to the given ticket.

        :param ticket_id: ID of ticket to which comment belongs
        :param content: Content of comment
        :param content_type: Content type of comment, default to text/plain
        :param attachments: Optional list of :py:class:`~rt.rest2.Attachment` objects
        :returns: ``True``
                      Operation was successful
                  ``False``
                      Sending failed (status code != 200)
        :raises BadRequestError: When ticket does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def get_attachments(self, ticket_id: typing.Union[str, int]) -> collections.abc.AsyncIterator:
        """Get attachment list for a given ticket.

        Example of a return result:

        .. code-block:: json

            [
                {
                    "id": "17",
                    "Filename": "README.rst",
                    "ContentLength": "3578",
                    "type": "attachment",
                    "ContentType": "test/plain",
                    "_url": "http://localhost:8080/REST/2.0/attachment/17"
                }
            ]

        :param ticket_id: ID of ticket
        :returns: Iterator of attachments belonging to given ticket. collections.abc.AsyncIterator[typing.Dict[str, str]]
        """
        ...
    
    async def get_attachments_ids(self, ticket_id: typing.Union[str, int]) -> collections.abc.AsyncIterator:
        """Get IDs of attachments for given ticket.

        :param ticket_id: ID of ticket
        :returns: Iterator of IDs (type int) of attachments belonging to given
                  ticket.
                  collections.abc.AsyncIterator[int]
        """
        ...
    
    async def get_attachment(self, attachment_id: typing.Union[str, int]) -> typing.Optional[dict[str, typing.Any]]:
        """Get attachment.

        :param attachment_id: ID of attachment to fetch
        :returns: Attachment as dictionary with these keys:

                      * Transaction
                      * ContentType
                      * Parent
                      * Creator
                      * Created
                      * Filename
                      * Content (base64 encoded string)
                      * 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

                  Set of headers available depends on mailservers sending
                  emails not on Request Tracker!

        :raises UnexpectedMessageFormatError: Unexpected format of returned message.
        :raises NotFoundError: If attachment with specified ID does not exist.
        """
        ...
    
    async def get_user(self, user_id: typing.Union[int, str]) -> typing.Dict[str, typing.Any]:
        """Get user details.

        :param 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

        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        :raises NotFoundError: If the user does not exist.
        """
        ...
    
    async def user_exists(self, user_id: typing.Union[int, str], privileged: bool = ...) -> bool:
        """Check if a given user_id exists.

        :parameter user_id: User ID to lookup.
        :parameter privileged: If set to True, only return True if the user_id was found and is privileged.

        :returns: bool: True on success, else False.
        """
        ...
    
    async def create_user(self, user_name: str, email_address: str, **kwargs: typing.Any) -> str:
        """Create user.

        :param user_name: Username (login for privileged, required)
        :param email_address: Email address (required)
        :param kwargs: Optional fields to set (see edit_user)
        :returns: ID of new user or False when create fails
        :raises BadRequestError: When user already exists
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def edit_user(self, user_id: typing.Union[str, int], **kwargs: typing.Any) -> typing.List[str]:
        """Edit user profile.

        :param user_id: Identification of user by username (str) or user ID
                        (int)
        :param 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: List of status messages
        :raises BadRequestError: When user does not exist
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def delete_user(self, user_id: typing.Union[str, int]) -> None:
        """Disable a user.

        :param user_id: Identification of a user by name (str) or ID (int)

        :raises BadRequestError: When user does not exist
        :raises NotFoundError: If the user does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def get_queue(self, queue_id: typing.Union[str, int]) -> typing.Optional[typing.Dict[str, typing.Any]]:
        """Get queue details.

        Example of a return result:

        .. code-block:: json

            {
                "LastUpdatedBy": {
                    "_url": "http://localhost:8080/REST/2.0/user/RT_System",
                    "type": "user",
                    "id": "RT_System"
                },
                "LastUpdated": "2022-03-06T04:53:38Z",
                "AdminCc": [],
                "SortOrder": "0",
                "CorrespondAddress": "",
                "Creator": {
                    "id": "RT_System",
                    "_url": "http://localhost:8080/REST/2.0/user/RT_System",
                    "type": "user"
                },
                "Lifecycle": "default",
                "Cc": [],
                "Created": "2022-03-06T04:53:38Z",
                "_hyperlinks": [
                    {
                        "_url": "http://localhost:8080/REST/2.0/queue/1",
                        "type": "queue",
                        "id": 1,
                        "ref": "self"
                    },
                    {
                        "ref": "history",
                        "_url": "http://localhost:8080/REST/2.0/queue/1/history"
                    },
                    {
                        "ref": "create",
                        "type": "ticket",
                        "_url": "http://localhost:8080/REST/2.0/ticket?Queue=1"
                    }
                ],
                "SLADisabled": "1",
                "Name": "General",
                "TicketCustomFields": [],
                "Disabled": "0",
                "TicketTransactionCustomFields": [],
                "CustomFields": [],
                "Description": "The default queue",
                "CommentAddress": "",
                "id": 1
            }

        :param queue_id: Identification of queue by name (str) or queue ID
                         (int)
        :returns: Queue details as a dictionary

        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        :raises NotFoundError: In case the queue does not exist
        """
        ...
    
    async def get_all_queues(self, include_disabled: bool = ...) -> collections.abc.AsyncIterator:
        """Return a list of all queues.

        Example of a return result:

        .. code-block:: json

            [
                {
                    "InitialPriority": "",
                    "_url": "http://localhost:8080/REST/2.0/queue/1",
                    "type": "queue",
                    "Name": "General",
                    "DefaultDueIn": "",
                    "Description": "The default queue",
                    "CorrespondAddress": "",
                    "CommentAddress": "",
                    "id": "1",
                    "FinalPriority": ""
                }
            ]

        :param include_disabled: Set to True to also return disabled queues.

        :returns: Iterator of dictionaries containing basic information on all queues.
                  collections.abc.AsyncIterator[typing.Dict[str, typing.Any]]

        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        """
        ...
    
    async def edit_queue(self, queue_id: typing.Union[str, int], **kwargs: typing.Any) -> typing.List[str]:
        """Edit queue.

        :param queue_id: Identification of queue by name (str) or ID (int)
        :param kwargs: Other fields to edit from the following list:

                          * Name
                          * Description
                          * CorrespondAddress
                          * CommentAddress
                          * Disabled
                          * SLADisabled
                          * Lifecycle
                          * SortOrder

        :returns: List of status messages
        :raises BadRequestError: When queue does not exist
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def create_queue(self, name: str, **kwargs: typing.Any) -> int:
        """Create queue.

        :param name: Queue name (required)
        :param kwargs: Optional fields to set (see edit_queue)
        :returns: ID of new queue or False when create fails
        :raises BadRequestError: When queue already exists
        :raises InvalidUseError: When invalid fields are set
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def delete_queue(self, queue_id: typing.Union[str, int]) -> None:
        """Disable a queue.

        :param queue_id: Identification of queue by name (str) or ID (int)

        :returns: ID or name of edited queue or False when edit fails
        :raises BadRequestError: When queue does not exist
        :raises NotFoundError: If the queue does not exist
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def get_links(self, ticket_id: typing.Union[str, int]) -> typing.List[typing.Dict[str, str]]:
        """Gets the ticket links for a single ticket.

        Example of a return result:

        .. code-block:: json

            [
                {
                    "id": "13",
                    "type": "ticket",
                    "_url": "http://localhost:8080/REST/2.0/ticket/13",
                    "ref": "depends-on"
                }
            ]

        :param ticket_id: ticket ID
        :returns: Links as lists of strings in dictionary with these keys
                  (just those which are defined):

                        * depends-on
                        * depended-on-by
                        * parent
                        * child
                        * refers-to
                        * referred-to-by

                  None is returned if ticket does not exist.
        :raises UnexpectedMessageFormatError: In case that returned status code is not 200
        """
        ...
    
    async def edit_link(self, ticket_id: typing.Union[str, int], link_name: TYPE_VALID_TICKET_LINK_NAMES, link_value: typing.Union[str, int], delete: bool = ...) -> bool:
        """Creates or deletes a link between the specified tickets.

        :param ticket_id: ID of ticket to edit
        :param link_name: Name of link to edit ('Parent', 'Child', 'RefersTo',
                           'ReferredToBy', 'DependsOn', 'DependedOnBy')
        :param link_value: Either ticker ID or external link.
        :param 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 InvalidUseError: When none or more than one link is specified. Also,
                            when a wrong link name is used or when trying to link to a deleted ticket.
        """
        ...
    
    async def merge_ticket(self, ticket_id: typing.Union[str, int], into_id: typing.Union[str, int]) -> bool:
        """Merge ticket into another.

        :param ticket_id: ID of ticket to be merged
        :param into_id: 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def take(self, ticket_id: typing.Union[str, int]) -> bool:
        """Take ticket.

        :param 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def untake(self, ticket_id: typing.Union[str, int]) -> bool:
        """Untake ticket.

        :param 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    
    async def steal(self, ticket_id: typing.Union[str, int]) -> bool:
        """Steal ticket.

        :param 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.
        :raises UnexpectedResponseError: If the response from RT is not as expected
        """
        ...
    


