Nexom 0.1.3__py3-none-any.whl

nexom/core/error.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+from typing import Any
+
+
+class NexomError(Exception):
+    """
+    Base exception class for all Nexom errors.
+
+    Attributes:
+        code: Stable error code for programmatic handling.
+        message: Human-readable error message.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code: str = code
+        self.message: str = message
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"{self.code} -> {self.message}"
+
+
+# =========================
+# Command / CLI
+# =========================
+
+class CommandArgumentsError(NexomError):
+    """Raised when required CLI arguments are missing."""
+
+    def __init__(self) -> None:
+        super().__init__("CS01", "Missing command arguments.")
+
+
+# =========================
+# Path / Routing
+# =========================
+
+class PathNotFoundError(NexomError):
+    """Raised when no matching route is found."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__("P01", f"This path is not found. '{path}'")
+
+
+class PathInvalidHandlerTypeError(NexomError):
+    """Raised when a handler returns an invalid response type."""
+
+    def __init__(self, handler: Any) -> None:
+        name = getattr(handler, "__name__", repr(handler))
+        super().__init__(
+            "P02",
+            "This handler returns an invalid type. "
+            f"Return value must be Response or dict. '{name}'",
+        )
+
+
+class PathlibTypeError(NexomError):
+    """Raised when a non-Path object is added to Pathlib."""
+
+    def __init__(self) -> None:
+        super().__init__("P03", "This list only accepts Path objects.")
+
+
+class PathHandlerMissingArgError(NexomError):
+    """Raised when a handler signature is invalid."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "P04",
+            "Handler must accept 'request' and 'args' as parameters.",
+        )
+
+
+# =========================
+# Cookie
+# =========================
+
+class CookieInvalidValueError(NexomError):
+    """Raised when a cookie value is invalid."""
+
+    def __init__(self, value: str) -> None:
+        super().__init__("C01", f"This value is invalid. '{value}'")
+
+
+# =========================
+# Template
+# =========================
+
+class TemplateNotFoundError(NexomError):
+    """Raised when a template file cannot be found."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__("T01", f"This template is not found. '{name}'")
+
+class TemplateInvalidNameError(NexomError):
+    """Raised when a template file/dir name violates Nexom template naming rules."""
+
+    def __init__(self, key: str) -> None:
+        super().__init__(
+            "T02",
+            f"This template name is invalid. '{key}'",
+        )
+
+class TemplatesNotDirError(NexomError):
+    """Raised when the base templates directory is not a directory."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(
+            "T03",
+            f"This base path is not a directory. '{path}'"
+        )
+
+
+# =========================
+# ObjectHTML
+# =========================
+class HTMLDocLibNotFoundError(NexomError):
+    """Raised when an HTML document is not found in the library."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            "HD01",
+            f"This HTML document is not found in the library. '{name}'",
+        )
+
+class ObjectHTMLInsertValueError(NexomError):
+    """Raised when an insert value for ObjectHTML is invalid."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            "OH01",
+            f"This insert value is invalid. '{name}'",
+        )
+class ObjectHTMLExtendsError(NexomError):
+    """Raised when an extends for ObjectHTML is invalid."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            "OH02",
+            f"This extends is invalid. '{name}'",
+        )
+class ObjectHTMLImportError(NexomError):
+    """Raised when an import for ObjectHTML is invalid."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(
+            "OH03",
+            f"This import is invalid. '{name}'",
+        )

nexom/engine/__init__.py

@@ -0,0 +1 @@
+from . import object_html_render

nexom/engine/object_html_render.py

@@ -0,0 +1,224 @@
+"""
+Nexom Object HTML (OHTML)
+
+A lightweight HTML composition system that extends plain HTML with:
+- <Extends ... />
+- <Insert ...>...</Insert>
+- <Import ... />
+- {{slot}}
+
+This renderer also preserves indentation when importing blocks or inserting
+multi-line slot values.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import UserList
+from typing import Final
+
+from ..core.error import (
+    HTMLDocLibNotFoundError,
+    ObjectHTMLImportError,
+    ObjectHTMLInsertValueError,
+    ObjectHTMLExtendsError,
+)
+
+
+# Slots: {{ key }}
+_SLOT_RE: Final = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+# Extends: <Extends a.b />
+_EXTENDS_RE: Final = re.compile(r"<Extends\s+([\w\.]+)\s*/>")
+
+# Insert: <Insert key>...</Insert>
+_INSERT_RE: Final = re.compile(r"<Insert\s+([\w\.]+)>(.*?)</Insert>", flags=re.DOTALL)
+
+# Import: line-based (captures indent + name)
+# Example:
+#     <Import components.header />
+_IMPORT_LINE_RE: Final = re.compile(r"(?m)^([ \t]*)<Import\s+([\w\.]+)\s*/>\s*$")
+
+
+class HTMLDoc:
+    """Raw HTML document container (no rendering)."""
+
+    def __init__(self, name: str, html: str) -> None:
+        self.name = name.rsplit(".", 1)[0] if name.endswith(".html") else name
+        self.html = html
+
+    def __repr__(self) -> str:
+        return self.name
+
+
+class HTMLDocLib(UserList[HTMLDoc]):
+    """A list of HTML documents with name lookup."""
+
+    def __init__(self, docs: list[HTMLDoc] | None = None) -> None:
+        super().__init__(docs or [])
+
+    def get(self, name: str, raise_error: bool = False) -> HTMLDoc | None:
+        for doc in self.data:
+            if doc.name == name:
+                return doc
+        if raise_error:
+            raise HTMLDocLibNotFoundError(name)
+        return None
+
+
+class ObjectHTML:
+    """
+    Object HTML renderer.
+
+    Provides dynamic callable access:
+        engine.default(title="x")
+        engine.layout.base(title="x")
+
+    Internals:
+    - Extends/Insert are applied first (non-strict slots for inserts)
+    - Imports are expanded with indentation preserved
+    - Final {{slot}} replacement is applied (strict)
+    """
+
+    def __init__(self, *docs: HTMLDoc, lib: HTMLDocLib | None = None) -> None:
+        self.lib = lib or HTMLDocLib()
+        for doc in docs:
+            self.lib.append(doc)
+
+        # Build dynamic callables for each doc name
+        for doc in self.lib:
+            self._set_doc(doc)
+
+    def _set_doc(self, doc: HTMLDoc) -> None:
+        def _call(**kwargs: str) -> str:
+            return self.render(doc.name, **kwargs)
+
+        setattr(self, doc.name, _call)
+
+    def render(self, name: str, **kwargs: str) -> str:
+        """Render a template by name."""
+        html = self._render_structure(name)
+        # Final strict slot fill (indent-aware)
+        return self._apply_slots_strict(html, kwargs)
+
+    # -------------------------
+    # phases
+    # -------------------------
+
+    def _render_structure(self, name: str) -> str:
+        """Resolve Extends/Insert and Import. Leaves {{slots}} unresolved."""
+        doc = self.lib.get(name, raise_error=True)
+        html = self._apply_extends(doc.html)
+        html = self._apply_imports(html)
+        return html
+
+    def _apply_extends(self, html: str) -> str:
+        m = _EXTENDS_RE.search(html)
+        if not m:
+            return html
+
+        extends_name = m.group(1)
+        base = self.lib.get(extends_name)
+        if not base:
+            raise ObjectHTMLExtendsError(extends_name)
+
+        inserts = {t: c.strip() for t, c in _INSERT_RE.findall(html)}
+
+        # Replace only specified slots in base (non-strict, indent-aware)
+        return self._apply_slots_non_strict(base.html, inserts)
+
+    def _apply_imports(self, html: str) -> str:
+        import_map = {d.name: d.html for d in self.lib}
+
+        def indent_block(block: str, indent: str) -> str:
+            # Import replaces the whole line, so indent ALL non-empty lines.
+            lines = block.splitlines(True)  # keep line breaks
+            out: list[str] = []
+            for line in lines:
+                if line.strip() == "":
+                    out.append(line)
+                else:
+                    out.append(indent + line)
+            return "".join(out)
+
+        def repl(m: re.Match) -> str:
+            indent = m.group(1)
+            name = m.group(2)
+
+            if name not in import_map:
+                raise ObjectHTMLImportError(name)
+
+            imported = import_map[name]
+            return indent_block(imported, indent)
+
+        return _IMPORT_LINE_RE.sub(repl, html)
+
+    # -------------------------
+    # slot replacement (indent-aware)
+    # -------------------------
+
+    def _line_indent_before(self, html: str, pos: int) -> str:
+        """
+        Return whitespace indent from the start of the line up to pos.
+
+        If the substring from line start to pos contains only whitespace,
+        that whitespace is returned. Otherwise returns empty string.
+        """
+        line_start = html.rfind("\n", 0, pos)
+        line_start = 0 if line_start == -1 else line_start + 1
+        prefix = html[line_start:pos]
+
+        m = re.match(r"[ \t]*", prefix)
+        indent = m.group(0) if m else ""
+        # If there is any non-whitespace before the slot, don't indent-inject.
+        return indent if prefix == indent else ""
+
+    def _indent_multiline_slot_value(self, value: str, indent: str) -> str:
+        """
+        Indent multi-line slot values for {{slot}} replacement.
+
+        IMPORTANT: The indent before {{slot}} already remains in the output,
+        so we indent ONLY lines after the first line.
+        """
+        if "\n" not in value:
+            return value
+
+        lines = value.splitlines(True)  # keepends
+        if not lines:
+            return value
+
+        out = [lines[0]]
+        for line in lines[1:]:
+            if line.strip() == "":
+                out.append(line)
+            else:
+                out.append(indent + line)
+        return "".join(out)
+
+    def _apply_slots_non_strict(self, html: str, values: dict[str, str]) -> str:
+        def repl(m: re.Match) -> str:
+            key = m.group(1)
+            if key not in values:
+                return m.group(0)
+
+            raw = str(values[key])
+            indent = self._line_indent_before(html, m.start())
+            if indent:
+                return self._indent_multiline_slot_value(raw, indent)
+            return raw
+
+        return _SLOT_RE.sub(repl, html)
+
+    def _apply_slots_strict(self, html: str, values: dict[str, str]) -> str:
+        def repl(m: re.Match) -> str:
+            key = m.group(1)
+            if key not in values:
+                raise ObjectHTMLInsertValueError(key)
+
+            raw = str(values[key])
+            indent = self._line_indent_before(html, m.start())
+            if indent:
+                return self._indent_multiline_slot_value(raw, indent)
+            return raw
+
+        return _SLOT_RE.sub(repl, html)

nexom/web/__init__.py

@@ -0,0 +1,5 @@
+from . import request
+from . import response
+from . import path
+from . import cookie
+from . import template

nexom/web/cookie.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+from typing import Any
+from .response import Response
+from ..core.error import CookieInvalidValueError
+
+
+class Cookie:
+    """
+    Represents a single HTTP cookie.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        value: str,
+        *,
+        http_only: bool = True,
+        secure: bool = True,
+        **kwargs: str | int,
+    ) -> None:
+        if name is None:
+            raise CookieInvalidValueError("Cookie name cannot be None")
+        self.name: str = name
+        self.value: str = value
+        self.http_only: bool = http_only
+        self.secure: bool = secure
+        self.attributes: dict[str, str | int] = kwargs
+
+    def __repr__(self) -> str:
+        parts = [f"{self.name}={self.value};"]
+        for k, v in self.attributes.items():
+            parts.append(f"{k}={v};")
+        if self.http_only:
+            parts.append("HttpOnly;")
+        if self.secure:
+            parts.append("Secure;")
+        return " ".join(parts)
+
+    def __str__(self) -> str:
+        return repr(self)
+
+    def set(self, key: str, value: str | int) -> None:
+        """
+        Add or update an attribute of the cookie.
+        """
+        self.attributes[key] = value
+
+    def to_header(self) -> str:
+        """
+        Return the cookie string for Set-Cookie header.
+        """
+        return str(self)
+
+    def response(self, body: str | bytes = "OK") -> Response:
+        """
+        Generate a Response object with this cookie set.
+        """
+        res = Response(body)
+        res.headers.append(("Set-Cookie", self.to_header()))
+        return res
+
+
+class RequestCookies(dict[str, str | None]):
+    """
+    Container for cookies parsed from a request.
+    """
+
+    def __init__(self, **kwargs: str) -> None:
+        super().__init__(kwargs)
+        self.default: str | None = None
+
+    def get(self, key: str) -> str | None:
+        return super().get(key, self.default)

nexom/web/http_status_codes.py

@@ -0,0 +1,72 @@
+http_status_codes = {
+    # 1xx Informational
+    100: "Continue",
+    101: "Switching Protocols",
+    102: "Processing",
+    103: "Early Hints",
+
+    # 2xx Success
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    203: "Non-Authoritative Information",
+    204: "No Content",
+    205: "Reset Content",
+    206: "Partial Content",
+    207: "Multi-Status",
+    208: "Already Reported",
+    226: "IM Used",
+
+    # 3xx Redirection
+    300: "Multiple Choices",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    304: "Not Modified",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+
+    # 4xx Client Errors
+    400: "Bad Request",
+    401: "Unauthorized",
+    402: "Payment Required",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    407: "Proxy Authentication Required",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    411: "Length Required",
+    412: "Precondition Failed",
+    413: "Content Too Large",          # Payload Too Large
+    414: "URI Too Long",
+    415: "Unsupported Media Type",
+    416: "Range Not Satisfiable",
+    417: "Expectation Failed",
+    418: "I'm a teapot",
+    421: "Misdirected Request",
+    422: "Unprocessable Content",      # Unprocessable Entity の代替
+    423: "Locked",
+    424: "Failed Dependency",
+    425: "Too Early",
+    426: "Upgrade Required",
+    428: "Precondition Required",
+    429: "Too Many Requests",
+    431: "Request Header Fields Too Large",
+    451: "Unavailable For Legal Reasons",
+
+    # 5xx Server Errors
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+    505: "HTTP Version Not Supported",
+    506: "Variant Also Negotiates",
+    507: "Insufficient Storage",
+    508: "Loop Detected",
+    510: "Not Extended",
+    511: "Network Authentication Required",
+}

nexom/web/middleware.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Protocol, TypeAlias, Any
+
+from .request import Request
+from .response import Response
+
+
+Handler: TypeAlias = Callable[[Request, dict[str, str | None]], Response]
+
+
+class Middleware(Protocol):
+    """
+    Middleware interface.
+
+    A middleware receives the request, route args, and next handler.
+    It must return a Response.
+    """
+
+    def __call__(self, request: Request, args: dict[str, str | None], next_: Handler) -> Response:
+        ...
+
+
+@dataclass(frozen=True)
+class MiddlewareChain:
+    """
+    Build and execute a middleware chain.
+    """
+    middlewares: tuple[Middleware, ...]
+
+    def wrap(self, handler: Handler) -> Handler:
+        """
+        Wrap the given handler with middlewares (outer -> inner).
+        """
+        def wrapped(request: Request, args: dict[str, str | None]) -> Response:
+            # Build chain lazily per call (safe and simple)
+            def call_at(i: int, req: Request, a: dict[str, str | None]) -> Response:
+                if i >= len(self.middlewares):
+                    return handler(req, a)
+
+                mw = self.middlewares[i]
+
+                def next_(r: Request, aa: dict[str, str | None]) -> Response:
+                    return call_at(i + 1, r, aa)
+
+                return mw(req, a, next_)
+
+            return call_at(0, request, args)
+
+        return wrapped

nexom/web/path.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+import os
+import re
+import json
+from mimetypes import guess_type
+from typing import Callable, Any, Optional, Iterable
+
+from ..core.error import (
+    PathNotFoundError,
+    PathlibTypeError,
+    PathInvalidHandlerTypeError,
+    PathHandlerMissingArgError,
+)
+from .request import Request
+from .response import Response, JsonResponse
+from .middleware import Middleware, MiddlewareChain, Handler
+
+
+class Path:
+    """
+    Represents a route with optional path arguments and its handler.
+    """
+
+    def __init__(self, path: str, handler: Handler, name: str):
+        self.handler = handler
+        self.name: str = name
+
+        path_segments = path.strip("/").split("/")
+        self.path_args: dict[int, str] = {}
+        detection_index = 0
+
+        for idx, segment in enumerate(path_segments):
+            m = re.match(r"{(.*?)}", segment)
+            if m:
+                if detection_index == 0:
+                    detection_index = idx
+                self.path_args[idx] = m.group(1)
+            if idx == len(path_segments) - 1 and detection_index == 0:
+                detection_index = idx + 1
+
+        self.path: str = "/".join(path_segments[:detection_index])
+        self.detection_range: int = detection_index
+        self.args: dict[str, Optional[str]] = {}
+
+    def _read_args(self, request_path: str) -> None:
+        segments = request_path.strip("/").split("/")
+        for idx, arg_name in self.path_args.items():
+            self.args[arg_name] = segments[idx] if idx < len(segments) else None
+
+    def call_handler(self, request: Request, middlewares: tuple[Middleware, ...] = ()) -> Response:
+        try:
+            self._read_args(request.path)
+
+            handler = self.handler
+            if middlewares:
+                handler = MiddlewareChain(middlewares).wrap(handler)
+
+            res = handler(request, self.args)
+            if isinstance(res, dict):
+                return JsonResponse(res)
+            if not isinstance(res, Response):
+                raise PathInvalidHandlerTypeError(self.handler)
+            return res
+        except TypeError as e:
+            if re.search(r"takes \d+ positional arguments? but \d+ were given", str(e)):
+                raise PathHandlerMissingArgError()
+            raise
+
+
+class Static(Path):
+    """
+    Represents a static file route.
+    """
+
+    def __init__(self, path: str, static_directory: str, name: str) -> None:
+        self.static_directory = os.path.abspath(static_directory.rstrip("/"))
+        super().__init__(path, self._access, name)
+
+    def _access(self, request: Request, args: dict[str, Optional[str]]) -> Response:
+        segments = request.path.strip("/").split("/")
+        relative_path = os.path.join(*segments[self.detection_range :]) if len(segments) > self.detection_range else ""
+        abs_path = os.path.abspath(os.path.join(self.static_directory, relative_path))
+
+        if os.path.isdir(abs_path):
+            abs_path = os.path.join(abs_path, "index.html")
+
+        if not abs_path.startswith(self.static_directory) or not os.path.exists(abs_path):
+            raise PathNotFoundError(request.path)
+
+        with open(abs_path, "rb") as f:
+            content = f.read()
+
+        mime_type, _ = guess_type(abs_path)
+        return Response(content, headers=[("Content-Type", mime_type or "application/octet-stream")])
+
+
+class Pathlib(list[Path]):
+    """
+    Collection of Path objects with middleware support.
+    """
+
+    def __init__(self, *paths: Path) -> None:
+        for p in paths:
+            self._check(p)
+        super().__init__(paths)
+        self.raise_if_not_exist: bool = True
+        self.middlewares: list[Middleware] = []
+
+    def _check(self, arg: object) -> None:
+        if not isinstance(arg, Path):
+            raise PathlibTypeError
+
+    def add_middleware(self, *middlewares: Middleware) -> None:
+        self.middlewares.extend(middlewares)
+
+    def get(self, request_path: str) -> Path | None:
+        segments = request_path.rstrip("/").split("/")
+        for p in self:
+            detection_path = "/".join(segments[: p.detection_range])
+            if detection_path == p.path:
+                return p
+
+        if self.raise_if_not_exist:
+            raise PathNotFoundError(request_path)
+        return None