notice.collections
==================

.. py:module:: notice.collections


Attributes
----------

.. autoapisummary::

   notice.collections._StrColumnLike
   notice.collections._N


Classes
-------

.. autoapisummary::

   notice.collections.OfficialNoticeCollection


Functions
---------

.. autoapisummary::

   notice.collections.get_unique_notice_name


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

.. py:type:: _StrColumnLike
   :canonical: ColumnElement[str] | ColumnElement[str | None] | ColumnElement[Markup] | ColumnElement[Markup | None]


.. py:data:: _N

.. py:function:: get_unique_notice_name(name: str, session: sqlalchemy.orm.Session, model_class: type[onegov.notice.models.OfficialNotice]) -> str

   Create a unique, URL-friendly name. 


.. py:class:: OfficialNoticeCollection(session: sqlalchemy.orm.Session, page: int = 0, state: onegov.notice.models.NoticeState | None = None, term: str | None = None, order: str | None = None, direction: Literal['asc', 'desc'] | None = None, issues: collections.abc.Collection[str] | None = None, categories: collections.abc.Collection[str] | None = None, organizations: collections.abc.Collection[str] | None = None, user_ids: list[uuid.UUID] | None = None, group_ids: list[uuid.UUID] | None = None)

   Bases: :py:obj:`onegov.core.collection.Pagination`\ [\ :py:obj:`_N`\ ]


   Manage a list of official notices. 


   .. py:attribute:: session


   .. py:attribute:: state
      :value: None



   .. py:attribute:: term
      :value: None



   .. py:attribute:: order
      :value: 'first_issue'



   .. py:attribute:: direction
      :value: 'asc'



   .. py:attribute:: issues
      :value: None



   .. py:attribute:: categories
      :value: None



   .. py:attribute:: organizations
      :value: None



   .. py:attribute:: user_ids
      :value: []



   .. py:attribute:: group_ids
      :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[_N]

      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:: for_state(state: onegov.notice.models.NoticeState) -> Self

      Returns a new instance of the collection with the given state. 



   .. py:method:: for_term(term: str | None) -> Self

      Returns a new instance of the collection with the given term. 



   .. py:method:: for_order(order: str, direction: Literal['asc', 'desc'] | None = None) -> Self

      Returns a new instance of the collection with the given ordering.
      Inverts the direction if the new ordering is the same as the old one
      and an explicit ordering is not defined.




   .. py:method:: for_organizations(organizations: collections.abc.Collection[str] | None) -> Self

      Returns a new instance of the collection with the given
      organizations.




   .. py:method:: for_categories(categories: collections.abc.Collection[str] | None) -> Self

      Returns a new instance of the collection with the given categories.

              



   .. py:property:: model_class
      :type: type[_N]



   .. py:property:: term_columns
      :type: list[_StrColumnLike]


      The columns used for full text search. 



   .. py:method:: filter_query(query: sqlalchemy.orm.Query[_N]) -> sqlalchemy.orm.Query[_N]

      Filters the given query by the state of the collection. 



   .. py:method:: order_query(query: sqlalchemy.orm.Query[_N]) -> sqlalchemy.orm.Query[_N]

      Orders the given query by the state of the collection. 



   .. py:method:: query() -> sqlalchemy.orm.Query[_N]

      Returns a filtered and sorted query.

      Filters by:
      - notice.state matches state
      - notice.user_id is in user_ids
      - notice.group_id is in group_ids
      - notice.issues has any of the issues
      - term is in title, text, category, organization, groupname, usernames

      Orders by:
      - any notice columns
      - group name (group.name)
      - users real name (user.realname)
      - username (user.username)
      - username or users real name (user.name)




   .. py:method:: _get_unique_name(name: str) -> str

      Create a unique, URL-friendly name. 



   .. py:method:: add(title: str, text: str | None, **optional: Any) -> _N

      Add a new notice.

      A unique, URL-friendly name is created automatically for this notice
      using the title and optionally numbers for duplicate names.

      Returns the created notice.



   .. py:method:: delete(notice: onegov.notice.models.OfficialNotice) -> None

      Delete an notice. 



   .. py:method:: by_name(name: str) -> _N | None

      Returns a notice by its URL-friendly name. 



   .. py:method:: by_id(id: uuid.UUID) -> _N | None

      Returns a notice by its id.