lema-basic-web-backend 0.1.0__py3-none-any.whl

basic_web_backend/__init__.py

@@ -0,0 +1,86 @@
+from importlib.metadata import version
+
+from .adapters import LemaRequestAdapter, LemaResponseAdapter
+from .application import WebApplication
+from .config import ApplicationConfig
+from .exceptions import (
+    AmbiguousRouteError,
+    BackendError,
+    BadRequest,
+    Conflict,
+    DuplicateRouteError,
+    Forbidden,
+    HTTPException,
+    InvalidRouteError,
+    MethodNotAllowed,
+    NotFound,
+    PayloadTooLarge,
+    RoutingError,
+    TemplateError,
+    TemplateLoadError,
+    TemplateNotFound,
+    TemplateRenderError,
+    TemplateSyntaxError,
+    Unauthorized,
+    UndefinedVariableError,
+    UnprocessableContent,
+    UnsupportedMediaType,
+)
+
+from .multipart import UploadedFile
+from .request import Request
+from .response import (
+    content_response,
+    delete_cookie,
+    empty_response,
+    file_response,
+    html_response,
+    json_response,
+    redirect_response,
+    set_cookie,
+    text_response, 
+)
+from .template.environment import TemplateEnvironment
+
+__version__ = version("lema-basic-web-backend")
+
+__all__ = [
+    "__version__",
+    "WebApplication",
+    "ApplicationConfig",
+    "Request",
+    "UploadedFile",
+    "LemaRequestAdapter",
+    "LemaResponseAdapter",
+    "TemplateEnvironment",
+    "content_response",
+    "html_response",
+    "text_response",
+    "json_response",
+    "file_response",
+    "redirect_response",
+    "empty_response",
+    "set_cookie",
+    "delete_cookie",
+    "BackendError",
+    "RoutingError",
+    "DuplicateRouteError",
+    "InvalidRouteError",
+    "AmbiguousRouteError",
+    "HTTPException",
+    "BadRequest",
+    "Unauthorized",
+    "Forbidden",
+    "NotFound",
+    "MethodNotAllowed",
+    "Conflict",
+    "PayloadTooLarge",
+    "UnsupportedMediaType",
+    "UnprocessableContent",
+    "TemplateError",
+    "TemplateNotFound",
+    "TemplateLoadError",
+    "TemplateSyntaxError",
+    "TemplateRenderError",
+    "UndefinedVariableError"
+]

basic_web_backend/adapters.py

@@ -0,0 +1,39 @@
+from .request import Request
+
+class LemaRequestAdapter:
+    def convert(self, server_request):
+        method = server_request.method
+        path = server_request.path
+        query_string = server_request.query_string
+        headers = server_request.headers
+        body = server_request.body
+
+        return Request(method, path, query_string, headers, body)
+
+class LemaResponseAdapter:
+    def convert(self, backend_response):
+        if not isinstance(backend_response, tuple):
+            return backend_response
+        if len(backend_response) != 3:
+            return backend_response
+
+        body, status_code, headers = backend_response
+
+        filtered_headers = self._remove_content_length(headers)
+
+        return body, status_code, filtered_headers
+
+    def _remove_content_length(self, headers):
+        if headers is None:
+            return None
+
+        if isinstance(headers, dict):
+            return {
+                name: value for name, value in headers.items()
+                if name.lower() != "content-length"
+            }
+
+        return [
+            (name, value) for name, value in headers
+            if name.lower() != "content-length"
+        ]

basic_web_backend/application.py

@@ -0,0 +1,217 @@
+from html import escape
+from traceback import format_exc
+
+from .config import ApplicationConfig
+from .logging_config import create_logger
+from .exceptions import BadRequest, HTTPException, PayloadTooLarge
+from .response import html_response
+from .request import Request
+from .routing import Router
+from .static import StaticFileHandler
+from .template.environment import TemplateEnvironment
+
+
+class WebApplication:
+    def __init__(self, config=None):
+        if config is None:
+            config = ApplicationConfig()
+
+        self.config = config
+
+        self.logger = create_logger(
+            name=self.config.logger_name,
+            log_file=self.config.log_file,
+            log_level=self.config.log_level,
+            log_max_bytes=self.config.log_max_bytes,
+            log_backup_count=self.config.log_backup_count
+        )
+
+        self.template_environment = TemplateEnvironment(
+            template_folder=self.config.template_folder,
+            encoding=self.config.template_encoding,
+            autoescape=self.config.template_autoescape,
+            cache_enabled=self.config.template_cache,
+            auto_reload=self.config.template_auto_reload
+        )
+
+        self.router = Router()
+        self.error_handlers = {}
+        self.static_handler = None
+
+        if self.config.static_folder is not None:
+            self._register_static_route()
+
+    def _register_static_route(self):
+        static_url_path = ("/" + self.config.static_url_path.strip("/"))
+
+        if static_url_path == "/":
+            route_path = "/<path:filename>"
+        else:
+            route_path = f"{static_url_path}/<path:filename>"
+
+        self.static_handler = StaticFileHandler(static_folder=self.config.static_folder)
+        self.router.add_route(path=route_path, view=self._serve_static_file, methods=["GET"])
+
+    def _serve_static_file(self, request, filename):
+        return self.static_handler.serve(filename=filename)
+
+    def route(self, path, methods=None):
+        def decorator(view):
+            self.router.add_route(path=path, view=view, methods=methods)
+            return view
+        return decorator
+
+    def errorhandler(self, status_code):
+        if  not isinstance(status_code, int) or isinstance(status_code, bool):
+            raise TypeError("The error handler status code must be an integer.")
+
+        if not (400 <= status_code <= 599):
+            raise ValueError("The error handler status code must be between 400 and 599.")
+
+        def decorator(handler):
+            if not callable(handler):
+                raise TypeError("The error handler must be a callable.")
+
+            if status_code in self.error_handlers:
+                raise ValueError(f"An error handler is already registered for status code {status_code}.")
+
+            self.error_handlers[status_code] = handler
+            return handler
+        
+        return decorator
+
+    def __call__(self, server_request):
+        request = None
+
+        try:
+            request = self._convert_request(server_request)
+
+            self._check_content_length(request)
+
+            route_match = self.router.match_route(path=request.path, method=request.method)
+
+            response = route_match.view(request=request, **route_match.parameters)
+
+        except HTTPException as error:
+            response = self._handle_http_exception(error, request=request)
+
+
+        except Exception as error:
+            response = self._handle_internal_error(error, request=request)
+
+        return self._convert_response(response=response, request=request)
+
+    def _convert_request(self, server_request):
+        request = self.config.request_adapter.convert(server_request)
+
+        if not isinstance(request, Request):
+            raise TypeError(
+                "The request adapter must return a Request object."
+            )
+
+        return request
+
+    def _convert_response(self, response, request=None):
+        try:
+            return self.config.response_adapter.convert(response)
+        except Exception:
+            if request is None:
+                self.logger.exception("The response adapter failed.")
+            else:
+                self.logger.exception(
+                    "The response adapter failed while processing a request: %s %s",
+                    request.method,
+                    request.path
+                )
+            raise
+
+    def _handle_http_exception(self, error, request=None):
+        handler = self.error_handlers.get(error.status_code)
+
+        if handler is not None:
+            try:
+                return handler(error)
+            except Exception as handler_error:
+                return self._handle_internal_error(handler_error, request=request)
+
+        title = f"{error.status_code} {error.default_message}"
+
+        body = f"<h1>{escape(title)}</h1>"
+
+        if error.message != error.default_message:
+            body += f"<p>{escape(error.message)}</p>"
+
+        return html_response(
+            body=body,
+            status_code=error.status_code,
+            headers=error.headers
+        )
+
+    def _handle_internal_error(self, error, request=None):
+        if request is None:
+            self.logger.exception("Unhandled exception while adapting a server request.")
+        else:
+            self.logger.exception(
+                "Unhandled exception while processing a request: %s %s",
+                request.method,
+                request.path
+            )
+
+        handler = self.error_handlers.get(500)
+
+        if handler is not None:
+            try:
+                return handler(error)
+            except Exception as handler_error:
+                self.logger.exception("The custom 500 error handler failed.")
+
+                return self._create_internal_error_response(handler_error)
+
+        return self._create_internal_error_response(error)
+
+    def _create_internal_error_response(self, error):
+        if self.config.debug:
+            error_type = type(error).__name__
+            error_message = escape(str(error))
+            error_traceback = escape(format_exc())
+
+            return html_response(
+                body=(
+                    f"<h1>500 Internal Server Error</h1>"
+                    f"<h2>{error_type}: {error_message}</h2>"
+                    f"<pre>{error_traceback}</pre>"
+                ),
+                status_code=500
+            )
+
+        return html_response(
+            body="<h1>500 Internal Server Error</h1>",
+            status_code=500
+        )
+
+    def _check_content_length(self, request):
+        limit = self.config.max_content_length
+
+        if limit is None:
+            return
+
+        body = request.body
+
+        if isinstance(body, str):
+            body_length = len(body.encode("utf-8"))
+        else:
+            body_length = len(body)
+
+        if body_length > limit:
+            raise PayloadTooLarge(f"The request body exceeds the {limit}-byte limit.")
+
+    def render_template(self, template_name, status_code=200, headers=None, charset="utf-8", **context):
+        rendered_html = self.template_environment.render(template_name, **context)
+
+        return html_response(
+            body=rendered_html,
+            status_code=status_code,
+            headers=headers,
+            charset=charset
+        )
+

basic_web_backend/config.py

@@ -0,0 +1,214 @@
+import codecs
+import logging
+
+from .adapters import LemaRequestAdapter, LemaResponseAdapter
+from .logging_config import LOG_LEVELS
+
+def _validate_adapter(adapter, name):
+    convert = getattr(adapter, "convert", None)
+
+    if not callable(convert):
+        raise TypeError(f"{name} must have a callable 'convert' method")
+
+def _validate_boolean(value, name):
+    if not isinstance(value, bool):
+        raise TypeError(
+            f"{name} must be a boolean."
+        )
+
+
+def _validate_optional_non_negative_integer(
+    value,
+    name,
+):
+    if value is None:
+        return
+
+    _validate_non_negative_integer(
+        value=value,
+        name=name,
+    )
+
+
+def _validate_non_negative_integer(
+    value,
+    name,
+):
+    if (
+        not isinstance(value, int)
+        or isinstance(value, bool)
+    ):
+        raise TypeError(
+            f"{name} must be an integer."
+        )
+
+    if value < 0:
+        raise ValueError(
+            f"{name} cannot be negative."
+        )
+
+
+def _validate_static_url_path(value):
+    if not isinstance(value, str):
+        raise TypeError(
+            "static_url_path must be text."
+        )
+
+    if not value:
+        raise ValueError(
+            "static_url_path cannot be empty."
+        )
+
+    if not value.startswith("/"):
+        raise ValueError(
+            "static_url_path must start "
+            "with '/'."
+        )
+
+
+def _validate_encoding(encoding):
+    if not isinstance(encoding, str):
+        raise TypeError(
+            "template_encoding must be text."
+        )
+
+    try:
+        codecs.lookup(encoding)
+    except LookupError as error:
+        raise ValueError(
+            "Unknown template encoding: "
+            f"{encoding!r}."
+        ) from error
+
+
+def _validate_logger_name(name):
+    if not isinstance(name, str):
+        raise TypeError(
+            "logger_name must be text."
+        )
+
+    if not name.strip():
+        raise ValueError(
+            "logger_name cannot be empty."
+        )
+
+
+def _validate_log_level(log_level):
+    if not isinstance(log_level, str):
+        raise TypeError(
+            "log_level must be text."
+        )
+
+    normalized_level = log_level.upper()
+
+    if normalized_level not in LOG_LEVELS:
+        raise ValueError(
+            f"Unknown log level: {log_level}"
+        )
+
+class ApplicationConfig:
+    def __init__(
+        self,
+        request_adapter=None,
+        response_adapter=None,
+        debug=False,
+        static_folder="static",
+        static_url_path="/static",
+        max_content_length=None,
+        template_folder="templates",
+        template_encoding="utf-8",
+        template_autoescape=True,
+        template_cache=True,
+        template_auto_reload=False,
+        logger_name="basic_web_backend",
+        log_file=None,
+        log_level="INFO",
+        log_max_bytes=1_000_000,
+        log_backup_count=5
+    ):
+        if request_adapter is None:
+            request_adapter = LemaRequestAdapter()
+
+        if response_adapter is None:
+            response_adapter = LemaResponseAdapter()
+
+        _validate_adapter(request_adapter, "request_adapter")
+
+        _validate_adapter(response_adapter, "response_adapter")
+
+        _validate_adapter(
+            request_adapter,
+            "request_adapter",
+        )
+
+        _validate_adapter(
+            response_adapter,
+            "response_adapter",
+        )
+
+        _validate_boolean(
+            debug,
+            "debug",
+        )
+        _validate_boolean(
+            template_autoescape,
+            "template_autoescape",
+        )
+        _validate_boolean(
+            template_cache,
+            "template_cache",
+        )
+        _validate_boolean(
+            template_auto_reload,
+            "template_auto_reload",
+        )
+
+        _validate_optional_non_negative_integer(
+            value=max_content_length,
+            name="max_content_length",
+        )
+
+        _validate_static_url_path(
+            static_url_path
+        )
+
+        _validate_encoding(
+            template_encoding
+        )
+
+        _validate_logger_name(
+            logger_name
+        )
+
+        _validate_log_level(
+            log_level
+        )
+
+        _validate_non_negative_integer(
+            value=log_max_bytes,
+            name="log_max_bytes",
+        )
+        _validate_non_negative_integer(
+            value=log_backup_count,
+            name="log_backup_count",
+        )
+
+        self.request_adapter = request_adapter
+        self.response_adapter = response_adapter
+        self.debug = debug
+        self.template_folder = template_folder
+        self.template_encoding = template_encoding
+        self.template_autoescape = template_autoescape
+        self.template_cache = template_cache
+        self.template_auto_reload = template_auto_reload
+        self.static_folder = static_folder
+        self.static_url_path = static_url_path
+        self.max_content_length = max_content_length
+
+        self.logger_name = logger_name
+        self.log_file = log_file
+        self.log_level = log_level
+        self.log_max_bytes = log_max_bytes
+        self.log_backup_count = log_backup_count
+
+