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

basic_web_backend/exceptions.py

@@ -0,0 +1,176 @@
+class BackendError(Exception):
+    """Base class for all backend-specific exceptions."""
+    pass
+
+class RoutingError(BackendError):
+    """Base class for route registration errors."""
+    pass
+
+class DuplicateRouteError(RoutingError):
+    """Raised when a route is registered more than once."""
+    def __init__(self, path, method):
+        self.path = path
+        self.method = method
+        super().__init__(f"Route alredy registered for path: {path} and method: {method}")
+
+class InvalidRouteError(RoutingError):
+    """Raised when a route is registered with an invalid path or method."""
+    def __init__(self, path, message):
+        self.path = path
+        self.message = message
+        super().__init__(f"Invalid route {path!r}: {message}")
+
+class AmbiguousRouteError(RoutingError):
+    """Raised when a route is registered that conflicts with an existing route."""
+    def __init__(self, path, conflicting_path, methods):
+        self.path = path
+        self.conflicting_path = conflicting_path
+        self.methods = methods
+
+        method_list = ", ".join(sorted(self.methods))
+        super().__init__(
+            f"Ambigous routes {path!r} and "
+            f"{conflicting_path!r} for methods: {method_list}"
+        )
+
+class HTTPException(Exception):
+    """Base class for all HTTP exceptions."""
+    status_code = 500
+    default_message = "Internal Server Error"
+
+    def __init__(self, message=None, headers=None):
+        self.message = (
+            message
+            if message is not None
+            else self.default_message
+        )
+        self.headers = dict(headers or {})
+
+        super().__init__(self.message)
+
+
+class BadRequest(HTTPException):
+    status_code = 400
+    default_message = "Bad Request"
+
+
+class Unauthorized(HTTPException):
+    status_code = 401
+    default_message = "Unauthorized"
+
+
+class Forbidden(HTTPException):
+    status_code = 403
+    default_message = "Forbidden"
+
+
+class NotFound(HTTPException):
+    status_code = 404
+    default_message = "Not Found"
+
+    def __init__(self, path, message=None):
+        self.path = path
+        super().__init__(message=message)
+
+
+class MethodNotAllowed(HTTPException):
+    status_code = 405
+    default_message = "Method Not Allowed"
+
+    def __init__(
+        self,
+        method,
+        path,
+        allowed_methods,
+        message=None,
+    ):
+        self.method = method.upper()
+        self.path = path
+        self.allowed_methods = tuple(sorted(method.upper() for method in allowed_methods))
+
+        allow_header = ", ".join(
+            sorted(self.allowed_methods)
+        )
+
+        super().__init__(
+            message=message,
+            headers={
+                "Allow": allow_header,
+            },
+        )
+
+
+class Conflict(HTTPException):
+    status_code = 409
+    default_message = "Conflict"
+
+
+class PayloadTooLarge(HTTPException):
+    status_code = 413
+    default_message = "Payload Too Large"
+
+
+class UnsupportedMediaType(HTTPException):
+    status_code = 415
+    default_message = "Unsupported Media Type"
+
+
+class UnprocessableContent(HTTPException):
+    status_code = 422
+    default_message = "Unprocessable Content"
+
+class TemplateError(Exception):
+    """Base class for template-releated errors:"""
+
+class TemplateNotFound(TemplateError):
+    def __init__(self, template_name):
+        self.template_name = template_name
+
+        super().__init__(f"Template not found: {template_name}")
+
+class TemplateLoadError(TemplateError):
+    """Raised when a template file cannot be loaded."""
+
+    def __init__(self, template_name, message):
+        self.template_name = template_name
+        self.message = message
+
+        super().__init__(f"Could not load template {template_name!r}: {message}")
+
+class TemplateSyntaxError(TemplateError):
+    def __init__(self, message, template_name=None, line=None, column=None):
+        self.message = message
+        self.template_name = template_name
+        self.line = line
+        self.column = column
+
+        formatted_message = self._format_message()
+        super().__init__(formatted_message)
+
+    def _format_message(self):
+        if (self.template_name is not None and self.line is not None and self.column is not None):
+            return (
+                f"{self.template_name}:{self.line}:{self.column}: {self.message}"
+            )
+
+        if self.template_name is not None and self.line is not None:
+            return f"{self.template_name}:{self.line}: {self.message}"
+
+        if self.template_name is not None:
+            return f"{self.template_name}: {self.message}"
+
+        if self.line is not None and self.column is not None:
+            return f"Line {self.line}, Column {self.column}: {self.message}"
+
+        if self.line is not None:
+            return f"Line {self.line}: {self.message}"
+
+        return self.message
+
+class TemplateRenderError(TemplateError):
+    """Raised when a template cannot be rendered."""
+
+class UndefinedVariableError(TemplateRenderError):
+    def __init__(self, variable_name):
+        self.variable_name = variable_name
+        super().__init__(f"Undefined variable: {variable_name}")

basic_web_backend/logging_config.py

@@ -0,0 +1,61 @@
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+LOG_LEVELS = {
+    "CRITICAL": logging.CRITICAL,
+    "ERROR": logging.ERROR,
+    "WARNING": logging.WARNING,
+    "INFO": logging.INFO,
+    "DEBUG": logging.DEBUG,
+    "NOTSET": logging.NOTSET,
+}
+
+DEFAULT_LOG_FORMAT = (
+    "%(asctime)s "
+    "%(levelname)s "
+    "%(name)s "
+    "%(message)s"
+)
+
+def create_logger(
+    name="basic_web_backend",
+    log_file=None,
+    log_level="INFO",
+    log_max_bytes=1_000_000,
+    log_backup_count=5
+):
+    logger = logging.getLogger(name)
+
+    level = LOG_LEVELS.get(str(log_level).upper())
+
+    if level is None:
+        raise ValueError(f"Invalid log level: {log_level!r}")
+
+    logger.setLevel(level)
+    logger.propagate = False
+
+    _remove_existing_handlers(logger)
+
+    if log_file is not None:
+        log_path = Path(log_file)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+
+        handler = RotatingFileHandler(
+            filename=log_path,
+            maxBytes=log_max_bytes,
+            backupCount=log_backup_count,
+            encoding="utf-8"
+        )
+
+        handler.setLevel(level)
+        handler.setFormatter(logging.Formatter(DEFAULT_LOG_FORMAT))
+        logger.addHandler(handler)
+
+    return logger
+
+def _remove_existing_handlers(logger):
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+        handler.close()
+    

basic_web_backend/multipart.py

@@ -0,0 +1,109 @@
+from dataclasses import dataclass
+from email.parser import BytesParser
+from email.policy import default
+
+from .exceptions import BadRequest
+
+@dataclass
+class UploadedFile:
+    filename: str
+    content_type: str | None
+    body: bytes
+    headers: dict
+
+def parse_multipart(body, boundary, charset="utf-8"):
+    _validate_inputs(body=body, boundary=boundary)
+
+    message = _parse_multipart_message(body=body, boundary=boundary)
+
+    if not message.is_multipart():
+        raise BadRequest("The request body is not valid multipart data.")
+
+    if message.defects:
+        raise BadRequest("The request body contains malformed multipart data.")
+
+    form = {}
+    files = {}
+
+    for part in message.iter_parts():
+        _process_part(part=part, form=form, files=files, default_charset=charset)
+
+    return form, files
+
+def _validate_inputs(body, boundary):
+    if not isinstance(body, bytes):
+        raise BadRequest("The multipart body must be bytes.")
+    if not isinstance(boundary, str):
+        raise BadRequest("The multipart boundary must be text.")
+    if not boundary:
+        raise BadRequest("The multipart boundary is missing or empty.")
+    if "\n" in boundary or "\r" in boundary:
+        raise BadRequest("The multipart boundary is invalid.")
+
+def _parse_multipart_message(body, boundary):
+    try:
+        boundary_bytes = boundary.encode("ascii")
+    except UnicodeEncodeError:
+        raise BadRequest("The multipart boundary must contain only ASCII characters.")
+
+    excaped_boundary = boundary_bytes.replace(b'"', b'\\"').replace(b'\\', b'\\\\')
+
+    synthetic_headers = (
+        b"Content-Type: multipart/form-data; "
+        b'boundary="'
+        + excaped_boundary 
+        + b'"\r\n'
+        + b"MIME-Version: 1.0\r\n"
+        + b"\r\n"
+    )
+
+    return BytesParser(policy=default).parsebytes(synthetic_headers + body)
+
+def _process_part(part, form, files, default_charset):
+    if part.get_content_disposition() != "form-data":
+        raise BadRequest("Each multipart part must use form-data content disposition.")
+
+    field_name = part.get_param("name", header="content-disposition")
+
+    if not field_name:
+        raise BadRequest("Each multipart part must have a field name.")
+
+    payload = part.get_payload(decode=True)
+
+    if payload is None:
+        payload = b""
+
+    filename = part.get_filename()
+
+    if filename is not None:
+        uploaded_file = UploadedFile(
+            filename=filename,
+            content_type=_get_part_content_type(part=part),
+            body=payload,
+            headers=dict(part.items()),
+        )
+
+        files.setdefault(field_name, []).append(uploaded_file)
+
+        return
+
+    text = _decode_form_field(part=part, payload=payload, default_charset=default_charset)
+
+    form.setdefault(field_name, []).append(text)
+
+def _get_part_content_type(part):
+    if part.get("Content-Type") is None:
+        return None
+
+    return part.get_content_type()
+
+def _decode_form_field(part, payload, default_charset):
+    charset = part.get_content_charset() or default_charset
+
+    try:
+        return payload.decode(charset)
+    except LookupError as error:
+        raise BadRequest(f"Unsupported multipart character encoding: {charset}") from error
+    except UnicodeDecodeError as error:
+        raise BadRequest(f"A multipart form field cannot be decoded using {charset}.") from error
+

basic_web_backend/request.py

@@ -0,0 +1,180 @@
+import json
+from urllib.parse import parse_qs
+from http.cookies import CookieError, SimpleCookie
+
+from .exceptions import BadRequest, UnsupportedMediaType
+from .multipart import parse_multipart
+
+class Request:
+    def __init__(self, method, path, query_string="", headers=None, body=b""):
+        if not isinstance(body, (str, bytes)):
+            raise BadRequest("The request body must be bytes or text")
+
+        self.method = method.upper()
+        self.path = path
+        self.query_string = query_string
+        self.body = body
+
+        if headers is None:
+            header_items = []
+        elif isinstance(headers, dict):
+            header_items = headers.items()
+        else:
+            header_items = headers
+
+        self.headers = [(k.lower(), v) for k, v in header_items]
+        self.query = parse_qs(query_string, keep_blank_values=True)
+
+    def get_header(self, name, default=None):
+        normalized_name = name.lower()
+
+        for header_name, header_value in self.headers:
+            if header_name == normalized_name:
+                return header_value
+
+        return default
+
+    def get_headers(self, name):
+        normalized_name = name.lower()
+        return [value for header_name, value in self.headers if header_name == normalized_name]
+
+    @property
+    def content_type(self):
+        conetnt_type, parameters = self._parse_content_type()
+        return conetnt_type
+
+    @property
+    def charset(self):
+        content_type, parameters = self._parse_content_type()
+
+        charset = parameters.get("charset")
+        if charset is None:
+            return None
+
+        return charset.lower()
+
+    def _parse_content_type(self):
+        header_value = self.get_header("content-type")
+
+        if header_value is None:
+            return None, {}
+
+        parts = header_value.split(";")
+        content_type = parts[0].strip().lower()
+
+        if not content_type:
+            content_type = None
+
+        parameters = {}
+
+        for part in parts[1:]:
+            name, sep, value = part.partition("=")
+            if not sep:
+                continue
+
+            name = name.strip().lower()
+            value = value.strip()
+
+            if (
+                len(value) >= 2 and value[0] == '"' and value[-1] == '"'
+            ):
+                value = value[1:-1]
+
+            if name:
+                parameters[name] = value
+
+        return content_type, parameters
+
+    def get_json(self):
+        content_type = self.content_type
+
+        is_json = (content_type == "application/json" or (content_type is not None and content_type.endswith("+json")))
+
+        if not is_json:
+            raise UnsupportedMediaType("The request content type must be JSON")
+
+        charset = self.charset or "utf-8"
+
+        try:
+            if isinstance(self.body, bytes):
+                body_text = self.body.decode(charset)
+            else:
+                body_text = self.body
+
+        except LookupError:
+            raise BadRequest(f"The charset '{charset}' is not supported")
+        except UnicodeDecodeError:
+            raise BadRequest(f"The request body could not be decoded using the charset '{charset}'")
+
+        try:
+            return json.loads(body_text)
+        except json.JSONDecodeError:
+            raise BadRequest("The request body is not valid JSON")
+
+    def get_form(self):
+        if self.content_type != "application/x-www-form-urlencoded":
+            raise UnsupportedMediaType("The request content type must be application/x-www-form-urlencoded")
+
+        charset = self.charset or "utf-8"
+
+        try:
+            if isinstance(self.body, bytes):
+                body_text = self.body.decode(charset)
+            else:
+                body_text = self.body
+
+            return parse_qs(body_text, keep_blank_values=True, encoding=charset, errors="strict")
+
+        except LookupError:
+            raise BadRequest(f"Unsupported character encoding: '{charset}'")
+        except UnicodeDecodeError:
+            raise BadRequest(f"The request body could not be decoded using the charset '{charset}'")
+
+    @property
+    def cookies(self):
+        cookie_headers = self.get_headers("cookie")
+
+        if cookie_headers is None:
+            return {}
+
+        result = {}
+
+        for header_value in cookie_headers:
+            cookie = SimpleCookie()
+            try:
+                cookie.load(header_value)
+            except CookieError:
+                raise BadRequest("The request contains invalid cookie header.")
+
+            for name, morsel in cookie.items():
+                result[name] = morsel.value
+
+        return result
+
+    def get_multipart(self):
+        if self.content_type != "multipart/form-data":
+            raise UnsupportedMediaType(
+                "The request Content-Type must be "
+                "multipart/form-data."
+            )
+
+        content_type, parameters = (
+            self._parse_content_type()
+        )
+
+        boundary = parameters.get("boundary")
+
+        if not boundary:
+            raise BadRequest(
+                "The multipart boundary is missing."
+            )
+
+        charset = self.charset or "utf-8"
+
+        return parse_multipart(
+            body=self.body,
+            boundary=boundary,
+            charset=charset,
+        )
+
+