stario 0.1.0__tar.gz

stario-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.3
+Name: stario
+Version: 0.1.0
+Summary: Stario brings back the joy of building web apps
+Author: Adam Bobowski
+Author-email: Adam Bobowski <adam.bobowski@wratilabs.com>
+Requires-Dist: brotli-asgi>=1.4.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: starlette>=0.47.2
+Requires-Dist: uvicorn>=0.35.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <img alt="stario-logo" src="https://raw.githubusercontent.com/bobowski/stario/main/docs/img/stario.png">
+  </picture>
+</p>
+
+<p align="center">
+  <em>✨ Binging back joy and exploration to building web apps ✨</em>
+</p>
+
+---
+
+**Documentation**: Coming soon
+
+**Source Code**: <a href="https://github.com/bobowski/stario/tree/main/stario" target="_blank">https://github.com/bobowski/stario</a>
+
+---
+
+### Stario
+
+Stario is a lightweight ASGI framework built on top of [Starlette](https://www.starlette.io/)
+that brings back the joy of building web apps.
+Focus on building apps rather than passing data between components.
+
+### Why Stario?
+
+- HTML-first - dropping intermediary data layers (e.g. JSON) and using HTML as the primary data format. "Just throw html at user and make them happy."
+- Rapid prototyping - a simple framework to build and test fullstack ideas with minimal setup. Build, see if it works, optimize later (if ever).
+- No-nonsense - no ceremony, no complexity, just build.
+- Learning experience - Learn about web, rather than X or Y language framework. I've learned a lot building this framework. I hope you will too.
+
+It focuses on:
+
+- **HTML-first DX**: return strings or HTML providers, no ceremony.
+- **Realtime by default**: seamless Server-Sent Events (SSE) with [DataStar](https://data-star.dev/) patches/signals.
+- **Great defaults**: Brotli compression out of the box, fast dependency resolution, and caching.
+- **Starlette compatibility**: interop with routes, middleware, and tools you already know.
+
+What you get:
+
+- **A tiny, low-complexity HTTP framework** powered by [Starlette](https://www.starlette.io/) and [DataStar](https://data-star.dev/).
+- **SSE streaming** by simply yielding patches, HTML, or signals (dicts).
+- **Brotli compression** middleware enabled by default (GZip fallback).
+- **Simple DI** via `Annotated` with request params (`QueryParam`, `PathParam`, `Header`, `Cookie`) and `Inject`.
+- **Per-request/app/ttl caching** and configurable run modes (`auto`, `sync`, `thread`).
+- **Header-constrained routes** and a lightweight `StarRouter`.
+- **Few dependencies** and a clear, typed codebase.
+
+---
+
+## Installation
+
+From PyPI (when available):
+
+```shell
+pip install stario
+```
+
+Or from source in this repository:
+
+```shell
+cd stario
+pip install -e .
+```
+
+You'll also want an ASGI server such as [uvicorn](https://www.uvicorn.org/):
+
+```shell
+pip install uvicorn
+```
+
+## Quick start
+
+```python
+# main.py
+import asyncio
+from stario import Stario, Query, Command
+from stario.toys import ToyPage
+
+
+async def home():
+    return ToyPage(
+        """
+        <h2>Realtime responses!</h2>
+        <div data-on-load="@get('/online-counter')">
+            This shows how long the connection has been open.
+        </div>
+        <div id="online-counter"></div>
+        """
+    )
+
+
+async def online_counter():
+    duration = 0
+    interval = 0.01
+    while True:
+        # Yielding strings/patches streams as SSE with DataStar-compatible events
+        yield f"<div id='online-counter'>Online since: {duration:.1f}s</div>"
+        duration += interval
+        await asyncio.sleep(interval)
+
+
+# Building the app
+app = Stario(
+    Query("/", home),
+    Query("/online-counter", online_counter),
+)
+```
+
+Run with Uvicorn:
+
+```shell
+uvicorn main:app --reload
+```
+
+Open `http://127.0.0.1:8000/` in your browser.
+
+---
+
+<p align="center"><i>Stario code is designed & crafted for joy.</i><br/>&mdash; ⭐️ &mdash;</p>

stario-0.1.0/README.md

@@ -0,0 +1,120 @@
+<p align="center">
+  <picture>
+    <img alt="stario-logo" src="https://raw.githubusercontent.com/bobowski/stario/main/docs/img/stario.png">
+  </picture>
+</p>
+
+<p align="center">
+  <em>✨ Binging back joy and exploration to building web apps ✨</em>
+</p>
+
+---
+
+**Documentation**: Coming soon
+
+**Source Code**: <a href="https://github.com/bobowski/stario/tree/main/stario" target="_blank">https://github.com/bobowski/stario</a>
+
+---
+
+### Stario
+
+Stario is a lightweight ASGI framework built on top of [Starlette](https://www.starlette.io/)
+that brings back the joy of building web apps.
+Focus on building apps rather than passing data between components.
+
+### Why Stario?
+
+- HTML-first - dropping intermediary data layers (e.g. JSON) and using HTML as the primary data format. "Just throw html at user and make them happy."
+- Rapid prototyping - a simple framework to build and test fullstack ideas with minimal setup. Build, see if it works, optimize later (if ever).
+- No-nonsense - no ceremony, no complexity, just build.
+- Learning experience - Learn about web, rather than X or Y language framework. I've learned a lot building this framework. I hope you will too.
+
+It focuses on:
+
+- **HTML-first DX**: return strings or HTML providers, no ceremony.
+- **Realtime by default**: seamless Server-Sent Events (SSE) with [DataStar](https://data-star.dev/) patches/signals.
+- **Great defaults**: Brotli compression out of the box, fast dependency resolution, and caching.
+- **Starlette compatibility**: interop with routes, middleware, and tools you already know.
+
+What you get:
+
+- **A tiny, low-complexity HTTP framework** powered by [Starlette](https://www.starlette.io/) and [DataStar](https://data-star.dev/).
+- **SSE streaming** by simply yielding patches, HTML, or signals (dicts).
+- **Brotli compression** middleware enabled by default (GZip fallback).
+- **Simple DI** via `Annotated` with request params (`QueryParam`, `PathParam`, `Header`, `Cookie`) and `Inject`.
+- **Per-request/app/ttl caching** and configurable run modes (`auto`, `sync`, `thread`).
+- **Header-constrained routes** and a lightweight `StarRouter`.
+- **Few dependencies** and a clear, typed codebase.
+
+---
+
+## Installation
+
+From PyPI (when available):
+
+```shell
+pip install stario
+```
+
+Or from source in this repository:
+
+```shell
+cd stario
+pip install -e .
+```
+
+You'll also want an ASGI server such as [uvicorn](https://www.uvicorn.org/):
+
+```shell
+pip install uvicorn
+```
+
+## Quick start
+
+```python
+# main.py
+import asyncio
+from stario import Stario, Query, Command
+from stario.toys import ToyPage
+
+
+async def home():
+    return ToyPage(
+        """
+        <h2>Realtime responses!</h2>
+        <div data-on-load="@get('/online-counter')">
+            This shows how long the connection has been open.
+        </div>
+        <div id="online-counter"></div>
+        """
+    )
+
+
+async def online_counter():
+    duration = 0
+    interval = 0.01
+    while True:
+        # Yielding strings/patches streams as SSE with DataStar-compatible events
+        yield f"<div id='online-counter'>Online since: {duration:.1f}s</div>"
+        duration += interval
+        await asyncio.sleep(interval)
+
+
+# Building the app
+app = Stario(
+    Query("/", home),
+    Query("/online-counter", online_counter),
+)
+```
+
+Run with Uvicorn:
+
+```shell
+uvicorn main:app --reload
+```
+
+Open `http://127.0.0.1:8000/` in your browser.
+
+---
+
+<p align="center"><i>Stario code is designed & crafted for joy.</i><br/>&mdash; ⭐️ &mdash;</p>

stario-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "stario"
+version = "0.1.0"
+description = "Stario brings back the joy of building web apps"
+readme = "README.md"
+authors = [
+    { name = "Adam Bobowski", email = "adam.bobowski@wratilabs.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "brotli-asgi>=1.4.0",
+    "pydantic>=2.11.7",
+    "starlette>=0.47.2",
+    "uvicorn>=0.35.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.6,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.403",
+    "pytest>=8.4.1",
+    "ruff>=0.12.8",
+    "ty>=0.0.1a19",
+]

stario-0.1.0/src/stario/__init__.py

@@ -0,0 +1,26 @@
+from .application import Stario
+from .datastar import LOAD_DATASTAR, Signals
+from .dependencies import Inject
+from .middlewares import BrotliMiddleware
+from .parameters import Body, Cookie, Header, PathParam, QueryParam
+from .routes import Command, Query
+from .routing import StarRoute
+from .types import CacheScope, RunMode
+
+__all__ = [
+    "Stario",
+    "StarRoute",
+    "Query",
+    "Command",
+    "PathParam",
+    "QueryParam",
+    "Body",
+    "Header",
+    "Cookie",
+    "Inject",
+    "Signals",
+    "LOAD_DATASTAR",
+    "BrotliMiddleware",
+    "CacheScope",
+    "RunMode",
+]

stario-0.1.0/src/stario/application.py

@@ -0,0 +1,150 @@
+from typing import (
+    Any,
+    Callable,
+    Mapping,
+    ParamSpec,
+    Protocol,
+    Sequence,
+    TypeVar,
+)
+
+from starlette.applications import Starlette
+from starlette.datastructures import State, URLPath
+from starlette.middleware import Middleware
+from starlette.routing import BaseRoute
+from starlette.types import ASGIApp, ExceptionHandler, Lifespan, Receive, Scope, Send
+
+from stario.middlewares import BrotliMiddleware
+from stario.routing import StarRouter
+
+AppType = TypeVar("AppType", bound="Stario")
+
+P = ParamSpec("P")
+
+
+class _MiddlewareFactory(Protocol[P]):
+    def __call__(
+        self, app: ASGIApp, /, *args: P.args, **kwargs: P.kwargs
+    ) -> ASGIApp: ...
+
+
+class Stario:
+    """
+    Creates a Stario application.
+    It's 'almost' Starlette app, but we push on some of the details.
+    """
+
+    def __init__(
+        self: AppType,
+        *routes: BaseRoute,
+        middleware: Sequence[Middleware] | None = None,
+        compression_middleware: Middleware | None = BrotliMiddleware.as_middleware(),
+        exception_handlers: Mapping[Any, ExceptionHandler] | None = None,
+        lifespan: Lifespan[AppType] | None = None,
+        debug: bool = False,
+        router_class: type[StarRouter] = StarRouter,
+    ) -> None:
+        """Initializes the application.
+
+        Parameters:
+            routes: A list of routes to serve incoming HTTP and WebSocket requests.
+            middleware: A list of middleware to run for every request. A starlette
+                application will always automatically include two middleware classes.
+                `ServerErrorMiddleware` is added as the very outermost middleware, to handle
+                any uncaught errors occurring anywhere in the entire stack.
+                `ExceptionMiddleware` is added as the very innermost middleware, to deal
+                with handled exception cases occurring in the routing or endpoints.
+            compression_middleware: A middleware class to compress the responses.
+                By default we opt for brotli compression with gzip fallback.
+                Parameters are what we think are reasonable for most use cases.
+                If you need tweaking those try `BrotliMiddleware.as_middleware()`.
+            exception_handlers: A mapping of either integer status codes,
+                or exception class types onto callables which handle the exceptions.
+                Exception handler callables should be of the form
+                `handler(request, exc) -> response` and may be either standard functions, or
+                async functions.
+            lifespan: A lifespan context function, which can be used to perform
+                startup and shutdown tasks. This is a newer style that replaces the
+                `on_startup` and `on_shutdown` handlers. Use one or the other, not both.
+            debug: Boolean indicating if debug tracebacks should be returned on errors.
+            router_class: A class to use for the router. By default we use `StarRouter`.
+                You can use this to customize the behaviour of the app, just consider
+                what are the implications :)
+        """
+
+        self.debug = debug
+        self.state = State()
+        self.router = router_class(*routes, lifespan=lifespan)
+        self.exception_handlers = (
+            {} if exception_handlers is None else dict(exception_handlers)
+        )
+        if compression_middleware is not None:
+            middleware = [] if middleware is None else list(middleware)
+            middleware.insert(0, compression_middleware)
+        self.user_middleware = [] if middleware is None else list(middleware)
+        self.middleware_stack: ASGIApp | None = None
+
+        self.cache: dict[Callable, Any] = {}
+
+        # self.dependency_overrides: dict[Callable, Callable] = {}
+        # """
+        # A dictionary with overrides for the dependencies.
+
+        # Each key is the original dependency callable, and the value is the
+        # actual dependency that should be called.
+
+        # This is for testing, to replace expensive dependencies with testing
+        # versions.
+        # """
+
+    @property
+    def routes(self) -> list[BaseRoute]:
+        return self.router.routes
+
+    def url_path_for(self, name: str, /, **path_params: Any) -> URLPath:
+        return self.router.url_path_for(name, **path_params)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        scope["app"] = self
+        if self.middleware_stack is None:
+            # Delegate to Starlette to build the middleware stack
+            # - we like it so there's no need to re-implement it
+            # Starlette expects its own instance; use the instance method to
+            # construct the stack with our attributes
+            self.middleware_stack = Starlette.build_middleware_stack(self)  # type: ignore[arg-type]
+        await self.middleware_stack(scope, receive, send)
+
+    def add(self, route: BaseRoute) -> None:
+        # We diverge from Starlette here because I think having more control over
+        #  the process of adding routes is more important for us in context of this library
+        self.router.add(route)
+
+    def mount(self, path: str, app: ASGIApp, name: str | None = None) -> None:
+        self.router.mount(path, app=app, name=name)
+
+    def host(self, host: str, app: ASGIApp, name: str | None = None) -> None:
+        self.router.host(host, app=app, name=name)
+
+    def add_middleware(
+        self,
+        middleware_class: _MiddlewareFactory[P],
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> None:
+        if self.middleware_stack is not None:
+            raise RuntimeError("Cannot add middleware after an application has started")
+        self.user_middleware.insert(0, Middleware(middleware_class, *args, **kwargs))
+
+    def add_exception_handler(
+        self,
+        exc_class_or_status_code: int | type[Exception],
+        handler: ExceptionHandler,
+    ) -> None:
+        self.exception_handlers[exc_class_or_status_code] = handler
+
+    def add_event_handler(
+        self,
+        event_type: str,
+        func: Callable,
+    ) -> None:
+        self.router.add_event_handler(event_type, func)