httk.serve.web.providers
========================

.. py:module:: httk.serve.web.providers

.. autoapi-nested-parse::

   Small, dependency-free contracts for site-local paginated data providers.



Attributes
----------

.. autoapisummary::

   httk.serve.web.providers.MAX_CURSOR_CHARS
   httk.serve.web.providers.MAX_ROW_DATA_BYTES


Classes
-------

.. autoapisummary::

   httk.serve.web.providers.ProviderContext
   httk.serve.web.providers.TableRequest
   httk.serve.web.providers.TableColumn
   httk.serve.web.providers.TablePage


Functions
---------

.. autoapisummary::

   httk.serve.web.providers.immutable_mapping


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

.. py:data:: MAX_CURSOR_CHARS
   :value: 16384


.. py:data:: MAX_ROW_DATA_BYTES
   :value: 512000


.. py:function:: immutable_mapping(values: collections.abc.Mapping[str, object]) -> collections.abc.Mapping[str, object]

   Take a recursively immutable snapshot suitable for provider context.


.. py:class:: ProviderContext

   The immutable, site-local context passed to a table provider.


   .. py:attribute:: route
      :type:  str


   .. py:attribute:: widget_id
      :type:  str


   .. py:attribute:: query
      :type:  collections.abc.Mapping[str, str]


   .. py:attribute:: page
      :type:  collections.abc.Mapping[str, object]


   .. py:attribute:: global_data
      :type:  collections.abc.Mapping[str, object]


   .. py:method:: url_for(route: str, *, query: collections.abc.Mapping[str, str] | None = None) -> str

      Build a site-local route URL without exposing the ASGI request.



.. py:class:: TableRequest

   The bounded page request passed to ``provide(context, request, ...)``.


   .. py:attribute:: page_size
      :type:  int
      :value: 50



   .. py:attribute:: cursor
      :type:  str | None
      :value: None



   .. py:attribute:: revision
      :type:  str | None
      :value: None



.. py:class:: TableColumn

   A table column and its small, presentation-only metadata.


   .. py:attribute:: key
      :type:  str


   .. py:attribute:: label
      :type:  str


   .. py:attribute:: align
      :type:  str | None
      :value: None



   .. py:attribute:: class_name
      :type:  str | None
      :value: None



   .. py:method:: from_value(value: Self | str | collections.abc.Mapping[str, object]) -> Self
      :classmethod:


      Adapt the compact forms useful in small, site-local providers.



.. py:class:: TablePage

   One provider-owned page of structured rows and opaque navigation cursors.


   .. py:attribute:: rows
      :type:  tuple[collections.abc.Mapping[str, object], Ellipsis]


   .. py:attribute:: columns
      :type:  tuple[TableColumn, Ellipsis]


   .. py:attribute:: next_cursor
      :type:  str | None
      :value: None



   .. py:attribute:: previous_cursor
      :type:  str | None
      :value: None



   .. py:attribute:: total
      :type:  int | None
      :value: None



   .. py:attribute:: revision
      :type:  str | None
      :value: None



   .. py:method:: from_rows(rows: collections.abc.Iterable[collections.abc.Mapping[str, object]], *, columns: collections.abc.Iterable[TableColumn | str | collections.abc.Mapping[str, object]], next_cursor: str | None = None, previous_cursor: str | None = None, total: int | None = None, revision: str | None = None) -> Self
      :classmethod:


      Construct a page while adapting compact column declarations.



   .. py:method:: from_result(value: object) -> Self
      :classmethod:


      Accept a :class:`TablePage` or the equivalent explicit mapping.