org.api
=======

.. py:module:: org.api


Classes
-------

.. autoapisummary::

   org.api.EventApiEndpoint
   org.api.NewsApiEndpoint
   org.api.TopicApiEndpoint
   org.api.DirectoryEntryApiEndpoint


Functions
---------

.. autoapisummary::

   org.api.get_geo_location
   org.api.get_modified_iso_format
   org.api.format_multiple_choice_prompt


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

.. py:function:: get_geo_location(item: onegov.core.orm.mixins.ContentMixin) -> dict[str, Any]

.. py:function:: get_modified_iso_format(item: onegov.core.orm.mixins.TimestampMixin) -> str

   Returns the iso format of the modified or created field of item.

   :param item: db item e.g. agency, people, membership
   :return: str iso representation of item last modification


.. py:function:: format_multiple_choice_prompt(choices: collections.abc.Collection[str] | None) -> str | None

.. py:class:: EventApiEndpoint(request: onegov.core.request.CoreRequest, extra_parameters: dict[str, list[str]] | None = None, page: int | None = None)

   Bases: :py:obj:`onegov.api.models.ApiEndpoint`\ [\ :py:obj:`onegov.event.models.Occurrence`\ ]


   An API endpoint.

   API endpoints wrap collection and do some filter mapping.

   To add a new endpoint, inherit from this class and provide the missing
   functions and properties at the bottom. Note that the collection is
   expected to be to provide the functionality of
   ``onegov.core.collection.Pagination``.



   .. py:attribute:: app
      :type:  onegov.org.app.OrgApp


   .. py:attribute:: endpoint
      :value: 'events'



   .. py:property:: filters
      :type: collections.abc.Mapping[str, collections.abc.Collection[str] | str | None]


      A mapping of the available filter params to their corresponding
      description or a collection of possible values. If possible values
      are specified it is assumed that the filter can be specfied multiple
      times.

      The description is optional and should only be used for non-trivial
      filters that don't just accept arbitrary strings.




   .. py:property:: title
      :type: str


      Return a human readable title for this endpoint 



   .. py:property:: description
      :type: str | None


      Return a human readable description for this endpoint 



   .. py:property:: _base_collection
      :type: onegov.event.collections.OccurrenceCollection



   .. py:method:: get_date_filter(key: str, values: list[str]) -> datetime.date | None


   .. py:property:: collection
      :type: onegov.event.collections.OccurrenceCollection


      Return an instance of the collection with filters and page set.
              



   .. py:method:: item_data(item: onegov.event.models.Occurrence) -> dict[str, Any]

      Return the data properties of the collection item as a dictionary.

      For example::

          {
              'name': 'Paul',
              'age': 40
          }




   .. py:method:: item_links(item: onegov.event.models.Occurrence) -> dict[str, Any]

      Return the link properties of the collection item as a dictionary.
      Links can either be string or a linkable object.

      For example::

          {
              'website': 'https://onegov.ch',
              'friends': FriendsApiEndpoint(app).for_item(paul),
              'home': ApiEndpointCollection(app)
          }




.. py:class:: NewsApiEndpoint(request: onegov.core.request.CoreRequest, extra_parameters: dict[str, list[str]] | None = None, page: int | None = None)

   Bases: :py:obj:`onegov.api.models.ApiEndpoint`\ [\ :py:obj:`onegov.org.models.page.News`\ ]


   An API endpoint.

   API endpoints wrap collection and do some filter mapping.

   To add a new endpoint, inherit from this class and provide the missing
   functions and properties at the bottom. Note that the collection is
   expected to be to provide the functionality of
   ``onegov.core.collection.Pagination``.



   .. py:attribute:: app
      :type:  onegov.org.app.OrgApp


   .. py:attribute:: endpoint
      :value: 'news'



   .. py:property:: title
      :type: str


      Return a human readable title for this endpoint 



   .. py:property:: collection
      :type: Any


      Return an instance of the collection with filters and page set.
              



   .. py:method:: item_data(item: onegov.org.models.page.News) -> dict[str, Any]

      Return the data properties of the collection item as a dictionary.

      For example::

          {
              'name': 'Paul',
              'age': 40
          }




   .. py:method:: item_links(item: onegov.org.models.page.News) -> dict[str, Any]

      Return the link properties of the collection item as a dictionary.
      Links can either be string or a linkable object.

      For example::

          {
              'website': 'https://onegov.ch',
              'friends': FriendsApiEndpoint(app).for_item(paul),
              'home': ApiEndpointCollection(app)
          }




.. py:class:: TopicApiEndpoint(request: onegov.core.request.CoreRequest, extra_parameters: dict[str, list[str]] | None = None, page: int | None = None)

   Bases: :py:obj:`onegov.api.models.ApiEndpoint`\ [\ :py:obj:`onegov.org.models.page.Topic`\ ]


   An API endpoint.

   API endpoints wrap collection and do some filter mapping.

   To add a new endpoint, inherit from this class and provide the missing
   functions and properties at the bottom. Note that the collection is
   expected to be to provide the functionality of
   ``onegov.core.collection.Pagination``.



   .. py:attribute:: request
      :type:  onegov.org.request.OrgRequest


   .. py:attribute:: app
      :type:  onegov.org.app.OrgApp


   .. py:attribute:: endpoint
      :value: 'topics'



   .. py:property:: title
      :type: str


      Return a human readable title for this endpoint 



   .. py:property:: collection
      :type: Any


      Return an instance of the collection with filters and page set.
              



   .. py:method:: item_data(item: onegov.org.models.page.Topic) -> dict[str, Any]

      Return the data properties of the collection item as a dictionary.

      For example::

          {
              'name': 'Paul',
              'age': 40
          }




   .. py:method:: item_links(item: onegov.org.models.page.Topic) -> dict[str, Any]

      Return the link properties of the collection item as a dictionary.
      Links can either be string or a linkable object.

      For example::

          {
              'website': 'https://onegov.ch',
              'friends': FriendsApiEndpoint(app).for_item(paul),
              'home': ApiEndpointCollection(app)
          }




.. py:class:: DirectoryEntryApiEndpoint(request: onegov.org.request.OrgRequest, name: str, extra_parameters: dict[str, list[str]] | None = None, page: int | None = None)

   Bases: :py:obj:`onegov.api.models.ApiEndpoint`\ [\ :py:obj:`onegov.org.models.directory.ExtendedDirectoryEntry`\ ]


   An API endpoint.

   API endpoints wrap collection and do some filter mapping.

   To add a new endpoint, inherit from this class and provide the missing
   functions and properties at the bottom. Note that the collection is
   expected to be to provide the functionality of
   ``onegov.core.collection.Pagination``.



   .. py:attribute:: request
      :type:  onegov.org.request.OrgRequest


   .. py:attribute:: app
      :type:  onegov.org.app.OrgApp


   .. py:attribute:: endpoint
      :type:  str


   .. py:property:: title
      :type: str


      Return a human readable title for this endpoint 



   .. py:property:: description
      :type: str | None


      Return a human readable description for this endpoint 



   .. py:property:: directory
      :type: onegov.org.models.directory.ExtendedDirectory



   .. py:property:: collection
      :type: Any


      Return an instance of the collection with filters and page set.
              



   .. py:method:: for_page(page: int | None) -> DirectoryEntryApiEndpoint

      Return a new endpoint instance with the given page while keeping
      the current filters.




   .. py:method:: for_filter(**filters: Any) -> Self

      Return a new endpoint instance with the given filters while
      discarding the current filters and page.




   .. py:method:: by_id(id: onegov.core.collection.PKType) -> onegov.org.models.directory.ExtendedDirectoryEntry | None

      Return the item with the given ID from the collection. 



   .. py:method:: item_data(item: onegov.org.models.directory.ExtendedDirectoryEntry) -> dict[str, Any]

      Return the data properties of the collection item as a dictionary.

      For example::

          {
              'name': 'Paul',
              'age': 40
          }




   .. py:method:: item_links(item: onegov.org.models.directory.ExtendedDirectoryEntry) -> dict[str, Any]

      Return the link properties of the collection item as a dictionary.
      Links can either be string or a linkable object.

      For example::

          {
              'website': 'https://onegov.ch',
              'friends': FriendsApiEndpoint(app).for_item(paul),
              'home': ApiEndpointCollection(app)
          }