slick-framework 0.1.0__py3-none-any.whl

slick/__init__.py

@@ -0,0 +1,52 @@
+"""slick - a slick, minimal ASGI web framework built on the standard library.
+
+Quick taste::
+
+    from slick import Slick
+
+    app = Slick()
+
+    @app.get("/hello/{name}")
+    async def hello(request, name: str):
+        return {"message": f"Hello, {name}!"}
+"""
+
+from .app import CallNext, Slick
+from .datastructures import Headers, QueryParams, State
+from .exceptions import HTTPException
+from .requests import Request
+from .responses import (
+    HTMLResponse,
+    JSONResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    Response,
+    to_response,
+)
+from .routing import Route, Router
+from .server import serve
+from .testclient import TestClient, TestResponse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Slick",
+    "Router",
+    "Route",
+    "Request",
+    "Response",
+    "JSONResponse",
+    "PlainTextResponse",
+    "HTMLResponse",
+    "RedirectResponse",
+    "HTTPException",
+    "Headers",
+    "QueryParams",
+    "State",
+    "CallNext",
+    "TestClient",
+    "TestResponse",
+    "serve",
+    "to_response",
+    "__version__",
+]

slick/app.py

@@ -0,0 +1,203 @@
+"""The :class:`Slick` ASGI application."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import traceback
+from typing import Any, Awaitable, Callable, Optional, TypeVar
+
+from .datastructures import State
+from .exceptions import HTTPException
+from .requests import Request
+from .responses import JSONResponse, PlainTextResponse, Response, to_response
+from .routing import Handler, Router
+from .types import Receive, Scope, Send
+
+__all__ = ["Slick", "CallNext", "Middleware", "ExceptionHandler"]
+
+logger = logging.getLogger("slick")
+
+CallNext = Callable[[Request], Awaitable[Response]]
+Middleware = Callable[[Request, CallNext], Awaitable[Response]]
+ExceptionHandler = Callable[[Request, Exception], Any]
+LifespanHook = Callable[[], Any]
+
+H = TypeVar("H", bound=Handler)
+M = TypeVar("M", bound=Middleware)
+E = TypeVar("E", bound=ExceptionHandler)
+L = TypeVar("L", bound=LifespanHook)
+
+
+async def _maybe_await(value: Any) -> Any:
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+class Slick(Router):
+    """A minimal ASGI 3 application.
+
+    ``Slick`` *is* a :class:`~slick.routing.Router`, so routes are added with
+    ``@app.get(...)``, ``@app.post(...)``, ``@app.route(...)`` etc. An
+    instance is an ASGI callable: run it with any ASGI server, the built-in
+    :func:`slick.serve` development server, or :class:`slick.TestClient`.
+
+    :param debug: when ``True`` unhandled errors return the traceback as the
+        ``500`` response body instead of a generic JSON message.
+    """
+
+    def __init__(self, *, debug: bool = False) -> None:
+        super().__init__()
+        self.debug = debug
+        self.state = State()
+        self._middleware: list[Middleware] = []
+        self._exception_handlers: dict[type[BaseException], ExceptionHandler] = {}
+        self._startup: list[LifespanHook] = []
+        self._shutdown: list[LifespanHook] = []
+        self._param_cache: dict[Handler, Optional[set[str]]] = {}
+
+    # ------------------------------------------------------------------ hooks
+
+    def middleware(self, func: M) -> M:
+        """Register an ``async def mw(request, call_next) -> Response``.
+
+        The first middleware registered is the outermost one: it sees the
+        request first and the response last.
+        """
+        self._middleware.append(func)
+        return func
+
+    def exception_handler(self, exc_class: type[Exception]) -> Callable[[E], E]:
+        """Register ``handler(request, exc)`` for ``exc_class`` and subclasses.
+
+        The handler may be sync or async and may return anything a route
+        handler can return. Registering for :class:`HTTPException` overrides
+        the default ``{"detail": ...}`` JSON error body.
+        """
+
+        def decorator(handler: E) -> E:
+            self._exception_handlers[exc_class] = handler
+            return handler
+
+        return decorator
+
+    def on_startup(self, func: L) -> L:
+        """Run ``func()`` (sync or async) when the ASGI lifespan starts."""
+        self._startup.append(func)
+        return func
+
+    def on_shutdown(self, func: L) -> L:
+        """Run ``func()`` (sync or async) when the ASGI lifespan ends."""
+        self._shutdown.append(func)
+        return func
+
+    # ------------------------------------------------------------------- ASGI
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """ASGI 3 entry point."""
+        if scope["type"] == "lifespan":
+            await self._lifespan(receive, send)
+            return
+        if scope["type"] != "http":
+            raise RuntimeError(f"Slick does not support {scope['type']!r} connections")
+
+        scope["app"] = self
+        request = Request(scope, receive)
+        try:
+            response = await self._build_chain()(request)
+        except Exception:
+            logger.exception("Unhandled error while handling %s %s", request.method, request.path)
+            if self.debug:
+                response = PlainTextResponse(traceback.format_exc(), 500)
+            else:
+                response = JSONResponse({"detail": "Internal Server Error"}, 500)
+            await response(send)
+            # Re-raise so servers can log it and TestClient can surface it.
+            raise
+        await response(send, include_body=request.method != "HEAD")
+
+    async def _lifespan(self, receive: Receive, send: Send) -> None:
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                try:
+                    for hook in self._startup:
+                        await _maybe_await(hook())
+                except Exception:
+                    await send({"type": "lifespan.startup.failed", "message": traceback.format_exc()})
+                    raise
+                await send({"type": "lifespan.startup.complete"})
+            elif message["type"] == "lifespan.shutdown":
+                try:
+                    for hook in self._shutdown:
+                        await _maybe_await(hook())
+                except Exception:
+                    await send({"type": "lifespan.shutdown.failed", "message": traceback.format_exc()})
+                    raise
+                await send({"type": "lifespan.shutdown.complete"})
+                return
+
+    # --------------------------------------------------------------- dispatch
+
+    def _build_chain(self) -> CallNext:
+        call_next: CallNext = self._dispatch
+        for mw in reversed(self._middleware):
+            call_next = self._wrap(mw, call_next)
+        return call_next
+
+    @staticmethod
+    def _wrap(mw: Middleware, inner: CallNext) -> CallNext:
+        async def call(request: Request) -> Response:
+            return to_response(await mw(request, inner))
+
+        return call
+
+    async def _dispatch(self, request: Request) -> Response:
+        """Route the request, call the handler and apply exception handlers."""
+        try:
+            route, params = self.resolve(request.method, request.path)
+            request.scope["path_params"] = params
+            request.scope["route"] = route
+            result = await self._call_handler(route.handler, request, params)
+            return to_response(result)
+        except Exception as exc:
+            handler = self._lookup_exception_handler(exc)
+            if handler is not None:
+                return to_response(await _maybe_await(handler(request, exc)))
+            if isinstance(exc, HTTPException):
+                return JSONResponse({"detail": exc.detail}, exc.status_code, exc.headers)
+            raise
+
+    def _lookup_exception_handler(self, exc: Exception) -> Optional[ExceptionHandler]:
+        for cls in type(exc).__mro__:
+            if cls in self._exception_handlers:
+                return self._exception_handlers[cls]
+        return None
+
+    async def _call_handler(self, handler: Handler, request: Request, params: dict[str, Any]) -> Any:
+        """Call ``handler(request, **matching_path_params)``.
+
+        Path params are passed as keyword arguments only when the handler's
+        signature names them (or accepts ``**kwargs``). Sync handlers run in a
+        worker thread so they don't block the event loop.
+        """
+        accepted = self._accepted_params(handler)
+        kwargs = params if accepted is None else {k: v for k, v in params.items() if k in accepted}
+        if inspect.iscoroutinefunction(handler):
+            return await handler(request, **kwargs)
+        return await _maybe_await(await asyncio.to_thread(handler, request, **kwargs))
+
+    def _accepted_params(self, handler: Handler) -> Optional[set[str]]:
+        """Names of keyword params ``handler`` takes; ``None`` means "any"."""
+        if handler not in self._param_cache:
+            # Skip the first parameter: it always receives the request.
+            parameters = list(inspect.signature(handler).parameters.values())[1:]
+            if any(p.kind is p.VAR_KEYWORD for p in parameters):
+                self._param_cache[handler] = None
+            else:
+                self._param_cache[handler] = {
+                    p.name for p in parameters if p.kind in (p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)
+                }
+        return self._param_cache[handler]

slick/datastructures.py

@@ -0,0 +1,132 @@
+"""Small immutable/mutable mapping types used by requests and responses."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import Iterable, Optional, Union
+from urllib.parse import parse_qsl
+
+__all__ = ["Headers", "QueryParams", "State"]
+
+HeaderInput = Union[Mapping[str, str], Iterable[tuple[str, str]], None]
+
+
+class Headers(Mapping[str, str]):
+    """A case-insensitive, multi-valued HTTP header collection.
+
+    Lookups via ``headers["Content-Type"]`` return the *first* value for that
+    name; use :meth:`getlist` to get all of them. Keys are stored lower-cased.
+    ``Headers`` is mutable through :meth:`__setitem__`, :meth:`append` and
+    :meth:`__delitem__` so that middleware can adjust response headers.
+    """
+
+    def __init__(self, headers: HeaderInput = None) -> None:
+        self._items: list[tuple[str, str]] = []
+        if headers is None:
+            return
+        pairs = headers.items() if isinstance(headers, Mapping) else headers
+        for key, value in pairs:
+            self._items.append((key.lower(), value))
+
+    @classmethod
+    def from_raw(cls, raw: Iterable[tuple[bytes, bytes]]) -> "Headers":
+        """Build headers from an ASGI ``[(name_bytes, value_bytes), ...]`` list."""
+        return cls((k.decode("latin-1"), v.decode("latin-1")) for k, v in raw)
+
+    def raw(self) -> list[tuple[bytes, bytes]]:
+        """Return the headers in ASGI wire format."""
+        return [(k.encode("latin-1"), v.encode("latin-1")) for k, v in self._items]
+
+    def __getitem__(self, key: str) -> str:
+        key = key.lower()
+        for k, v in self._items:
+            if k == key:
+                return v
+        raise KeyError(key)
+
+    def __setitem__(self, key: str, value: str) -> None:
+        """Replace every value of ``key`` with the single ``value``."""
+        key = key.lower()
+        self._items = [(k, v) for k, v in self._items if k != key]
+        self._items.append((key, value))
+
+    def __delitem__(self, key: str) -> None:
+        key = key.lower()
+        if key not in self:
+            raise KeyError(key)
+        self._items = [(k, v) for k, v in self._items if k != key]
+
+    def __contains__(self, key: object) -> bool:
+        return isinstance(key, str) and any(k == key.lower() for k, _ in self._items)
+
+    def __iter__(self) -> Iterator[str]:
+        seen: list[str] = []
+        for k, _ in self._items:
+            if k not in seen:
+                seen.append(k)
+        return iter(seen)
+
+    def __len__(self) -> int:
+        return len(set(k for k, _ in self._items))
+
+    def __repr__(self) -> str:
+        return f"Headers({self._items!r})"
+
+    def append(self, key: str, value: str) -> None:
+        """Add a value without removing existing values (e.g. ``Set-Cookie``)."""
+        self._items.append((key.lower(), value))
+
+    def getlist(self, key: str) -> list[str]:
+        """Return every value for ``key`` in order (possibly empty)."""
+        key = key.lower()
+        return [v for k, v in self._items if k == key]
+
+    def multi_items(self) -> list[tuple[str, str]]:
+        """Return all ``(name, value)`` pairs, including repeated names."""
+        return list(self._items)
+
+
+class QueryParams(Mapping[str, str]):
+    """Parsed URL query string. ``params["x"]`` returns the first value."""
+
+    def __init__(self, query_string: Union[str, bytes] = "") -> None:
+        if isinstance(query_string, bytes):
+            query_string = query_string.decode("latin-1")
+        self._items: list[tuple[str, str]] = parse_qsl(query_string, keep_blank_values=True)
+
+    def __getitem__(self, key: str) -> str:
+        for k, v in self._items:
+            if k == key:
+                return v
+        raise KeyError(key)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(dict.fromkeys(k for k, _ in self._items))
+
+    def __len__(self) -> int:
+        return len(dict.fromkeys(k for k, _ in self._items))
+
+    def __repr__(self) -> str:
+        return f"QueryParams({self._items!r})"
+
+    def getlist(self, key: str) -> list[str]:
+        """Return every value for ``key`` (e.g. ``?tag=a&tag=b``)."""
+        return [v for k, v in self._items if k == key]
+
+    def multi_items(self) -> list[tuple[str, str]]:
+        """Return all ``(key, value)`` pairs, including repeated keys."""
+        return list(self._items)
+
+
+class State:
+    """A plain attribute bag (``app.state.db = ...``, ``request.state.user = ...``)."""
+
+    def __init__(self, **values: object) -> None:
+        self.__dict__.update(values)
+
+    def __repr__(self) -> str:
+        return f"State({self.__dict__!r})"
+
+    def get(self, name: str, default: Optional[object] = None) -> object:
+        """Return attribute ``name`` or ``default`` if it is unset."""
+        return self.__dict__.get(name, default)

slick/exceptions.py

@@ -0,0 +1,39 @@
+"""Exceptions that the framework turns into HTTP responses."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+from typing import Any, Mapping, Optional
+
+__all__ = ["HTTPException"]
+
+
+class HTTPException(Exception):
+    """Raise from a handler or middleware to abort with an HTTP error.
+
+    By default it is rendered as ``{"detail": <detail>}`` JSON with the given
+    status code. ``detail`` defaults to the standard reason phrase.
+
+    Example::
+
+        raise HTTPException(404, "No such user")
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        if detail is None:
+            try:
+                detail = HTTPStatus(status_code).phrase
+            except ValueError:
+                detail = "Error"
+        super().__init__(status_code, detail)
+        self.status_code = status_code
+        self.detail = detail
+        self.headers: dict[str, str] = dict(headers or {})
+
+    def __repr__(self) -> str:
+        return f"HTTPException(status_code={self.status_code!r}, detail={self.detail!r})"

slick/requests.py

@@ -0,0 +1,132 @@
+"""The :class:`Request` object passed to every handler and middleware."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+from urllib.parse import parse_qsl
+
+from .datastructures import Headers, QueryParams, State
+from .exceptions import HTTPException
+from .types import Receive, Scope
+
+__all__ = ["Request"]
+
+
+class Request:
+    """A read-only view over an ASGI HTTP ``scope`` plus its body stream.
+
+    The body is read lazily the first time :meth:`body`, :meth:`text`,
+    :meth:`json` or :meth:`form` is awaited and cached afterwards.
+    """
+
+    def __init__(self, scope: Scope, receive: Optional[Receive] = None) -> None:
+        if scope.get("type") != "http":
+            raise ValueError("Request requires an ASGI 'http' scope")
+        self.scope = scope
+        self._receive = receive
+        self._body: Optional[bytes] = None
+        self._headers: Optional[Headers] = None
+        self._query: Optional[QueryParams] = None
+        # Per-request attribute bag, backed by the scope so it survives
+        # being wrapped in a new Request object.
+        self.state = State()
+        self.state.__dict__ = scope.setdefault("state", {})
+
+    @property
+    def method(self) -> str:
+        """Upper-case HTTP method, e.g. ``"GET"``."""
+        return self.scope["method"].upper()
+
+    @property
+    def path(self) -> str:
+        """The decoded request path, without query string."""
+        return self.scope["path"]
+
+    @property
+    def url(self) -> str:
+        """Reconstructed absolute URL (``scheme://host/path?query``)."""
+        scheme = self.scope.get("scheme", "http")
+        host = self.headers.get("host")
+        if host is None:
+            server = self.scope.get("server") or ("localhost", None)
+            host = server[0] if server[1] in (None, 80, 443) else f"{server[0]}:{server[1]}"
+        qs = self.scope.get("query_string", b"").decode("latin-1")
+        return f"{scheme}://{host}{self.path}" + (f"?{qs}" if qs else "")
+
+    @property
+    def headers(self) -> Headers:
+        """Case-insensitive request headers."""
+        if self._headers is None:
+            self._headers = Headers.from_raw(self.scope.get("headers", []))
+        return self._headers
+
+    @property
+    def query_params(self) -> QueryParams:
+        """Parsed query string (``request.query_params.get("page", "1")``)."""
+        if self._query is None:
+            self._query = QueryParams(self.scope.get("query_string", b""))
+        return self._query
+
+    @property
+    def path_params(self) -> dict[str, Any]:
+        """Values captured from the route pattern, already converted."""
+        return self.scope.setdefault("path_params", {})
+
+    @property
+    def cookies(self) -> dict[str, str]:
+        """Cookies parsed from the ``Cookie`` header."""
+        result: dict[str, str] = {}
+        for chunk in self.headers.get("cookie", "").split(";"):
+            if "=" in chunk:
+                key, _, value = chunk.strip().partition("=")
+                result[key] = value
+        return result
+
+    @property
+    def client(self) -> Optional[tuple[str, int]]:
+        """``(host, port)`` of the peer, if the server provided it."""
+        client = self.scope.get("client")
+        return tuple(client) if client else None  # type: ignore[return-value]
+
+    @property
+    def app(self) -> Any:
+        """The :class:`~slick.Slick` application handling this request."""
+        return self.scope.get("app")
+
+    async def body(self) -> bytes:
+        """Return the full request body (read once, then cached)."""
+        if self._body is None:
+            chunks: list[bytes] = []
+            if self._receive is not None:
+                while True:
+                    message = await self._receive()
+                    if message["type"] == "http.disconnect":
+                        break
+                    chunks.append(message.get("body", b""))
+                    if not message.get("more_body", False):
+                        break
+            self._body = b"".join(chunks)
+        return self._body
+
+    async def text(self) -> str:
+        """Return the body decoded as UTF-8."""
+        return (await self.body()).decode("utf-8")
+
+    async def json(self) -> Any:
+        """Parse the body as JSON.
+
+        Raises :class:`HTTPException` ``400`` if the body is not valid JSON.
+        """
+        raw = await self.body()
+        try:
+            return json.loads(raw)
+        except (ValueError, UnicodeDecodeError) as exc:
+            raise HTTPException(400, "Invalid JSON body") from exc
+
+    async def form(self) -> dict[str, str]:
+        """Parse an ``application/x-www-form-urlencoded`` body."""
+        return dict(parse_qsl((await self.body()).decode("latin-1"), keep_blank_values=True))
+
+    def __repr__(self) -> str:
+        return f"Request({self.method} {self.path})"