server.application
==================

.. py:module:: server.application


Classes
-------

.. autoapisummary::

   server.application.Application


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

.. py:class:: Application

   WSGI applications inheriting from this class can be served by
   onegov.server.



   .. py:attribute:: allowed_hosts_expression
      :type:  re.Pattern[str] | None
      :value: None



   .. py:attribute:: allowed_hosts
      :type:  set[str]


   .. py:attribute:: namespace
      :type:  str


   .. py:attribute:: _aliases
      :type:  dict[str, str]


   .. py:method:: __call__(environ: _typeshed.wsgi.WSGIEnvironment, start_respnose: _typeshed.wsgi.StartResponse) -> collections.abc.Iterable[bytes]
      :abstractmethod:



   .. py:method:: configure_application(**configuration: Any) -> None

      Called *once* when the application is instantiated, with the
      configuration values defined for this application.

      This will be called *before* :meth:`set_application_base_path` is
      called, as this happens *before* the request.

      Be sure to call this method from any subclasses you create. The server
      adds its own configuration here!




   .. py:method:: set_application_id(application_id: str) -> None

      Sets the application id before __call__ is called. That is, before
      each request.

      The application id consists of two values, delimitd by a '/'. The first
      value is the namespace of the application, the second value is the
      last fragment of the base_path.

      That is `namespace/app` for all requests in the following config::

          {
              'applications': [
                  {
                      path: '/app',
                      namespace: 'namespace'
                  }
              ]
          }

      And `namespace/blog` for a `/sites/blog` request in the following
      config::

          {
              'applications': [
                  {
                      path: '/sites/*',
                      namespace: 'namespace'
                  }
              ]
          }



   .. py:method:: set_application_base_path(base_path: str) -> None

      Sets the base path of the application before __call__ is called.
      That is, before each request.

      The base_path of static applications is equal to path the application
      was configured to run under.

      The base_path of wildcard applications includes the path matched
      by the wildcard. For example, if the application is configured to run
      under `/sites/*`, the base_path would be `/sites/blog` if
      `/sites/blog/login` was requested.




   .. py:method:: is_allowed_hostname(hostname: str) -> bool

      Called at least once per request with the given hostname.

      If True is returned, the request with the given hostname is allowed.
      If False is returned, the request is denied.

      You usually won't need to override this method, as
      :attr:`allowed_hosts_expression` and :attr:`allowed_hosts` already
      gives you a way to influence its behavior.

      If you do override, it's all on you though (except for localhost
      requests).



   .. py:method:: is_allowed_application_id(application_id: str) -> bool

      Called at least once per request with the given application id.

      If True is returned, the request with the given application_id is
      allowed. If False is returned, the request is denied.

      By default, all application ids are allowed.




   .. py:method:: alias(application_id: str, alias: str) -> None

      Adds an alias under which this application is available on the
      server.

      The alias only works for wildcard applications - it has no effect
      on static applications!

      This is how it works:

      An application running under `/sites/main` can be made available
      under `/sites/blog` by running `self.alias('main', 'blog')`.

      Aliases must be unique, so this method will fail with a
      :class:`onegov.server.errors.ApplicationConflictError` if an alias
      is already in use by another application running under the same path.

      Note that an application opened through an alias will still have
      the application_id set to the actual root, not the alias. So
      `/sites/blog` in the example above would still lead to an
      application_id of `main` instead of `blog`.

      This is mainly meant to be used for dynamic DNS setups. Say you have
      an application available through test.onegov.dev (pointing to
      `/sites/test`). You now want to make this site available through
      example.org. You can do this as follows::

          self.allowed_hosts.add('example.org')
          self.alias('example_org')

      If your server has a catch-all rule that sends unknown domains to
      `/sites/domain_without_dots`, then you can add domains dynamically
      and the customer just points the DNS to your ip address.



   .. py:method:: handle_exception(exception: BaseException, environ: _typeshed.wsgi.WSGIEnvironment, start_response: _typeshed.wsgi.StartResponse) -> collections.abc.Iterable[bytes]

      Default exception handling - this can be used to return a different
      response when an unhandled exception occurs inside a request or before
      a request is handled by the application (when any of the above methods
      are called).

      By default we just raise the exception.

      Typically, returning an error is what you might want to do::

          def handle_exception(exception, environ, start_response):
              if isinstance(exception, UnderMaintenanceError):
                  error = webob.exc.HTTPInternalServerError()
                  return error(environ, start_response)