bareASGI 5.0.0a2__py3-none-any.whl

bareasgi/__init__.py

@@ -0,0 +1,46 @@
+"""bareASGI exports"""
+
+
+from bareutils import (
+    text_reader,
+    text_writer,
+    bytes_reader,
+    bytes_writer
+)
+
+from .application import Application
+from .http import (
+    HttpRequest,
+    HttpResponse,
+    HttpRequestCallback,
+    HttpMiddlewareCallback,
+    PushResponse,
+    make_middleware_chain
+)
+from .lifespan import LifespanRequest
+from .typing import Scope
+from .websockets import WebSocket, WebSocketRequest, WebSocketRequestCallback
+
+__all__ = [
+    "Scope",
+
+    "text_reader",
+    "text_writer",
+    "bytes_reader",
+    "bytes_writer",
+
+    "Application",
+
+    "HttpRequest",
+    "HttpResponse",
+    "HttpRequestCallback",
+    "HttpMiddlewareCallback",
+    "PushResponse",
+    "make_middleware_chain",
+
+    "LifespanRequest",
+
+    "WebSocket",
+    "WebSocketRequest",
+    "WebSocketRequestCallback",
+]

bareasgi/application.py

@@ -0,0 +1,177 @@
+"""The ASGI application"""
+
+import logging
+from typing import Any, Callable, Final
+
+from bareutils import text_writer
+
+from .http import (
+    HttpRouter,
+    HttpResponse,
+    HttpMiddlewareCallback,
+    HttpRequestCallback
+)
+from .lifespan import LifespanRequestHandler
+from .websockets import (
+    WebSocketRouter,
+    WebSocketRequestCallback,
+    WebSocketMiddlewareCallback
+)
+
+from .basic_router import BasicHttpRouter, BasicWebSocketRouter
+from .core_application import CoreApplication
+
+LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
+
+DEFAULT_NOT_FOUND_RESPONSE: Final[HttpResponse] = HttpResponse(
+    404,
+    [(b'content-type', b'text/plain')],
+    text_writer('Not Found')
+)
+
+type HttpMiddlewares = list[HttpMiddlewareCallback]
+type WebSocketMiddlewares = list[WebSocketMiddlewareCallback]
+
+
+class Application(CoreApplication):
+    """A class to hold the application."""
+
+    def __init__(
+            self,
+            *,
+            middlewares: HttpMiddlewares | None = None,
+            http_router: HttpRouter | None = None,
+            ws_middlewares: WebSocketMiddlewares | None = None,
+            ws_router: WebSocketRouter | None = None,
+            startup_handlers: list[LifespanRequestHandler] | None = None,
+            shutdown_handlers: list[LifespanRequestHandler] | None = None,
+            not_found_response: HttpResponse = DEFAULT_NOT_FOUND_RESPONSE,
+            info: dict[str, Any] | None = None
+    ) -> None:
+        """Construct the application
+
+        ```python
+        from bareasgi import (
+            Application,
+            Scope,
+            HttpRequest,
+            HttpResponse,
+            text_reader,
+            text_writer
+        )
+
+        async def http_request_callback(request: HttpRequest) -> HttpResponse:
+            text = await text_reader(request.body)
+            return HttpResponse(
+                200,
+                [(b'content-type', b'text/plain')],
+                text_writer('This is not a test')
+            )
+
+        import uvicorn
+
+        app = Application()
+        app.http_router.add({'GET', 'POST', 'PUT', 'DELETE'}, '/{path}', http_request_callback)
+
+        uvicorn.run(app, port=9009)
+        ```
+
+        Args:
+            middlewares (HttpMiddlewares | None, optional): Optional
+                middleware callbacks. Defaults to None.
+            http_router (HttpRouter | None, optional): Optional router to for
+                http routes. Defaults to None.
+            ws_middlewares (WebSocketMiddlewares | None, optional):
+                Optional middleware callbacks. Defaults to None.
+            ws_router (WebSocketRouter | None, optional): Optional
+                router for web routes. Defaults to None.
+            startup_handlers (Optional[List[LifespanHandler]], optional): Optional
+                handlers to run at startup. Defaults to None.
+            shutdown_handlers (Optional[List[LifespanHandler]], optional): Optional
+                handlers to run at shutdown. Defaults to None.
+            not_found_response (Optional[HttpResponse], optional): Optional not
+                found (404) response. Defaults to DEFAULT_NOT_FOUND_RESPONSE.
+            info (dict[str, Any] | None, optional): Optional
+                dictionary for user data. Defaults to None.
+        """
+        super().__init__(
+            middlewares or [],
+            http_router or BasicHttpRouter(not_found_response),
+            ws_middlewares or [],
+            ws_router or BasicWebSocketRouter(),
+            startup_handlers or [],
+            shutdown_handlers or [],
+            info or {}
+        )
+
+    def on_http_request(
+            self,
+            methods: set[str],
+            path: str
+    ) -> Callable[[HttpRequestCallback], HttpRequestCallback]:
+        """A decorator to add an http route handler to the application
+
+        Args:
+            methods (AbstractSet[str]): The http methods, e.g. {{'POST', 'PUT'}
+            path (str): The path
+
+        Returns:
+            Callable[[HttpRequestCallback], HttpRequestCallback]: The decorated
+                request.
+        """
+        def decorator(callback: HttpRequestCallback) -> Callable:
+            self.http_router.add(methods, path, callback)
+            return callback
+
+        return decorator
+
+    def on_ws_request(
+            self,
+            path: str
+    ) -> Callable[[WebSocketRequestCallback], WebSocketRequestCallback]:
+        """A decorator to add a websocket route handler to the application
+
+        Args:
+            path (str): The path
+
+        Returns:
+            Callable[[WebSocketRequestCallback], WebSocketRequestCallback]: The
+                decorated handler
+        """
+        def decorator(
+                callback: WebSocketRequestCallback
+        ) -> WebSocketRequestCallback:
+            self.ws_router.add(path, callback)
+            return callback
+
+        return decorator
+
+    def on_startup(
+            self,
+            callback: LifespanRequestHandler
+    ) -> LifespanRequestHandler:
+        """A decorator to add a startup handler to the application
+
+        Args:
+            callback (LifespanRequestHandler): The startup handler.
+
+        Returns:
+            LifespanRequestHandler: The decorated handler.
+        """
+        self.startup_handlers.append(callback)
+        return callback
+
+    def on_shutdown(
+            self,
+            callback: LifespanRequestHandler
+    ) -> LifespanRequestHandler:
+        """A decorator to add a startup handler to the application
+
+        Args:
+            callback (LifespanRequestHandler): The shutdown handler.
+
+        Returns:
+            LifespanRequestHandler: The decorated handler.
+        """
+        self.shutdown_handlers.append(callback)
+        return callback

bareasgi/basic_router/__init__.py

@@ -0,0 +1,9 @@
+"""Basic routing support"""
+
+from .http_router import BasicHttpRouter
+from .web_socket_router import BasicWebSocketRouter
+
+__all__ = [
+    "BasicHttpRouter",
+    "BasicWebSocketRouter"
+]

bareasgi/basic_router/http_router.py

@@ -0,0 +1,91 @@
+"""
+Http Routing
+"""
+
+import logging
+from typing import Any, Final, Mapping
+
+from ..http import HttpRouter, HttpRequest, HttpResponse, HttpRequestCallback
+
+from .path_definition import PathDefinition
+
+LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
+
+type Route = tuple[PathDefinition, HttpRequestCallback]
+
+
+class BasicHttpRouter(HttpRouter):
+    """A basic http routing implementation"""
+
+    def __init__(self, not_found_response: HttpResponse) -> None:
+        self._routes: dict[str, list[Route]] = {}
+        self._not_found_response = not_found_response
+
+    @property
+    def not_found_response(self) -> HttpResponse:
+        return self._not_found_response
+
+    @not_found_response.setter
+    def not_found_response(self, value: HttpResponse) -> None:
+        self._not_found_response = value
+
+    def add(
+            self,
+            methods: set[str],
+            path: str,
+            callback: HttpRequestCallback
+    ) -> None:
+        LOGGER.debug('Adding route for %s on "%s".', methods, path)
+        path_definition = PathDefinition(path)
+        for method in methods:
+            self.add_route(method, path_definition, callback)
+
+    def add_route(
+            self,
+            method: str,
+            path_definition: PathDefinition,
+            callback: HttpRequestCallback
+    ) -> None:
+        """Add a route to a callback for a method and path definition
+
+        Args:
+            method (str): The method.
+            path_definition (PathDefinition): The path definition
+            callback (HttpRequestCallback): The callback
+        """
+        path_definition_list = self._routes.setdefault(method, [])
+        path_definition_list.append((path_definition, callback))
+
+    async def _not_found(
+            self,
+            _request: HttpRequest
+    ) -> HttpResponse:
+        return self._not_found_response
+
+    def resolve(
+            self,
+            method: str,
+            path: str
+    ) -> tuple[HttpRequestCallback, Mapping[str, Any]]:
+        path_definition_list = self._routes.get(method)
+        if path_definition_list:
+            for path_definition, handler in path_definition_list:
+                is_match, matches = path_definition.match(path)
+                if is_match:
+                    LOGGER.debug(
+                        'Matched %s on "%s" for %s matching %s.',
+                        method,
+                        path,
+                        path_definition,
+                        matches,
+                        extra={'method': method, 'path': path}
+                    )
+                    return handler, matches
+
+        LOGGER.warning(
+            'Failed to find a match for %s on "%s".',
+            method,
+            path,
+            extra={'method': method, 'path': path}
+        )
+        return self._not_found, {}

bareasgi/basic_router/path_definition.py

@@ -0,0 +1,94 @@
+"""
+Path definitions used by the routers.
+"""
+
+from typing import Any, Mapping
+
+from .path_segment import PathSegment
+
+
+class PathDefinition:
+    """A class capturing a matchable path"""
+
+    NO_MATCH: tuple[bool, Mapping[str, Any]] = (False, {})
+
+    def __init__(self, path: str) -> None:
+        """Create a path definition."""
+        # Save for hashing
+        self.path = path
+
+        if not path.startswith('/'):
+            raise ValueError('Paths must be absolute')
+        # Trim off the leading '/'
+        path = path[1:]
+
+        # Handle paths that end with a '/'
+        if path.endswith('/'):
+            path = path[:-1]
+            self.ends_with_slash = True
+        else:
+            self.ends_with_slash = False
+
+        # Parse each path segment.
+        self.segments: list[PathSegment] = []
+        for segment in path.split('/'):
+            self.segments.append(PathSegment(segment))
+
+    def match(self, path: str) -> tuple[bool, Mapping[str, Any]]:
+        """Try to match the given path with this path definition
+
+        Args:
+            path (str): The path to match
+
+        Raises:
+            Exception: If the path is not absolute.
+
+        Returns:
+            Tuple[bool, Mapping[str, Any]]: A tuple of is_match and matches.
+        """
+        if not path.startswith('/'):
+            raise ValueError('Paths must be absolute')
+
+        # Handle trailing slash
+        if path[1:].endswith('/') and self.segments[-1].type != 'path':
+            if not self.ends_with_slash:
+                return self.NO_MATCH
+            path = path[:-1]
+        elif self.ends_with_slash:
+            return self.NO_MATCH
+
+        parts = path[1:].split('/')
+
+        # Must have at least the same number of segments.
+        if len(parts) < len(self.segments):
+            return self.NO_MATCH
+
+        # Keep the matches we find.
+        matches: dict[str, Any | None] = {}
+
+        # A path with more segments is allowed if the last segment is a variable of type 'path'.
+        if len(parts) > len(self.segments):
+            last_segment = self.segments[-1]
+            if last_segment.type != 'path':
+                return self.NO_MATCH
+            index = len(self.segments) - 1
+            matches[last_segment.name] = '/'.join(parts[index:])
+            parts = parts[:index]
+
+        # Now the path parts and segments are the same length we can check them.
+        for part, segment in zip(parts, self.segments):
+            is_match, name, value = segment.match(part)
+            if not is_match:
+                return self.NO_MATCH
+            if name:
+                matches[name] = value
+
+        return True, matches
+
+    def __hash__(self) -> int:
+        return hash(self.path)
+
+    def __str__(self):
+        return f'<PathDefinition: segments={self.segments}, ends_with_slash={self.ends_with_slash}>'
+
+    __repr__ = __str__

bareasgi/basic_router/path_segment.py

@@ -0,0 +1,92 @@
+"""
+A segment of a path.
+"""
+
+from datetime import datetime
+from typing import Any, Callable, Mapping
+
+from ..utils import parse_json_datetime
+
+type Converter = Callable[[Any, str | None], Any]
+
+
+class ParseError(Exception):
+    """Exception raised on a parse error"""
+
+
+def _parse_datetime(value, fmt) -> datetime | None:
+    return datetime.strptime(value, fmt) if fmt else parse_json_datetime(value)
+
+
+CONVERTERS: Mapping[str, Converter] = {
+    'str': lambda value, fmt: value,
+    'int': lambda value, fmt: int(value),
+    'float': lambda value, fmt: float(value),
+    'datetime': _parse_datetime,
+    'path': lambda value, fmt: value,
+}
+
+
+class PathSegment:
+    """A class representing the segment of a path"""
+
+    def __init__(self, segment: str) -> None:
+        """Create a path segment
+        A path segment can be an absolute name "foo", a variable "{foo}", a
+        variable and type "{foo:int}" or a variable, type, and
+        format "{foo:datetime:Y-m-dTH:M:S}".
+
+        Valid types are: int, float, str, datetime, path.
+        The 'path' type catches all following segments, so '/foo/{rest:path}'
+        would match '/foo/bar/grum'.
+        """
+        self.type: str | None = None
+        self.format: str | None = None
+
+        if segment.startswith('{') and segment.endswith('}'):
+            self.name, *type_and_format = segment[1:-1].split(':', maxsplit=3)
+            if len(type_and_format) == 2:
+                self.type, self.format = type_and_format
+            elif len(type_and_format) == 1:
+                self.type, self.format = type_and_format[0], None
+            else:
+                self.type, self.format = 'str', None
+            if self.type and self.type not in CONVERTERS:
+                raise TypeError('Unknown type')
+            self.is_variable = True
+        elif segment.startswith('{') or segment.endswith('}'):
+            raise ParseError("Invalid substitution segment")
+        elif '{' in segment or '}' in segment:
+            raise ParseError("Literal segment contains invalid characters")
+        else:
+            self.name = segment
+            self.is_variable = False
+            self.type = None
+            self.format = None
+
+    def match(self, value: str) -> tuple[bool, str | None, Any | None]:
+        """Try to match a segment.
+
+        :param value: The path segment to match.
+        :return: A tuple of: is_match:bool, variable_name:str, value:any
+        """
+        if self.is_variable:
+            # noinspection PyBroadException
+            try:
+                converter = CONVERTERS[self.type or 'str']
+                value = converter(value, self.format) if self.type else value
+                return True, self.name, value
+            except ValueError:
+                return False, None, None
+        else:
+            return value == self.name, None, None
+
+    def __str__(self):
+        return '<PathSegment: ' \
+            f'name="{self.name}"' \
+            f', is_variable={self.is_variable}' \
+            f', type="{self.type}"' \
+            f', format="{self.format}"' \
+               '>'
+
+    __repr__ = __str__

bareasgi/basic_router/web_socket_router.py

@@ -0,0 +1,48 @@
+"""
+A basic Websocket router.
+"""
+
+import logging
+from typing import Any, Final, Mapping
+
+from ..websockets import WebSocketRouter, WebSocketRequestCallback
+
+from .path_definition import PathDefinition
+
+LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
+
+type Route = tuple[PathDefinition, WebSocketRequestCallback]
+
+
+class BasicWebSocketRouter(WebSocketRouter):
+    """The implementation of a basic Websocket router"""
+
+    def __init__(self) -> None:
+        self._routes: list[Route] = []
+
+    def add(self, path: str, callback: WebSocketRequestCallback) -> None:
+        self._routes.append((PathDefinition(path), callback))
+
+    def resolve(
+            self,
+            path: str
+    ) -> tuple[WebSocketRequestCallback, Mapping[str, Any]]:
+        for path_definition, handler in self._routes:
+            is_match, matches = path_definition.match(path)
+            if is_match:
+                LOGGER.debug(
+                    'Matched "%s"" with %s.',
+                    path,
+                    path_definition,
+                    extra={'path': path}
+                )
+                return handler, matches
+
+        LOGGER.warning(
+            'Failed to find a match for "%s".',
+            path,
+            extra={'path': path}
+        )
+
+        # TODO: Should we have a "route not found" handler?
+        raise ValueError(f"Unable to find route for {path}")

bareasgi/core_application.py

@@ -0,0 +1,143 @@
+"""The core ASGI application"""
+
+import logging
+from typing import Any, Final, cast
+
+from .http import (
+    HTTPScope,
+    ASGIHTTPReceiveCallable,
+    ASGIHTTPSendCallable,
+)
+from .lifespan import (
+    LifespanScope,
+    ASGILifespanReceiveCallable,
+    ASGILifespanSendCallable,
+)
+from .websockets.typing import (
+    WebSocketScope,
+    ASGIWebSocketReceiveCallable,
+    ASGIWebSocketSendCallable,
+)
+from .typing import (
+    Scope,
+    ASGISendCallable,
+    ASGIReceiveCallable
+)
+
+from .http import HttpInstance, HttpRouter, HttpMiddlewareCallback
+from .lifespan import LifespanRequestHandler, LifespanInstance
+from .websockets import (
+    WebSocketRouter,
+    WebSocketInstance,
+    WebSocketMiddlewareCallback
+)
+
+LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
+
+
+class CoreApplication:
+    """The core ASGI application"""
+
+    def __init__(
+            self,
+            middlewares: list[HttpMiddlewareCallback],
+            http_router: HttpRouter,
+            ws_middlewares: list[WebSocketMiddlewareCallback],
+            ws_router: WebSocketRouter,
+            startup_handlers: list[LifespanRequestHandler],
+            shutdown_handlers: list[LifespanRequestHandler],
+            info: dict[str, Any]
+    ) -> None:
+        self.info = info
+        self.middlewares = middlewares
+        self.http_router = http_router
+        self.ws_router = ws_router
+        self.ws_middlewares = ws_middlewares
+        self.startup_handlers = startup_handlers
+        self.shutdown_handlers = shutdown_handlers
+
+    async def _handle_lifespan_request(
+            self,
+            scope: LifespanScope,
+            receive: ASGILifespanReceiveCallable,
+            send: ASGILifespanSendCallable
+    ) -> None:
+        instance = LifespanInstance(
+            scope,
+            self.startup_handlers,
+            self.shutdown_handlers,
+            self.info
+        )
+        await instance.process(receive, send)
+
+    async def _handle_http_request(
+            self,
+            scope: HTTPScope,
+            receive: ASGIHTTPReceiveCallable,
+            send: ASGIHTTPSendCallable
+    ) -> None:
+        instance = HttpInstance(
+            scope,
+            self.http_router,
+            self.middlewares,
+            self.info
+        )
+        await instance.process(receive, send)
+
+    async def _handle_websocket_request(
+            self,
+            scope: WebSocketScope,
+            receive: ASGIWebSocketReceiveCallable,
+            send: ASGIWebSocketSendCallable
+    ) -> None:
+        instance = WebSocketInstance(
+            scope,
+            self.ws_router,
+            self.ws_middlewares,
+            self.info
+        )
+        await instance.process(receive, send)
+
+    async def __call__(
+            self,
+            scope: Scope,
+            receive: ASGIReceiveCallable,
+            send: ASGISendCallable
+    ) -> None:
+        """This is the entrypoint to the ASGI application.
+
+        Args:
+            scope (Scope): The ASGI scope.
+            receive (ASGIReceiveCallable): A coroutine to receive ASGI events.
+            send (ASGISendCallable): A coroutine to send ASGI events.
+
+        Raises:
+            ValueError: For an unknown event type.
+        """
+        if scope['type'] == 'http':
+
+            await self._handle_http_request(
+                cast(HTTPScope, scope),
+                cast(ASGIHTTPReceiveCallable, receive),
+                cast(ASGIHTTPSendCallable, send)
+            )
+
+        elif scope['type'] == 'lifespan':
+
+            await self._handle_lifespan_request(
+                cast(LifespanScope, scope),
+                cast(ASGILifespanReceiveCallable, receive),
+                cast(ASGILifespanSendCallable, send)
+            )
+
+        elif scope['type'] == 'websocket':
+
+            await self._handle_websocket_request(
+                cast(WebSocketScope, scope),
+                cast(ASGIWebSocketReceiveCallable, receive),
+                cast(ASGIWebSocketSendCallable, send)
+            )
+
+        else:
+
+            raise ValueError('Unknown event type: ' + scope['type'])