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

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


Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/autoapi/httk/serve/web/api/index
   /reference/autoapi/httk/serve/web/cli/index
   /reference/autoapi/httk/serve/web/compat/index
   /reference/autoapi/httk/serve/web/engine/index
   /reference/autoapi/httk/serve/web/functions/index
   /reference/autoapi/httk/serve/web/model/index
   /reference/autoapi/httk/serve/web/providers/index
   /reference/autoapi/httk/serve/web/publishing/index
   /reference/autoapi/httk/serve/web/renderers/index
   /reference/autoapi/httk/serve/web/resources/index
   /reference/autoapi/httk/serve/web/runtime/index
   /reference/autoapi/httk/serve/web/templating/index
   /reference/autoapi/httk/serve/web/widgets/index


Attributes
----------

.. autoapisummary::

   httk.serve.web.SITE_RESOURCES_KEY


Classes
-------

.. autoapisummary::

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


Functions
---------

.. autoapisummary::

   httk.serve.web.create_asgi_app
   httk.serve.web.publish
   httk.serve.web.serve


Package Contents
----------------

.. py:function:: create_asgi_app(srcdir: str | pathlib.Path, *, baseurl: str | None = None, compatibility_mode: bool = False, config_name: str = 'config', debug: bool = False, table_token_secret: str | bytes | None = None) -> starlette.applications.Starlette

.. py:function:: publish(srcdir: str | pathlib.Path, outdir: str | pathlib.Path, baseurl: str, *, host_static: str | None = None, compatibility_mode: bool = False, config_name: str = 'config', use_urls_without_ext: bool | None = None) -> httk.serve.web.model.page.PublishReport

.. py:function:: serve(srcdir: str | pathlib.Path, *, host: str = '127.0.0.1', port: int = 8080, baseurl: str | None = None, compatibility_mode: bool = False, config_name: str = 'config', debug: bool = False, table_token_secret: str | bytes | None = None) -> None

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



.. 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:data:: SITE_RESOURCES_KEY
   :value: 'httk_serve_resources'


   Stable ``global_data`` key through which site startup code gets resources.

.. py:class:: SiteResources

   Callbacks owned by one :class:`httk.serve.web.engine.site_engine.SiteEngine`.

   Site ``functions/init.py`` code can obtain this object from
   ``global_data[SITE_RESOURCES_KEY]`` and call :meth:`register` for every
   persistent resource it opens.  Callbacks run in reverse registration order
   when the :class:`httk.serve.web.engine.site_engine.SiteEngine` closes.  Closing is
   idempotent, so ASGI lifespan shutdown and an enclosing helper may both
   safely close the same engine.


   .. py:property:: closed
      :type: bool


      Whether cleanup has started for this registry.


   .. py:method:: register(callback: CleanupCallback) -> None

      Register one synchronous callback to run during :meth:`close`.

      Registration after close is a programming error: the callback could no
      longer be guaranteed to run.



   .. py:method:: close() -> None

      Run pending callbacks in LIFO order exactly once.

      Every callback gets a chance to run.  If cleanup fails, the first
      exception is re-raised after the remaining callbacks have executed;
      additional failures are attached as notes for diagnosis.