move ASGIAdoptor out of v1 module

src/nominatim_api/server/asgi_adaptor.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This file is part of Nominatim. (https://nominatim.org)
+#
+# Copyright (C) 2024 by the Nominatim developer community.
+# For a full list of authors see the git log.
+"""
+Base abstraction for implementing based on different ASGI frameworks.
+"""
+from typing import Optional, Any, NoReturn, Callable
+import abc
+import math
+
+from ..config import Configuration
+from .. import logging as loglib
+from ..core import NominatimAPIAsync
+
+CONTENT_TEXT = 'text/plain; charset=utf-8'
+CONTENT_XML = 'text/xml; charset=utf-8'
+CONTENT_HTML = 'text/html; charset=utf-8'
+CONTENT_JSON = 'application/json; charset=utf-8'
+
+CONTENT_TYPE = {'text': CONTENT_TEXT, 'xml': CONTENT_XML, 'debug': CONTENT_HTML}
+
+class ASGIAdaptor(abc.ABC):
+    """ Adapter class for the different ASGI frameworks.
+        Wraps functionality over concrete requests and responses.
+    """
+    content_type: str = CONTENT_TEXT
+
+    @abc.abstractmethod
+    def get(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """ Return an input parameter as a string. If the parameter was
+            not provided, return the 'default' value.
+        """
+
+    @abc.abstractmethod
+    def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """ Return a HTTP header parameter as a string. If the parameter was
+            not provided, return the 'default' value.
+        """
+
+
+    @abc.abstractmethod
+    def error(self, msg: str, status: int = 400) -> Exception:
+        """ Construct an appropriate exception from the given error message.
+            The exception must result in a HTTP error with the given status.
+        """
+
+
+    @abc.abstractmethod
+    def create_response(self, status: int, output: str, num_results: int) -> Any:
+        """ Create a response from the given parameters. The result will
+            be returned by the endpoint functions. The adaptor may also
+            return None when the response is created internally with some
+            different means.
+
+            The response must return the HTTP given status code 'status', set
+            the HTTP content-type headers to the string provided and the
+            body of the response to 'output'.
+        """
+
+    @abc.abstractmethod
+    def base_uri(self) -> str:
+        """ Return the URI of the original request.
+        """
+
+
+    @abc.abstractmethod
+    def config(self) -> Configuration:
+        """ Return the current configuration object.
+        """
+
+
+    def get_int(self, name: str, default: Optional[int] = None) -> int:
+        """ Return an input parameter as an int. Raises an exception if
+            the parameter is given but not in an integer format.
+
+            If 'default' is given, then it will be returned when the parameter
+            is missing completely. When 'default' is None, an error will be
+            raised on a missing parameter.
+        """
+        value = self.get(name)
+
+        if value is None:
+            if default is not None:
+                return default
+
+            self.raise_error(f"Parameter '{name}' missing.")
+
+        try:
+            intval = int(value)
+        except ValueError:
+            self.raise_error(f"Parameter '{name}' must be a number.")
+
+        return intval
+
+
+    def get_float(self, name: str, default: Optional[float] = None) -> float:
+        """ Return an input parameter as a flaoting-point number. Raises an
+            exception if the parameter is given but not in an float format.
+
+            If 'default' is given, then it will be returned when the parameter
+            is missing completely. When 'default' is None, an error will be
+            raised on a missing parameter.
+        """
+        value = self.get(name)
+
+        if value is None:
+            if default is not None:
+                return default
+
+            self.raise_error(f"Parameter '{name}' missing.")
+
+        try:
+            fval = float(value)
+        except ValueError:
+            self.raise_error(f"Parameter '{name}' must be a number.")
+
+        if math.isnan(fval) or math.isinf(fval):
+            self.raise_error(f"Parameter '{name}' must be a number.")
+
+        return fval
+
+
+    def get_bool(self, name: str, default: Optional[bool] = None) -> bool:
+        """ Return an input parameter as bool. Only '0' is accepted as
+            an input for 'false' all other inputs will be interpreted as 'true'.
+
+            If 'default' is given, then it will be returned when the parameter
+            is missing completely. When 'default' is None, an error will be
+            raised on a missing parameter.
+        """
+        value = self.get(name)
+
+        if value is None:
+            if default is not None:
+                return default
+
+            self.raise_error(f"Parameter '{name}' missing.")
+
+        return value != '0'
+
+
+    def raise_error(self, msg: str, status: int = 400) -> NoReturn:
+        """ Raise an exception resulting in the given HTTP status and
+            message. The message will be formatted according to the
+            output format chosen by the request.
+        """
+        if self.content_type == CONTENT_XML:
+            msg = f"""<?xml version="1.0" encoding="UTF-8" ?>
+                      <error>
+                        <code>{status}</code>
+                        <message>{msg}</message>
+                      </error>
+                   """
+        elif self.content_type == CONTENT_JSON:
+            msg = f"""{{"error":{{"code":{status},"message":"{msg}"}}}}"""
+        elif self.content_type == CONTENT_HTML:
+            loglib.log().section('Execution error')
+            loglib.log().var_dump('Status', status)
+            loglib.log().var_dump('Message', msg)
+            msg = loglib.get_and_disable()
+
+        raise self.error(msg, status)
+
+
+EndpointFunc = Callable[[NominatimAPIAsync, ASGIAdaptor], Any]

src/nominatim_api/server/falcon/server.py

@@ -18,6 +18,7 @@ from ...config import Configuration
 from ...core import NominatimAPIAsync
 from ... import v1 as api_impl
 from ... import logging as loglib
+from ..asgi_adaptor import ASGIAdaptor, EndpointFunc
 
 class HTTPNominatimError(Exception):
     """ A special exception class for errors raised during processing.
@@ -57,7 +58,7 @@ async def timeout_error_handler(req: Request, resp: Response, #pylint: disable=u
         resp.content_type = 'text/plain; charset=utf-8'
 
 
-class ParamWrapper(api_impl.ASGIAdaptor):
+class ParamWrapper(ASGIAdaptor):
     """ Adaptor class for server glue to Falcon framework.
     """
 
@@ -98,7 +99,7 @@ class EndpointWrapper:
     """ Converter for server glue endpoint functions to Falcon request handlers.
     """
 
-    def __init__(self, name: str, func: api_impl.EndpointFunc, api: NominatimAPIAsync) -> None:
+    def __init__(self, name: str, func: EndpointFunc, api: NominatimAPIAsync) -> None:
         self.name = name
         self.func = func
         self.api = api

src/nominatim_api/server/starlette/server.py

@@ -24,9 +24,10 @@ from starlette.middleware.cors import CORSMiddleware
 from ...config import Configuration
 from ...core import NominatimAPIAsync
 from ... import v1 as api_impl
+from ..asgi_adaptor import ASGIAdaptor, EndpointFunc
 from ... import logging as loglib
 
-class ParamWrapper(api_impl.ASGIAdaptor):
+class ParamWrapper(ASGIAdaptor):
     """ Adaptor class for server glue to Starlette framework.
     """
 
@@ -69,7 +70,7 @@ class ParamWrapper(api_impl.ASGIAdaptor):
         return cast(Configuration, self.request.app.state.API.config)
 
 
-def _wrap_endpoint(func: api_impl.EndpointFunc)\
+def _wrap_endpoint(func: EndpointFunc)\
         -> Callable[[Request], Coroutine[Any, Any, Response]]:
     async def _callback(request: Request) -> Response:
         return cast(Response, await func(request.app.state.API, ParamWrapper(request)))

src/nominatim_api/v1/__init__.py

@@ -10,9 +10,7 @@ Implementation of API version v1 (aka the legacy version).
 
 #pylint: disable=useless-import-alias
 
-from .server_glue import (ASGIAdaptor as ASGIAdaptor,
+from .server_glue import ROUTES as ROUTES
-                          EndpointFunc as EndpointFunc,
-                          ROUTES as ROUTES)
 
 from . import format as _format
 

src/nominatim_api/v1/server_glue.py

@@ -8,17 +8,14 @@
 Generic part of the server implementation of the v1 API.
 Combine with the scaffolding provided for the various Python ASGI frameworks.
 """
-from typing import Optional, Any, Type, Callable, NoReturn, Dict, cast
+from typing import Optional, Any, Type, Dict, cast
 from functools import reduce
-import abc
 import dataclasses
-import math
 from urllib.parse import urlencode
 
 import sqlalchemy as sa
 
 from ..errors import UsageError
-from ..config import Configuration
 from .. import logging as loglib
 from ..core import NominatimAPIAsync
 from .format import dispatch as formatting
@@ -28,156 +25,7 @@ from ..status import StatusResult
 from ..results import DetailedResult, ReverseResults, SearchResult, SearchResults
 from ..localization import Locales
 from . import helpers
-
+from ..server.asgi_adaptor import CONTENT_HTML, CONTENT_JSON, CONTENT_TYPE, ASGIAdaptor
-CONTENT_TEXT = 'text/plain; charset=utf-8'
-CONTENT_XML = 'text/xml; charset=utf-8'
-CONTENT_HTML = 'text/html; charset=utf-8'
-CONTENT_JSON = 'application/json; charset=utf-8'
-
-CONTENT_TYPE = {'text': CONTENT_TEXT, 'xml': CONTENT_XML, 'debug': CONTENT_HTML}
-
-class ASGIAdaptor(abc.ABC):
-    """ Adapter class for the different ASGI frameworks.
-        Wraps functionality over concrete requests and responses.
-    """
-    content_type: str = CONTENT_TEXT
-
-    @abc.abstractmethod
-    def get(self, name: str, default: Optional[str] = None) -> Optional[str]:
-        """ Return an input parameter as a string. If the parameter was
-            not provided, return the 'default' value.
-        """
-
-    @abc.abstractmethod
-    def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]:
-        """ Return a HTTP header parameter as a string. If the parameter was
-            not provided, return the 'default' value.
-        """
-
-
-    @abc.abstractmethod
-    def error(self, msg: str, status: int = 400) -> Exception:
-        """ Construct an appropriate exception from the given error message.
-            The exception must result in a HTTP error with the given status.
-        """
-
-
-    @abc.abstractmethod
-    def create_response(self, status: int, output: str, num_results: int) -> Any:
-        """ Create a response from the given parameters. The result will
-            be returned by the endpoint functions. The adaptor may also
-            return None when the response is created internally with some
-            different means.
-
-            The response must return the HTTP given status code 'status', set
-            the HTTP content-type headers to the string provided and the
-            body of the response to 'output'.
-        """
-
-    @abc.abstractmethod
-    def base_uri(self) -> str:
-        """ Return the URI of the original request.
-        """
-
-
-    @abc.abstractmethod
-    def config(self) -> Configuration:
-        """ Return the current configuration object.
-        """
-
-
-    def get_int(self, name: str, default: Optional[int] = None) -> int:
-        """ Return an input parameter as an int. Raises an exception if
-            the parameter is given but not in an integer format.
-
-            If 'default' is given, then it will be returned when the parameter
-            is missing completely. When 'default' is None, an error will be
-            raised on a missing parameter.
-        """
-        value = self.get(name)
-
-        if value is None:
-            if default is not None:
-                return default
-
-            self.raise_error(f"Parameter '{name}' missing.")
-
-        try:
-            intval = int(value)
-        except ValueError:
-            self.raise_error(f"Parameter '{name}' must be a number.")
-
-        return intval
-
-
-    def get_float(self, name: str, default: Optional[float] = None) -> float:
-        """ Return an input parameter as a flaoting-point number. Raises an
-            exception if the parameter is given but not in an float format.
-
-            If 'default' is given, then it will be returned when the parameter
-            is missing completely. When 'default' is None, an error will be
-            raised on a missing parameter.
-        """
-        value = self.get(name)
-
-        if value is None:
-            if default is not None:
-                return default
-
-            self.raise_error(f"Parameter '{name}' missing.")
-
-        try:
-            fval = float(value)
-        except ValueError:
-            self.raise_error(f"Parameter '{name}' must be a number.")
-
-        if math.isnan(fval) or math.isinf(fval):
-            self.raise_error(f"Parameter '{name}' must be a number.")
-
-        return fval
-
-
-    def get_bool(self, name: str, default: Optional[bool] = None) -> bool:
-        """ Return an input parameter as bool. Only '0' is accepted as
-            an input for 'false' all other inputs will be interpreted as 'true'.
-
-            If 'default' is given, then it will be returned when the parameter
-            is missing completely. When 'default' is None, an error will be
-            raised on a missing parameter.
-        """
-        value = self.get(name)
-
-        if value is None:
-            if default is not None:
-                return default
-
-            self.raise_error(f"Parameter '{name}' missing.")
-
-        return value != '0'
-
-
-    def raise_error(self, msg: str, status: int = 400) -> NoReturn:
-        """ Raise an exception resulting in the given HTTP status and
-            message. The message will be formatted according to the
-            output format chosen by the request.
-        """
-        if self.content_type == CONTENT_XML:
-            msg = f"""<?xml version="1.0" encoding="UTF-8" ?>
-                      <error>
-                        <code>{status}</code>
-                        <message>{msg}</message>
-                      </error>
-                   """
-        elif self.content_type == CONTENT_JSON:
-            msg = f"""{{"error":{{"code":{status},"message":"{msg}"}}}}"""
-        elif self.content_type == CONTENT_HTML:
-            loglib.log().section('Execution error')
-            loglib.log().var_dump('Status', status)
-            loglib.log().var_dump('Message', msg)
-            msg = loglib.get_and_disable()
-
-        raise self.error(msg, status)
-
 
 def build_response(adaptor: ASGIAdaptor, output: str, status: int = 200,
                    num_results: int = 0) -> Any:
@@ -565,8 +413,6 @@ async def polygons_endpoint(api: NominatimAPIAsync, params: ASGIAdaptor) -> Any:
     return build_response(params, formatting.format_result(results, fmt, {}))
 
 
-EndpointFunc = Callable[[NominatimAPIAsync, ASGIAdaptor], Any]
-
 ROUTES = [
     ('status', status_endpoint),
     ('details', details_endpoint),