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

basic_web_backend/response.py

@@ -0,0 +1,197 @@
+import json
+import mimetypes
+from pathlib import Path
+from http.cookies import SimpleCookie
+
+MIME_TYPES = {
+    #Web
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".xml": "application/xml",
+    ".csv": "text/csv",
+
+    #Images
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".svg": "image/svg+xml",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+
+    #Fonts
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+
+    #Documents and archives
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+    ".tar": "application/x-tar",
+    ".gz": "application/gzip",
+    ".rar": "application/vnd.rar",
+    ".zip": "application/zip",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+
+    #Audio and video
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".mp4": "video/mp4",
+    ".avi": "video/x-msvideo",
+    ".mov": "video/quicktime",
+    ".mkv": "video/x-matroska",
+    ".flac": "audio/flac",
+    ".ogg": "audio/ogg",
+    ".webm": "video/webm",
+    ".m4a": "audio/mp4",
+    ".aac": "audio/aac"
+}
+
+REDIRECT_STATUS_CODES = {
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect"
+}
+
+def _prepare_headers(default_content_type=None, headers=None):
+    if headers is None:
+        response_headers = {}
+    else:
+        response_headers = dict(headers)
+
+    has_content_type = any(
+        name.lower() == "content-type" for name in response_headers)
+
+    if default_content_type and not has_content_type:
+        response_headers["Content-Type"] = default_content_type
+
+    return response_headers
+
+def guess_content_type(filename):
+    path = Path(filename)
+    extension = path.suffix.lower()
+
+    if extension in MIME_TYPES:
+        return MIME_TYPES[extension]
+
+    guessed_type, encoding = mimetypes.guess_type(path.name)
+    if guessed_type is not None:
+        return guessed_type
+
+    return "application/octet-stream"
+
+def content_response(body, content_type, status_code=200, headers=None):
+    response_headers = _prepare_headers(content_type, headers)
+    return body, status_code, response_headers
+
+def html_response(body, status_code=200, headers=None, charset="utf-8"):
+    encoded_body = body.encode(charset)
+    return content_response(body=encoded_body, content_type=f"text/html; charset={charset}",
+        status_code=status_code, headers=headers)
+
+def text_response(body, status_code=200, headers=None, charset="utf-8"):
+    encoded_body = body.encode(charset)
+    return content_response(body=encoded_body, content_type=f"text/plain; charset={charset}",
+        status_code=status_code, headers=headers)
+
+def json_response(data, status_code=200, headers=None, charset="utf-8"):
+    body = json.dumps(data, ensure_ascii=False)
+    encoded_body = body.encode(charset)
+    return content_response(body=encoded_body, content_type=f"application/json; charset={charset}",
+        status_code=status_code, headers=headers)
+
+def file_response(file_path, status_code=200, headers=None, as_attachment=False, download_name=None):
+    path = Path(file_path)
+    body = path.read_bytes()
+    content_type = guess_content_type(path)
+
+    response_headers = _prepare_headers(content_type, headers)
+
+    if as_attachment:
+        filename = download_name or path.name
+        safe_filename = Path(filename).name.replace('"', '_').replace("\r", '_').replace("\n", '_')
+
+        response_headers["Content-Disposition"] = f"attachment; filename=\"{safe_filename}\""
+
+    return body, status_code, response_headers
+
+def redirect_response(location, status_code=302, headers=None):
+    if status_code not in REDIRECT_STATUS_CODES:
+        raise ValueError(f"Invalid redirect status code: {status_code}")
+
+    response_headers = _prepare_headers(headers=headers)
+    response_headers["Location"] = location
+    return "", status_code, response_headers
+
+def empty_response(status_code=204, headers=None):
+    response_headers = _prepare_headers(headers=headers)
+    return b"", status_code, response_headers
+
+def set_cookie(
+        response,
+        key,
+        value,
+        max_age=None,
+        expires=None,
+        path="/",
+        domain=None,
+        secure=False,
+        http_only=False,
+        same_site=None
+):
+
+    body, status_code, headers = response
+
+    if headers is None:
+        response_headers = []
+    elif isinstance(headers, dict):
+        response_headers = list(headers.items())
+    else:
+        response_headers = list(headers)
+
+    cookie = SimpleCookie()
+    cookie[key] = value
+
+    morsel = cookie[key]
+    if max_age is not None:
+        morsel["max-age"] = str(max_age)
+    if expires is not None:
+        morsel["expires"] = expires
+    if path is not None:
+        morsel["path"] = path
+    if domain is not None:
+        morsel["domain"] = domain
+    if secure:
+        morsel["secure"] = True
+    if http_only:
+        morsel["httpOnly"] = True
+    if same_site is not None:
+        morsel["samesite"] = same_site
+
+    response_headers.append(("Set-Cookie", morsel.OutputString()))
+
+    return body, status_code, response_headers
+
+def delete_cookie(response, key, path="/", domain=None):
+    return set_cookie(
+        response=response,
+        key=key,
+        value="",
+        max_age=0,
+        expires="Thu, 01 Jan 1970 00:00:00 GMT",
+        path=path,
+        domain=domain
+    )
+        
+
+

basic_web_backend/routing.py

@@ -0,0 +1,343 @@
+import re
+from dataclasses import dataclass
+from collections.abc import Callable
+
+from .exceptions import (
+    AmbiguousRouteError,
+    DuplicateRouteError,
+    InvalidRouteError,
+    MethodNotAllowed,
+    NotFound
+)
+
+PARAMETER_PATTERN = re.compile(r"<(?P<converter>string|int|float|path):"
+    r"(?P<name>[a-zA-Z_]\w*)>")
+
+CONVERTERS = {
+    "string": (r"[^/]+", str),
+    "int": (r"\d+", int),
+    "float": (r"(?:\d+(?:\.\d*)?)|\.\d+", float),
+    "path": (r".+", str),
+}
+
+CONVERTER_OVERLAPS = {
+    "string": {"string", "int", "float", "path"},
+    "int": {"string", "int", "float", "path"},
+    "float": {"string", "int", "float", "path"},
+    "path": {"string", "int", "float", "path"},
+}
+
+@dataclass
+class RouteMatch:
+    view: Callable
+    parameters: dict
+
+@dataclass
+class DynamicRoute:
+    path_pattern: str
+    regex: re.Pattern
+    converters: dict
+    segments: list
+    methods: dict
+
+class Router:
+    def __init__(self):
+        self.static_routes = {}
+        self.dynamic_routes = []
+
+    def add_route(self, path, view, methods=None):
+        self._validate_path(path=path)
+        self._validate_view(path=path, view=view)
+
+        methods = self._prepare_methods(path=path, methods=methods)
+
+        if "<" in path or ">" in path:
+            self._add_dynamic_route(path=path, methods=methods, view=view)
+        else:
+            self._add_static_route(path=path, methods=methods, view=view)
+
+    def _prepare_methods(self, path, methods):
+        if methods is None:
+            return ["GET"]
+
+        if isinstance(methods, str):
+            raise InvalidRouteError(
+                path=path,
+                message="Route methods must be provided as an iterable of methods names, not as a single string."
+            )
+
+        try:
+            method_items = list(methods)
+        except TypeError as error:
+            raise InvalidRouteError(
+                path=path,
+                message="Route methods must be iterable"
+            ) from error
+
+        if not method_items:
+            raise InvalidRouteError(
+                path=path,
+                message="At least one HTTP method must be provided."
+            )
+
+        normalized_methods = set()
+
+        for method in method_items:
+            if not isinstance(method, str):
+                raise InvalidRouteError(
+                    path=path,
+                    message="Every HTTP method must be text"
+                )
+
+            normalized_method = method.strip().upper()
+
+            if not normalized_method:
+                raise InvalidRouteError(
+                    path=path,
+                    message="HTTP method names cannot be empty or whitespace."
+                )
+
+            normalized_methods.add(normalized_method)
+
+        return normalized_methods
+
+    def _validate_path(self, path):
+        if not isinstance(path, str):
+            raise InvalidRouteError(
+                path=path,
+                message="The route path must be text."
+            )
+
+        if not path.startswith("/"):
+            raise InvalidRouteError(
+                path=path,
+                message="The route must start with '/'."
+            )
+
+    def _validate_view(self, path, view):
+        if not callable(view):
+            raise InvalidRouteError(
+                path=path,
+                message="The route view must be callable."
+            )
+
+    def _add_static_route(self, path, view, methods):
+        registered_methods = self.static_routes.setdefault(path, {})
+
+        for method in methods:
+            if method in registered_methods:
+                raise DuplicateRouteError(path=path, method=method)
+
+        for method in methods:
+            registered_methods[method] = view
+
+    def _add_dynamic_route(self, path, view, methods):
+        existing_same_route = self._find_dynamic_route(path)
+
+        if existing_same_route is not None:
+            duplicate_methods = methods & existing_same_route.methods.keys()
+            if duplicate_methods:
+                duplicate_method = sorted(duplicate_methods)[0]
+
+                raise DuplicateRouteError(path=path, method=duplicate_method)
+
+            for method in methods:
+                existing_same_route.methods[method] = view
+
+            return
+        new_route = self._compile_dynamic_route(path)
+
+        self._check_dynamic_ambiguity(new_route=new_route, methods=methods)
+
+        new_route.methods = {method: view for method in methods}
+
+        self.dynamic_routes.append(new_route)
+
+    def _find_dynamic_route(self, path):
+        for dynamic_route in self.dynamic_routes:
+            if dynamic_route.path_pattern == path:
+                return dynamic_route
+
+        return None
+
+    def _compile_dynamic_route(self, path):
+        if not path.startswith("/"):
+            raise InvalidRouteError(path=path, message="The route must start with '/'.")
+
+        raw_segments = path[1:].split("/")
+        segments = []
+        regex_parts = []
+        converters = {}
+
+        for index, raw_segment in enumerate(raw_segments):
+            paramater_match = PARAMETER_PATTERN.fullmatch(raw_segment)
+            if paramater_match is None:
+                if "<" in raw_segment or ">" in raw_segment:
+                    raise InvalidRouteError(
+                        path=path,
+                        message="A parameter must be in the format <converter:name>."
+                    )
+                segments.append(("static", raw_segment))
+                regex_parts.append(re.escape(raw_segment))
+                continue
+
+            converter_name = paramater_match.group("converter")
+            parameter_name = paramater_match.group("name")
+
+            if parameter_name in converters:
+                raise InvalidRouteError(
+                    path=path,
+                    message=f"Duplicate parameter name: {parameter_name!r}."
+
+                )
+
+            if converter_name == "path" and index != len(raw_segments) - 1:
+                raise InvalidRouteError(
+                    path=path,
+                    message="The 'path' converter must be the final route segment."
+                )
+
+            converter_pattern, converter = CONVERTERS[converter_name]
+            segments.append(("dynamic", converter_name))
+            regex_parts.append(f"(?P<{parameter_name}>{converter_pattern})")
+            converters[parameter_name] = converter
+
+        regex_source = "^/" + "/".join(regex_parts) + "$"
+
+        return DynamicRoute(
+            path_pattern=path,
+            regex=re.compile(regex_source),
+            converters=converters,
+            segments=segments,
+            methods={}
+        )
+
+    def _check_dynamic_ambiguity(self, new_route, methods):
+        for existing_route in self.dynamic_routes:
+            common_methods = methods & existing_route.methods.keys()
+
+            if not common_methods:
+                continue
+
+            if self._routes_overlap(new_route.segments, existing_route.segments):
+                raise AmbiguousRouteError(
+                    path=new_route.path_pattern,
+                    conflicting_path=existing_route.path_pattern,
+                    methods=common_methods
+                )
+
+    def _routes_overlap(self, first_segments, second_segments):
+        if len(first_segments) == len(second_segments):
+            return self._prefixes_overlap(first_segments, second_segments)
+
+        if len(first_segments) < len(second_segments):
+            shorter = first_segments
+            longer = second_segments
+        else:
+            shorter = second_segments
+            longer = first_segments
+
+        if not self._ends_with_path(shorter):
+            return False
+
+        shorter_prefix = shorter[:-1]
+        longer_prefix = longer[:len(shorter_prefix)]
+        return self._prefixes_overlap(shorter_prefix, longer_prefix)
+
+    def _ends_with_path(self, segments):
+        if not segments:
+            return False
+
+        return segments[-1] == ("dynamic", "path")
+
+    def _prefixes_overlap(self, first_segments, second_segments):
+        for first_segment, second_segment in zip(first_segments, second_segments):
+            if not self._segments_overlap(first_segment, second_segment):
+                return False
+
+        return True
+
+    def _segments_overlap(self, first_segment, second_segment):
+        first_kind, first_value = first_segment
+        second_kind, second_value = second_segment
+
+        if first_kind == "static" and second_kind == "static":
+            return first_value == second_value
+
+        if first_kind == "static" and second_kind == "dynamic":
+            return self._static_matches_converter(first_value, second_value)
+
+        if first_kind == "dynamic" and second_kind == "static":
+            return self._static_matches_converter(second_value, first_value)
+
+        return (
+            second_value
+            in CONVERTER_OVERLAPS[first_value]
+        )
+
+    def _static_matches_converter(self, value, converter_name):
+        converter_pattern, _ = CONVERTERS[converter_name]
+
+        return (re.fullmatch(converter_pattern, value) is not None)
+
+    def match_route(self, path, method):
+        normalized_method = method.upper()
+
+        registered_methods = self.static_routes.get(path)
+
+        if registered_methods is not None:
+            view = registered_methods.get(normalized_method)
+
+            if view is None:
+                raise MethodNotAllowed(
+                    method=normalized_method,
+                    path=path,
+                    allowed_methods=registered_methods.keys()
+                )
+
+            return RouteMatch(view=view, parameters={})
+
+        return self._match_dynamic_route(path=path, method=normalized_method)
+
+    def _match_dynamic_route(self, path, method):
+        allowed_methods = set()
+
+        for dynamic_route in self.dynamic_routes:
+            regex_match = dynamic_route.regex.fullmatch(path)
+
+            if regex_match is None:
+                continue
+
+            allowed_methods.update(dynamic_route.methods.keys())
+
+            view = dynamic_route.methods.get(method)
+
+            if view is None:
+                continue
+
+            parameters = self._convert_parameters(
+                regex_match=regex_match,
+                converters=dynamic_route.converters
+            )
+
+            return RouteMatch(view=view, parameters=parameters)
+
+        if allowed_methods:
+            raise MethodNotAllowed(
+                method=method,
+                path=path,
+                allowed_methods=allowed_methods
+            )
+
+        raise NotFound(path=path)
+
+    def _convert_parameters(self, regex_match, converters):
+        parameters = {}
+
+        for name, value in regex_match.groupdict().items():
+            converter = converters[name]
+            parameters[name] = converter(value)
+
+        return parameters
+
+        

basic_web_backend/static.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from .exceptions import NotFound
+from .response import file_response
+
+class StaticFileHandler:
+    def __init__(self, static_folder):
+        self.static_folder = Path(static_folder).resolve()
+
+    def serve(self, filename, status_code=200, headers=None, as_attachment=False, download_name=None):
+        try:
+            file_path = (self.static_folder / filename).resolve()
+
+        except (OSError, RuntimeError):
+            raise NotFound(path=filename)
+
+        if not file_path.is_relative_to(self.static_folder):
+            raise NotFound(path=filename)
+
+        if not file_path.is_file():
+            raise NotFound(path=filename)
+
+        try:
+            return file_response(file_path=file_path, status_code=status_code, headers=headers, as_attachment=as_attachment, download_name=download_name)
+        except (FileNotFoundError, IsADirectoryError) as error:
+            raise NotFound(path=filename) from error
+
+        
+

basic_web_backend/template/__init__.py

@@ -0,0 +1,3 @@
+from .environment import TemplateEnvironment
+
+__all__ = ["TemplateEnvironment"]

basic_web_backend/template/environment.py

@@ -0,0 +1,110 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..exceptions import TemplateNotFound, TemplateLoadError
+from .evaluator import render as render_nodes
+from .lexer import tokenize
+from .parser import parse
+
+@dataclass
+class CachedTemplate:
+    nodes: list
+    modified_time_ns: int
+    file_size: int
+
+class TemplateEnvironment:
+    def __init__(
+        self,
+        template_folder,
+        encoding="utf-8",
+        autoescape=True,
+        cache_enabled=True,
+        auto_reload=False
+    ):
+        self.template_folder = Path(template_folder).resolve()
+        self.encoding = encoding
+        self.autoescape = autoescape
+        self.cache_enabled = cache_enabled
+        self.auto_reload = auto_reload
+
+        self._template_cache = {}
+
+    def render(self, template_name, **context):
+        template_name = str(template_name)
+        template_path = self._resolve_template_path(template_name)
+
+        nodes = self._get_template_nodes(template_name=template_name, template_path=template_path)
+
+        return render_nodes(
+            nodes=nodes,
+            context=context,
+            autoescape=self.autoescape,
+            template_name=template_name
+        )
+
+    def clear_cache(self, template_name=None):
+        if template_name is None:
+            self._template_cache.clear()
+            return
+
+        template_path = self._build_template_path(template_name)
+
+        self._template_cache.pop(template_path, None)
+
+    def _resolve_template_path(self, template_name):
+        template_path = self._build_template_path(template_name)
+
+        if not template_path.is_relative_to(self.template_folder):
+            raise TemplateNotFound(template_name)
+
+        if not template_path.is_file():
+            raise TemplateNotFound(template_name)
+
+        return template_path
+
+    def _build_template_path(self, template_name):
+        template_path = self.template_folder / template_name
+        return template_path.resolve()        
+
+    def _get_template_nodes(self, template_name, template_path):
+        if not self.cache_enabled:
+            return self._load_template_nodes(template_name, template_path)
+
+        cached_template = self._template_cache.get(template_path)
+        if cached_template is not None:
+            if not self.auto_reload:
+                return cached_template.nodes
+
+            if not self._template_changed(template_name, template_path=template_path, cached_template=cached_template):
+                return cached_template.nodes
+
+        nodes = self._load_template_nodes(template_name=template_name, template_path=template_path)
+
+        file_status = self._get_file_status(template_name=template_name, template_path=template_path)
+        self._template_cache[template_path] = CachedTemplate(nodes=nodes, modified_time_ns=file_status.st_mtime_ns, file_size=file_status.st_size)
+
+        return nodes
+
+    def _load_template_nodes(self, template_name, template_path):
+        try:
+            source = template_path.read_text(encoding=self.encoding)
+        except (OSError, UnicodeError) as error:
+            raise TemplateLoadError(template_name=template_name, message=str(error)) from error
+
+        tokens = tokenize(source, template_name=template_name)
+        nodes = parse(tokens, template_name=template_name)
+        return nodes
+
+    def _get_file_status(self, template_name, template_path):
+        try:
+            return template_path.stat()
+        except OSError as error:
+            raise TemplateLoadError(template_name=template_name, message=str(error)) from error
+
+    def _template_changed(self, template_name, template_path, cached_template):
+        file_status = self._get_file_status(template_name=template_name, template_path=template_path)
+        return (
+            file_status.st_mtime_ns != cached_template.modified_time_ns or
+            file_status.st_size != cached_template.file_size
+        )
+