asgi-tools 1.2.0__cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

asgi_tools/__init__.py

@@ -0,0 +1,65 @@
+"""ASGI-Tools -- Tools to make ASGI Applications"""
+
+from __future__ import annotations
+
+from http_router import InvalidMethodError, NotFoundError
+
+from .app import App
+from .errors import ASGIConnectionClosedError, ASGIError, ASGIInvalidMethodError, ASGINotFoundError
+from .middleware import (
+    BackgroundMiddleware,
+    LifespanMiddleware,
+    RequestMiddleware,
+    ResponseMiddleware,
+    RouterMiddleware,
+    StaticFilesMiddleware,
+)
+from .request import Request
+from .response import (
+    Response,
+    ResponseError,
+    ResponseFile,
+    ResponseHTML,
+    ResponseJSON,
+    ResponseRedirect,
+    ResponseSSE,
+    ResponseStream,
+    ResponseText,
+    ResponseWebSocket,
+    parse_response,
+)
+from .view import HTTPView
+
+__all__ = (  # noqa: RUF022
+    # Errors
+    "ASGIConnectionClosedError",
+    "ASGIError",
+    "ASGIInvalidMethodError",
+    "ASGINotFoundError",
+    "InvalidMethodError",
+    "NotFoundError",
+    # App/handlers
+    "App",
+    "HTTPView",
+    # Request/Response
+    "Request",
+    "Response",
+    "ResponseError",
+    "ResponseFile",
+    "ResponseHTML",
+    "ResponseJSON",
+    "ResponseRedirect",
+    "ResponseSSE",
+    "ResponseStream",
+    "ResponseText",
+    "ResponseWebSocket",
+    # Middleware
+    "BackgroundMiddleware",
+    "LifespanMiddleware",
+    "RequestMiddleware",
+    "ResponseMiddleware",
+    "RouterMiddleware",
+    "StaticFilesMiddleware",
+    # Utils
+    "parse_response",
+)

asgi_tools/_compat.py

@@ -0,0 +1,259 @@
+"""Compatibility layer."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from asyncio import create_task, gather, sleep
+from concurrent.futures import ALL_COMPLETED, FIRST_COMPLETED
+from contextlib import asynccontextmanager, suppress
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncGenerator,
+    Awaitable,
+    Callable,
+    Coroutine,
+    Union,
+    cast,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from .types import TJSON
+
+
+from json import dumps, loads
+
+from sniffio import current_async_library
+
+__all__ = (
+    "aio_cancel",
+    "aio_sleep",
+    "aio_spawn",
+    "aio_stream_file",
+    "aio_wait",
+    "aiofile_installed",
+    "create_task",
+    "curio_installed",
+    "json_dumps",
+    "json_loads",
+    "trio_installed",
+)
+
+try:
+    from asyncio import timeout as asyncio_timeout  # type: ignore[attr-defined]
+except ImportError:  # python 310
+    from async_timeout import timeout as asyncio_timeout  # type: ignore[no-redef]
+
+
+aiofile_installed = False
+with suppress(ImportError):
+    import aiofile
+
+    aiofile_installed = True
+
+
+trio_installed = False
+with suppress(ImportError):
+    from trio import TooSlowError, open_memory_channel, open_nursery
+    from trio import fail_after as trio_fail_after
+    from trio import open_file as trio_open_file
+    from trio import sleep as trio_sleep
+
+    trio_installed = True
+
+
+curio_installed = False
+with suppress(ImportError):
+    from curio import TaskGroup as CurioTaskGroup
+    from curio import TaskTimeout
+    from curio import aopen as curio_open
+    from curio import sleep as curio_sleep
+    from curio import spawn as curio_spawn
+    from curio import timeout_after as curio_fail_after
+
+    curio_installed = True
+
+
+def aio_sleep(seconds: float = 0) -> Awaitable:
+    """Return sleep coroutine."""
+
+    if trio_installed and current_async_library() == "trio":
+        return trio_sleep(seconds)  # noqa: ASYNC105
+
+    if curio_installed and current_async_library() == "curio":
+        return curio_sleep(seconds)
+
+    return sleep(seconds)
+
+
+@asynccontextmanager
+async def aio_spawn(fn: Callable[..., Awaitable], *args, **kwargs):
+    """Spawn a given coroutine."""
+    if trio_installed and current_async_library() == "trio":
+        async with open_nursery() as tasks:
+            tasks.start_soon(fn, *args, **kwargs)
+            yield tasks
+
+    elif curio_installed and current_async_library() == "curio":
+        task = await curio_spawn(fn, *args, **kwargs)
+        yield task
+        await task.join()  # type: ignore [union-attr]
+
+    else:
+        coro = cast("Coroutine", fn(*args, **kwargs))
+        task = create_task(coro)
+        yield task
+        await task
+
+
+@asynccontextmanager
+async def aio_timeout(timeout: float):  # noqa: ASYNC109
+    """Fail after the given timeout."""
+    if not timeout:
+        yield
+        return
+
+    if trio_installed and current_async_library() == "trio":
+        try:
+            with trio_fail_after(timeout):
+                yield
+
+        except TooSlowError:
+            raise TimeoutError(f"{timeout}s.") from None
+
+    elif curio_installed and current_async_library() == "curio":
+        try:
+            async with curio_fail_after(timeout):
+                yield
+
+        except TaskTimeout:
+            raise TimeoutError(f"{timeout}s.") from None
+
+    else:
+        async with asyncio_timeout(timeout):
+            yield
+
+
+async def aio_wait(*aws: Awaitable, strategy: str = ALL_COMPLETED) -> Any:
+    """Run the coros concurrently, wait for all completed or cancel others.
+
+    Only ALL_COMPLETED, FIRST_COMPLETED are supported.
+    """
+    if not aws:
+        return None
+
+    if trio_installed and current_async_library() == "trio":
+        send_channel, receive_channel = open_memory_channel(0)  # type: ignore[var-annotated]
+
+        async with open_nursery() as n:
+            for aw in aws:
+                n.start_soon(trio_jockey, aw, send_channel)
+
+            results = []
+            for _ in aws:
+                results.append(await receive_channel.receive())
+                if strategy == FIRST_COMPLETED:
+                    n.cancel_scope.cancel()
+                    return results[0]
+
+            return results
+
+    if curio_installed and current_async_library() == "curio":
+        wait = all if strategy == ALL_COMPLETED else any
+        async with CurioTaskGroup(wait=wait) as g:
+            [await g.spawn(aw) for aw in aws]
+
+        return g.results if strategy == ALL_COMPLETED else g.result
+
+    aws = tuple(create_task(aw) if inspect.iscoroutine(aw) else aw for aw in aws)
+    done, pending = await asyncio.wait(aws, return_when=strategy)  # type: ignore[type-var]
+    if strategy != ALL_COMPLETED:
+        for task in pending:
+            task.cancel()  # type: ignore[attr-defined]
+        await gather(*pending, return_exceptions=True)
+        return next(iter(done)).result()  # type: ignore[attr-defined]
+
+    return [t.result() for t in done]  # type: ignore[attr-defined]
+
+
+async def aio_cancel(task: Union[asyncio.Task, Any]):
+    """Cancel asyncio task / trio nursery."""
+    if isinstance(task, asyncio.Task):
+        return task.cancel()
+
+    if trio_installed and current_async_library() == "trio":
+        return task.cancel_scope.cancel()
+
+    if curio_installed and current_async_library() == "curio":
+        return await task.cancel()
+    return None
+
+
+async def aio_stream_file(
+    filepath: Union[str, Path], chunk_size: int = 32 * 1024
+) -> AsyncGenerator[bytes, None]:
+    if trio_installed and current_async_library() == "trio":
+        async with await trio_open_file(filepath, "rb") as fp:
+            while True:
+                chunk = cast("bytes", await fp.read(chunk_size))
+                if not chunk:
+                    break
+                yield chunk
+
+    elif curio_installed and current_async_library() == "curio":
+        async with curio_open(filepath, "rb") as fp:
+            while True:
+                chunk = cast("bytes", await fp.read(chunk_size))
+                if not chunk:
+                    break
+                yield chunk
+
+    else:
+        if not aiofile_installed:
+            raise RuntimeError(
+                "`aiofile` is required to return files with asyncio",
+            )
+
+        async with aiofile.AIOFile(filepath, mode="rb") as fp:
+            async for chunk in aiofile.Reader(  # type: ignore [assignment]
+                fp, chunk_size=chunk_size
+            ):
+                yield cast("bytes", chunk)
+
+
+async def trio_jockey(coro: Awaitable, channel):
+    """Wait for the given coroutine and send result back to the given channel."""
+    await channel.send(await coro)
+
+
+def json_dumps(content) -> bytes:
+    """Emulate orjson."""
+    return dumps(  # type: ignore [call-arg]
+        content,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def json_loads(obj: Union[bytes, str]) -> TJSON:
+    """Emulate orjson."""
+    if isinstance(obj, bytes):
+        obj = obj.decode("utf-8")
+    return loads(obj)
+
+
+with suppress(ImportError):
+    from ujson import dumps as udumps
+    from ujson import loads as json_loads  # type: ignore[assignment]
+
+    def json_dumps(content) -> bytes:
+        """Emulate orjson."""
+        return udumps(content, ensure_ascii=False).encode("utf-8")
+
+
+with suppress(ImportError):
+    from orjson import dumps as json_dumps  # type: ignore[assignment,no-redef]
+    from orjson import loads as json_loads  # type: ignore[assignment,no-redef]

asgi_tools/app.py

@@ -0,0 +1,303 @@
+"""Simple Base for ASGI Apps."""
+
+from __future__ import annotations
+
+from functools import partial
+from inspect import isclass
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, cast
+
+from http_router import PrefixedRoute
+
+from asgi_tools.router import Router
+
+from .errors import ASGIConnectionClosedError, ASGIInvalidMethodError, ASGINotFoundError
+from .logs import logger
+from .middleware import LifespanMiddleware, StaticFilesMiddleware, parse_response
+from .request import Request
+from .response import Response, ResponseError
+from .utils import iscoroutinefunction, to_awaitable
+
+if TYPE_CHECKING:
+    import logging
+    from pathlib import Path
+
+    from http_router.types import TMethods, TPath
+
+    from .types import (
+        TASGIReceive,
+        TASGIScope,
+        TASGISend,
+        TExceptionHandler,
+        TVExceptionHandler,
+    )
+
+T = TypeVar("T")
+TRouteHandler = TypeVar("TRouteHandler", bound=Callable[[Request], Any])
+TCallable = TypeVar("TCallable", bound=Callable[..., Any])
+
+
+class App:
+    """A helper class to build ASGI applications quickly and efficiently.
+
+    Features:
+        - Routing with flexible path and method matching
+        - ASGI-Tools :class:`Request`, :class:`Response` integration
+        - Exception management and custom error handlers
+        - Static files serving
+        - Lifespan events (startup/shutdown)
+        - Simple middleware support
+
+    :param debug: Enable debug mode (more logging, raise unhandled exceptions)
+    :type debug: bool
+    :param logger: Custom logger for the application
+    :type logger: logging.Logger
+    :param static_url_prefix: URL prefix for static files
+    :type static_url_prefix: str
+    :param static_folders: List of folders to serve static files from
+    :type static_folders: Optional[list[str | Path]]
+    :param trim_last_slash: Treat "/path" and "/path/" as the same route
+    :type trim_last_slash: bool
+    :raises ValueError: If static_url_prefix is set without static_folders
+    :raises TypeError: If static_folders is not a list of strings or Paths
+    :raises RuntimeError: If the app is not an ASGI application
+
+    Example:
+        >>> from asgi_tools import App
+        >>> app = App()
+        >>> @app.route("/")
+        ... async def homepage(request):
+        ...     return "Hello, World!"
+    """
+
+    exception_handlers: dict[type[BaseException], TExceptionHandler]
+
+    def __init__(
+        self,
+        *,
+        debug: bool = False,
+        logger: logging.Logger = logger,
+        static_url_prefix: str = "/static",
+        static_folders: list[str | Path] | None = None,
+        trim_last_slash: bool = False,
+    ):
+        """Initialize the ASGI application with routing, logging, static files,
+           and lifespan support.
+
+        :param debug: Enable debug mode (more logging, raise unhandled exceptions)
+        :type debug: bool
+        :param logger: Custom logger for the application
+        :type logger: logging.Logger
+        :param static_url_prefix: URL prefix for static files
+        :type static_url_prefix: str
+        :param static_folders: List of folders to serve static files from
+        :type static_folders: Optional[list[str|Path]]
+        :param trim_last_slash: Treat "/path" and "/path/" as the same route
+        :type trim_last_slash: bool
+        """
+
+        # Register base exception handlers
+        self.exception_handlers = {
+            ASGIConnectionClosedError: to_awaitable(lambda _, __: None),
+        }
+
+        # Setup routing
+        self.router = Router(
+            trim_last_slash=trim_last_slash, validator=callable, converter=to_awaitable
+        )
+
+        # Setup logging
+        self.logger = logger
+
+        # Setup app
+        self.__app__ = self.__match__
+
+        # Setup lifespan
+        self.lifespan = LifespanMiddleware(
+            self.__process__, ignore_errors=not debug, logger=self.logger
+        )
+
+        # Enable middleware for static files
+        if static_folders and static_url_prefix:
+            md = StaticFilesMiddleware.setup(folders=static_folders, url_prefix=static_url_prefix)
+            self.middleware(md)
+
+        # Debug mode
+        self.debug = debug
+
+        # Handle unknown exceptions
+        if not debug:
+
+            async def handle_unknown_exception(_: Request, exc: BaseException) -> Response:
+                self.logger.exception(exc)
+                return ResponseError.INTERNAL_SERVER_ERROR()
+
+            self.exception_handlers[Exception] = handle_unknown_exception
+
+        self.internal_middlewares: list = []
+
+    async def __call__(self, scope: TASGIScope, receive: TASGIReceive, send: TASGISend) -> None:
+        """ASGI entrypoint. Converts the given scope into a request and processes it."""
+        await self.lifespan(scope, receive, send)
+
+    async def __process__(self, scope: TASGIScope, receive: TASGIReceive, send: TASGISend):
+        """Internal request processing: builds a Request, calls the app, and handles exceptions."""
+        scope["app"] = self
+        request = Request(scope, receive, send)
+        try:
+            response: Response | None = await self.__app__(request, receive, send)
+            if response is not None:
+                await response(scope, receive, send)
+
+        # Handle exceptions
+        except BaseException as exc:
+            for etype in type(exc).mro():
+                if etype in self.exception_handlers:
+                    await parse_response(
+                        await self.exception_handlers[etype](request, exc),
+                    )(scope, receive, send)
+                    break
+            else:
+                if isinstance(exc, Response):
+                    await exc(scope, receive, send)
+                else:
+                    raise
+
+    async def __match__(
+        self, request: Request, _: TASGIReceive, send: TASGISend
+    ) -> Response | None:
+        """Finds and calls a route handler, parses the response, and handles routing exceptions."""
+        scope = request.scope
+        path = f"{ scope.get('root_path', '') }{ scope['path'] }"
+        try:
+            match = self.router(path, scope.get("method", "GET"))
+
+        except ASGINotFoundError as exc:
+            raise ResponseError.NOT_FOUND() from exc
+
+        except ASGIInvalidMethodError as exc:
+            raise ResponseError.METHOD_NOT_ALLOWED() from exc
+
+        scope["endpoint"] = match.target
+        scope["path_params"] = {} if match.params is None else match.params
+        handler = cast("Callable[[Request], Any]", match.target)
+        response = await handler(request)
+
+        if scope["type"] == "http":
+            return parse_response(response)
+
+        # TODO: Do we need to close websockets automatically?
+        # if scope_type == "websocket" send websocket.close
+
+        return None
+
+    def __route__(self, router: Router, *prefixes: str, **_) -> "App":
+        """Mount this app as a nested application under given prefixes."""
+        for prefix in prefixes:
+            route = RouteApp(prefix, set(), target=self)
+            router.dynamic.insert(0, route)
+        return self
+
+    def middleware(self, md: TCallable, *, insert_first: bool = False) -> TCallable:
+        """Register a middleware for the application.
+
+        Middleware can be a coroutine (request/response) or a regular callable (lifespan).
+
+        :param md: The middleware function or class
+        :type md: TCallable
+        :param insert_first: If True, insert as the first middleware
+        :type insert_first: bool
+        :return: The registered middleware
+        :rtype: TCallable
+
+        Example:
+            >>> @app.middleware
+            ... async def log_requests(handler, request):
+            ...     print(f"Request: {request.method} {request.url}")
+            ...     return await handler(request)
+        """
+        # Register as a simple middleware
+        if iscoroutinefunction(md):
+            if md not in self.internal_middlewares:
+                if insert_first:
+                    self.internal_middlewares.insert(0, md)
+                else:
+                    self.internal_middlewares.append(md)
+
+            app = self.__match__
+            for md_ in reversed(self.internal_middlewares):
+                app = partial(md_, app)
+
+            self.__app__ = app
+
+        else:
+            self.lifespan.bind(md(self.lifespan.app))
+
+        return md
+
+    def route(
+        self, *paths: TPath, methods: TMethods | None = None, **opts: Any
+    ) -> Callable[[TRouteHandler], TRouteHandler]:
+        """Register a route handler.
+
+        :param paths: One or more URL paths to match
+        :type paths: TPath
+        :param methods: HTTP methods to match (GET, POST, etc.)
+        :type methods: Optional[TMethods]
+        :param opts: Additional options for the route
+        :type opts: Any
+        :return: Decorator function
+        :rtype: Callable[[TRouteHandler], TRouteHandler]
+        """
+        return self.router.route(*paths, methods=methods, **opts)
+
+    def on_startup(self, fn: Callable) -> None:
+        """Register a startup event handler.
+
+        :param fn: The function to call on startup
+        :type fn: Callable
+        """
+        return self.lifespan.on_startup(fn)
+
+    def on_shutdown(self, fn: Callable) -> None:
+        """Register a shutdown event handler.
+
+        :param fn: The function to call on shutdown
+        :type fn: Callable
+        """
+        return self.lifespan.on_shutdown(fn)
+
+    def on_error(self, etype: type[BaseException]):
+        """Register a custom exception handler for a given exception type.
+
+        :param etype: The exception type to handle
+        :type etype: type[BaseException]
+        :return: A decorator to register the handler
+        :rtype: Callable
+
+        Example:
+            >>> @app.on_error(TimeoutError)
+            ... async def timeout_handler(request, error):
+            ...     return 'Timeout occurred'
+        """
+        assert isclass(etype), f"Invalid exception type: {etype}"
+        assert issubclass(etype, BaseException), f"Invalid exception type: {etype}"
+
+        def recorder(handler: TVExceptionHandler) -> TVExceptionHandler:
+            self.exception_handlers[etype] = to_awaitable(handler)
+            return handler
+
+        return recorder
+
+
+class RouteApp(PrefixedRoute):
+    """Custom route to submount an application under a given path prefix."""
+
+    def __init__(self, path: str, methods: set, target: App):
+        """Create a submounted app callable for the given prefix."""
+        path = path.rstrip("/")
+
+        def app(request: Request):
+            subrequest = request.__copy__(path=request.path[len(path) :])
+            return target.__app__(subrequest, request.receive, request.send)
+
+        super().__init__(path, methods, app)

asgi_tools/constants.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from typing import Final
+
+BASE_ENCODING: Final = "latin-1"
+DEFAULT_CHARSET: Final = "utf-8"

asgi_tools/errors.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class ASGIError(Exception):
+    """Base class for ASGI-Tools Errors."""
+
+
+class ASGIConnectionClosedError(ASGIError):
+    """ASGI-Tools connection closed error."""
+
+
+class ASGIDecodeError(ASGIError, ValueError):
+    """ASGI-Tools decoding error."""
+
+
+class ASGINotFoundError(ASGIError):
+    """Raise when http handler not found."""
+
+
+class ASGIInvalidMethodError(ASGIError):
+    """Raise when http method not found."""
+
+
+class ASGIInvalidMessageError(ASGIError):
+    """Raise when unexpected message received."""