ticket.collection
=================

.. py:module:: ticket.collection


Attributes
----------

.. autoapisummary::

   ticket.collection.ExtendedTicketState


Classes
-------

.. autoapisummary::

   ticket.collection.TicketCollectionPagination
   ticket.collection.TicketCount
   ticket.collection.TicketCollection
   ticket.collection.ArchivedTicketCollection


Module Contents
---------------

.. py:type:: ExtendedTicketState
   :canonical: TicketState | Literal['all', 'unfinished']


.. py:class:: TicketCollectionPagination(session: sqlalchemy.orm.Session, page: int = 0, state: ExtendedTicketState = 'open', handler: str = 'ALL', group: str | None = None, owner: str = '*', extra_parameters: dict[str, Any] | None = None)

   Bases: :py:obj:`onegov.core.collection.Pagination`\ [\ :py:obj:`onegov.ticket.model.Ticket`\ ]


   Provides collections with pagination, if they implement a few
   documented properties and methods.

   See :class:`onegov.ticket.TicketCollection` for an example.



   .. py:method:: query() -> sqlalchemy.orm.Query[onegov.ticket.model.Ticket]


   .. py:attribute:: session


   .. py:attribute:: state
      :value: 'open'



   .. py:attribute:: handler
      :value: 'ALL'



   .. py:attribute:: handlers


   .. py:attribute:: group
      :value: None



   .. py:attribute:: owner
      :value: '*'



   .. py:method:: __eq__(other: object) -> bool

      Returns True if the current and the other Pagination instance
      are equal. Used to find the current page in a list of pages.




   .. py:method:: subset() -> sqlalchemy.orm.Query[onegov.ticket.model.Ticket]

      Returns an SQLAlchemy query containing all records that should
      be considered for pagination.




   .. py:property:: page_index
      :type: int


      Returns the current page index (starting at 0). 



   .. py:method:: page_by_index(index: int) -> Self

      Returns the page at the given index. A page here means an instance
      of the class inheriting from the ``Pagination`` base class.




   .. py:method:: available_groups(handler: str = '*') -> tuple[str, Ellipsis]


   .. py:method:: for_state(state: ExtendedTicketState) -> Self


   .. py:method:: for_handler(handler: str) -> Self


   .. py:method:: for_group(group: str) -> Self


   .. py:method:: for_owner(owner: str | uuid.UUID) -> Self


.. py:class:: TicketCount

   Bases: :py:obj:`NamedTuple`


   .. py:attribute:: open
      :type:  int
      :value: 0



   .. py:attribute:: pending
      :type:  int
      :value: 0



   .. py:attribute:: closed
      :type:  int
      :value: 0



   .. py:attribute:: archived
      :type:  int
      :value: 0



.. py:class:: TicketCollection(session: sqlalchemy.orm.Session, page: int = 0, state: ExtendedTicketState = 'open', handler: str = 'ALL', group: str | None = None, owner: str = '*', extra_parameters: dict[str, Any] | None = None)

   Bases: :py:obj:`TicketCollectionPagination`


   Provides collections with pagination, if they implement a few
   documented properties and methods.

   See :class:`onegov.ticket.TicketCollection` for an example.



   .. py:method:: query() -> sqlalchemy.orm.Query[onegov.ticket.model.Ticket]


   .. py:method:: random_number(length: int) -> int


   .. py:method:: random_ticket_number(handler_code: str) -> str


   .. py:method:: is_existing_ticket_number(ticket_number: str) -> bool


   .. py:method:: issue_unique_ticket_number(handler_code: str) -> str

      Randomly generates a new ticket number, ensuring it is unique
      for the given handler_code.

      The resulting code is of the following form::

          XXX-0000-1111

      Where ``XXX`` is the handler_code and the rest is a 12 character
      sequence of random numbers separated by dashes.

      This gives us 10^8 or 100 million ticket numbers for each handler.

      Though we'll never reach that limit, there is an increasing chance
      of conflict with existing ticket numbers, so we have to check
      against the database.

      Still, this number is not unguessable (say in an URL) - there we have
      to rely on the internal ticket id, which is a uuid.

      In a social engineering setting, where we don't have the abilty to
      quickly try out thousands of numbers, the ticket number should
      be pretty unguessable however.




   .. py:method:: open_ticket(handler_code: str, handler_id: str, **handler_data: Any) -> onegov.ticket.model.Ticket

      Opens a new ticket using the given handler. 



   .. py:method:: by_handler_code(handler_code: str) -> list[onegov.ticket.model.Ticket]


   .. py:method:: by_id(id: uuid.UUID, ensure_handler_code: str | None = None) -> onegov.ticket.model.Ticket | None


   .. py:method:: by_handler_id(handler_id: str) -> onegov.ticket.model.Ticket | None


   .. py:method:: get_count(excl_archived: bool = True) -> TicketCount


   .. py:method:: by_handler_data_id(handler_data_id: str | uuid.UUID) -> sqlalchemy.orm.Query[onegov.ticket.model.Ticket]


.. py:class:: ArchivedTicketCollection(session: sqlalchemy.orm.Session, page: int = 0, state: ExtendedTicketState = 'open', handler: str = 'ALL', group: str | None = None, owner: str = '*', extra_parameters: dict[str, Any] | None = None)

   Bases: :py:obj:`TicketCollectionPagination`


   Provides collections with pagination, if they implement a few
   documented properties and methods.

   See :class:`onegov.ticket.TicketCollection` for an example.



   .. py:method:: query() -> sqlalchemy.orm.Query[onegov.ticket.model.Ticket]