without-web 0.0.0__tar.gz → 0.0.2__tar.gz

without_web-0.0.2/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: without-web
+Version: 0.0.2
+Summary: An opinionated HTTP/WebSocket router for without-asgi: trie matching, typed path params, 405-vs-404, mounting, and OpenAPI.
+Author: Josh Karpel
+Author-email: Josh Karpel <josh.karpel@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: without-core==0.0.2
+Requires-Dist: without-asgi==0.0.2
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# without-web
+
+An opinionated HTTP and WebSocket router for
+[`without-asgi`](../without-asgi). `without-asgi` deliberately ships *no* router,
+only the unopinionated boundary and composition tools. `without-web` is the
+opinionated layer on top: t-string patterns with typed parameters, typed request
+extraction, 405-vs-404, mounting, scoped middleware, exception handlers, reverse
+routing (`url_for`), and OpenAPI.
+
+It snaps onto the boundary through nothing but the existing `HttpRouter` type:
+`Router.dispatch` *is* an `HttpRouter[T]`, so `make_asgi_app(http=router.dispatch)`
+just works, and bring-your-own (or no router at all) stays first-class.
+
+```python
+import json
+
+from without_asgi import Response, make_asgi_app
+from without_web import INT, Router, get, path_param
+
+uid = path_param("id", INT)              # one token: a pattern segment AND a typed read
+
+@get(t"/users/{uid}", uid)               # t-string pattern; `@get` returns a Route value
+async def show_user(state, user_id: int):    # user_id is an int, no `assert isinstance`
+    body = json.dumps({"id": user_id}).encode()
+    return Response(status=200, headers=((b"content-type", b"application/json"),), body=body)
+
+router = Router(routes=(show_user,), fallback=not_found)
+app = make_asgi_app(lifespan, http=router.dispatch)
+```
+
+Matching is a pure walk of an immutable trie, so precedence, 405-vs-404, and
+mounting fall out of the structure. Converters and extractors *parse, they don't
+validate*: a path param arrives already typed, and OpenAPI is a *merge* of the
+self-descriptions each layer recovers from structure rather than a blob declared
+by hand. Encoding stays the app's choice, so the router ships no
+`json_response`-style helper.
+
+See the
+[`without-web` guide](https://without.help/without-web/)
+(with the [API reference](https://without.help/reference/without_web/))
+for the full surface: patterns, extractors, streaming input, mounting,
+middleware, exception handlers, reverse routing, OpenAPI, and WebSocket routing.

without_web-0.0.2/README.md

@@ -0,0 +1,42 @@
+# without-web
+
+An opinionated HTTP and WebSocket router for
+[`without-asgi`](../without-asgi). `without-asgi` deliberately ships *no* router,
+only the unopinionated boundary and composition tools. `without-web` is the
+opinionated layer on top: t-string patterns with typed parameters, typed request
+extraction, 405-vs-404, mounting, scoped middleware, exception handlers, reverse
+routing (`url_for`), and OpenAPI.
+
+It snaps onto the boundary through nothing but the existing `HttpRouter` type:
+`Router.dispatch` *is* an `HttpRouter[T]`, so `make_asgi_app(http=router.dispatch)`
+just works, and bring-your-own (or no router at all) stays first-class.
+
+```python
+import json
+
+from without_asgi import Response, make_asgi_app
+from without_web import INT, Router, get, path_param
+
+uid = path_param("id", INT)              # one token: a pattern segment AND a typed read
+
+@get(t"/users/{uid}", uid)               # t-string pattern; `@get` returns a Route value
+async def show_user(state, user_id: int):    # user_id is an int, no `assert isinstance`
+    body = json.dumps({"id": user_id}).encode()
+    return Response(status=200, headers=((b"content-type", b"application/json"),), body=body)
+
+router = Router(routes=(show_user,), fallback=not_found)
+app = make_asgi_app(lifespan, http=router.dispatch)
+```
+
+Matching is a pure walk of an immutable trie, so precedence, 405-vs-404, and
+mounting fall out of the structure. Converters and extractors *parse, they don't
+validate*: a path param arrives already typed, and OpenAPI is a *merge* of the
+self-descriptions each layer recovers from structure rather than a blob declared
+by hand. Encoding stays the app's choice, so the router ships no
+`json_response`-style helper.
+
+See the
+[`without-web` guide](https://without.help/without-web/)
+(with the [API reference](https://without.help/reference/without_web/))
+for the full surface: patterns, extractors, streaming input, mounting,
+middleware, exception handlers, reverse routing, OpenAPI, and WebSocket routing.

without_web-0.0.2/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "without-web"
+version = "0.0.2"
+description = "An opinionated HTTP/WebSocket router for without-asgi: trie matching, typed path params, 405-vs-404, mounting, and OpenAPI."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "without-core==0.0.2",
+    "without-asgi==0.0.2",
+]
+
+[[project.authors]]
+name = "Josh Karpel"
+email = "josh.karpel@gmail.com"
+
+[tool.uv.sources.without-core]
+workspace = true
+
+[tool.uv.sources.without-asgi]
+workspace = true

without_web-0.0.2/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "without-web"
+version = "0.0.2"
+description = "An opinionated HTTP/WebSocket router for without-asgi: trie matching, typed path params, 405-vs-404, mounting, and OpenAPI."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Josh Karpel", email = "josh.karpel@gmail.com" },
+]
+requires-python = ">=3.14"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "without-core==0.0.2",
+    "without-asgi==0.0.2",
+]
+
+[tool.uv.sources]
+without-core = { workspace = true }
+without-asgi = { workspace = true }

without_web-0.0.2/src/without_web/__init__.py

@@ -0,0 +1,159 @@
+from without_web.converters import FLOAT
+from without_web.converters import INT
+from without_web.converters import PATH
+from without_web.converters import STR
+from without_web.converters import UUID
+from without_web.converters import Converter
+from without_web.exceptions import ExceptionRecover
+from without_web.exceptions import WebsocketExceptionRecover
+from without_web.exceptions import catching
+from without_web.exceptions import catching_websocket
+from without_web.extractors import BufferedRequest
+from without_web.extractors import ExtractionError
+from without_web.extractors import Extractor
+from without_web.extractors import HttpRequestHead
+from without_web.extractors import RequestHead
+from without_web.extractors import WebsocketRequestHead
+from without_web.extractors import body
+from without_web.extractors import catch_all
+from without_web.extractors import header_param
+from without_web.extractors import http_scope
+from without_web.extractors import into
+from without_web.extractors import once
+from without_web.extractors import optional
+from without_web.extractors import path_param
+from without_web.extractors import query_param
+from without_web.extractors import websocket_scope
+from without_web.handlers import Reply
+from without_web.handlers import Returned
+from without_web.handlers import WebsocketReturned
+from without_web.handlers import delete
+from without_web.handlers import get
+from without_web.handlers import handle
+from without_web.handlers import handle_stream
+from without_web.handlers import head
+from without_web.handlers import options
+from without_web.handlers import patch
+from without_web.handlers import post
+from without_web.handlers import put
+from without_web.handlers import ws
+from without_web.openapi import Body
+from without_web.openapi import Describable
+from without_web.openapi import HeaderParam
+from without_web.openapi import QueryParam
+from without_web.openapi import ResponseSpec
+from without_web.openapi import RouteSpec
+from without_web.openapi import SchemaFor
+from without_web.openapi import SchemaRef
+from without_web.openapi import Sequence
+from without_web.openapi import Single
+from without_web.openapi import describe
+from without_web.openapi import openapi
+from without_web.patterns import CatchAll
+from without_web.patterns import Literal
+from without_web.patterns import Param
+from without_web.patterns import PathSpec
+from without_web.patterns import Segment
+from without_web.patterns import split_path
+from without_web.responses import buffered
+from without_web.router import Delegate
+from without_web.router import Endpoint
+from without_web.router import HttpEndpoint
+from without_web.router import Match
+from without_web.router import Pattern
+from without_web.router import Reversible
+from without_web.router import Route
+from without_web.router import Router
+from without_web.router import WebsocketDelegate
+from without_web.router import WebsocketEndpoint
+from without_web.router import WebsocketRoute
+from without_web.router import WebsocketRouter
+from without_web.router import delegate
+from without_web.router import mount
+from without_web.router import route
+from without_web.router import url_for
+from without_web.router import with_middleware
+from without_web.router import ws_delegate
+from without_web.router import ws_mount
+from without_web.router import ws_route
+
+__all__ = [
+    "FLOAT",
+    "INT",
+    "PATH",
+    "STR",
+    "UUID",
+    "Body",
+    "BufferedRequest",
+    "CatchAll",
+    "Converter",
+    "Delegate",
+    "Describable",
+    "Endpoint",
+    "ExceptionRecover",
+    "ExtractionError",
+    "Extractor",
+    "HeaderParam",
+    "HttpEndpoint",
+    "HttpRequestHead",
+    "Literal",
+    "Match",
+    "Param",
+    "PathSpec",
+    "Pattern",
+    "QueryParam",
+    "Reply",
+    "RequestHead",
+    "ResponseSpec",
+    "Returned",
+    "Reversible",
+    "Route",
+    "RouteSpec",
+    "Router",
+    "SchemaFor",
+    "SchemaRef",
+    "Segment",
+    "Sequence",
+    "Single",
+    "WebsocketDelegate",
+    "WebsocketEndpoint",
+    "WebsocketExceptionRecover",
+    "WebsocketRequestHead",
+    "WebsocketReturned",
+    "WebsocketRoute",
+    "WebsocketRouter",
+    "body",
+    "buffered",
+    "catch_all",
+    "catching",
+    "catching_websocket",
+    "delegate",
+    "delete",
+    "describe",
+    "get",
+    "handle",
+    "handle_stream",
+    "head",
+    "header_param",
+    "http_scope",
+    "into",
+    "mount",
+    "once",
+    "openapi",
+    "optional",
+    "options",
+    "patch",
+    "path_param",
+    "post",
+    "put",
+    "query_param",
+    "route",
+    "split_path",
+    "url_for",
+    "websocket_scope",
+    "with_middleware",
+    "ws",
+    "ws_delegate",
+    "ws_mount",
+    "ws_route",
+]

without_web-0.0.2/src/without_web/converters.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from collections.abc import Mapping
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Generic
+from typing import TypeVar
+
+# Covariant: `V` appears only in `parse`'s return, so `Converter[int]` is a
+# `Converter[object]`. That lets a path-param token store its converter as
+# `Converter[object]` while `path_param` keeps the precise `V` for the handler.
+# The legacy `TypeVar` is needed because PEP 695's inferred variance treats a
+# (frozen) dataclass field as invariant; the variance is sound here.
+_V_co = TypeVar("_V_co", covariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class Converter(Generic[_V_co]):  # noqa: UP046 - PEP 695 infers a frozen dataclass field as invariant; the covariant TypeVar is deliberate (see above)
+    """
+    A path-segment parser paired with the JSON Schema it parses into.
+
+    `parse` turns a single matched segment into a typed value, raising
+    `ValueError` to *reject* a segment that does not fit (`int` against `"abc"`).
+    Rejection is not a handler-side error: it makes that trie branch fail to
+    match so the walk backtracks to a sibling, ultimately a 404 if nothing
+    matches (parse, don't validate).
+
+    `schema` is the half the router contributes to OpenAPI for a path parameter
+    that uses this converter: the router owns the path-param schema because it
+    owns the converter.
+
+    `name` is the converter's identity (and its OpenAPI parameter style); a
+    typed-token pattern reuses the converter *value* directly
+    (`path_param("id", INT)`), so the name, parse, type, and schema are all
+    declared in one place. Equality and hashing are by `name` alone (a converter
+    is a trie key), so `parse` and `schema` are excluded from comparison.
+    """
+
+    name: str
+    parse: Callable[[str], _V_co] = field(compare=False)
+    schema: Mapping[str, object] = field(compare=False)
+
+
+STR: Converter[str] = Converter(name="str", parse=str, schema={"type": "string"})
+INT: Converter[int] = Converter(name="int", parse=int, schema={"type": "integer"})
+FLOAT: Converter[float] = Converter(name="float", parse=float, schema={"type": "number"})
+UUID: Converter[uuid.UUID] = Converter(name="uuid", parse=uuid.UUID, schema={"type": "string", "format": "uuid"})
+# `path` is the catch-all converter: the trie consumes the rest of the request
+# target into one segment, so its `parse` is the identity on the joined string.
+# Security note: the value is the raw remaining path, *not* normalized. It can
+# contain `..` and encoded separators, so an app that joins it onto a filesystem
+# path, a proxy target, or a redirect URL MUST normalize and confine it first
+# (e.g. resolve and check it stays within a base directory); the router itself
+# never touches the filesystem, so it cannot do this for you.
+PATH: Converter[str] = Converter(name="path", parse=str, schema={"type": "string"})

without_web-0.0.2/src/without_web/exceptions.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from collections.abc import Awaitable
+from collections.abc import Callable
+
+from without import Processor
+from without import Stream
+from without_asgi import HttpHandler
+from without_asgi import HttpScope
+from without_asgi import Outbound
+from without_asgi import Response
+from without_asgi import ResponseStart
+from without_asgi import WebsocketAccept
+from without_asgi import WebsocketClose
+from without_asgi import WebsocketHandler
+from without_asgi import WebsocketOutbound
+from without_asgi import WebsocketScope
+from without_asgi import encode_response
+from without_asgi.routing import HttpMiddleware
+from without_asgi.routing import WebsocketMiddleware
+
+# An app's exception policy: given a raised exception, produce the reply to send
+# instead, or `None` to let it propagate. Writing this as `match exc:` (or
+# `try/except`) gives natural narrowing and full control, so there is no registry
+# of types to handlers and no per-type erasure: the policy is just a function.
+type ExceptionRecover = Callable[[Exception], Awaitable[Response | None]]
+type WebsocketExceptionRecover = Callable[[Exception], Awaitable[WebsocketClose | None]]
+
+
+def catching(recover: ExceptionRecover) -> HttpMiddleware[object]:
+    """
+    Build middleware that maps exceptions to a response, before the status commits.
+
+    Exception handling is not a new mechanism: it is a `Middleware` that wraps a
+    handler and watches its outbound stream. `recover` is the app's policy: it is
+    handed a raised exception and returns the `Response` to send instead, or
+    `None` to let the exception propagate. There is deliberately no registry of
+    `type -> handler`: a `recover` written as `match exc:` narrows each case to
+    its real type (no `assert isinstance`) and can re-raise, chain, or do async
+    work, all of which a heterogeneous mapping could not express without a cast.
+
+    Honest limitation: the mapping applies only while the status line can still
+    be set, i.e. until the first `ResponseStart` flows out. Informational events
+    (`EarlyHint`, `ResponseDebug`) precede it and do not commit the status, so an
+    exception after them can still be mapped; once `ResponseStart` is on the
+    wire the exception re-raises, because the handler can abort but not re-status.
+    """
+
+    def middleware(handler: HttpHandler, _state: object, scope: HttpScope) -> HttpHandler:
+        async def recovering(exc: Exception) -> tuple[Outbound, ...] | None:
+            response = await recover(exc)
+            return None if response is None else encode_response(response)
+
+        return _guarding(handler, _is_response_start, recovering)
+
+    return middleware
+
+
+def catching_websocket(recover: WebsocketExceptionRecover) -> WebsocketMiddleware[object]:
+    """
+    The WebSocket sibling of `catching`, mapping exceptions to a close.
+
+    The equivalent commit point is `WebsocketAccept`: before the handshake is
+    accepted a close still rejects the connection (the server turns it into a
+    `403`), so a mapped exception becomes that `WebsocketClose`. Once accepted
+    the connection is established and the exception re-raises. `recover` returns
+    the `WebsocketClose` to send, or `None` to propagate.
+    """
+
+    def middleware(handler: WebsocketHandler, _state: object, scope: WebsocketScope) -> WebsocketHandler:
+        async def recovering(exc: Exception) -> tuple[WebsocketOutbound, ...] | None:
+            close = await recover(exc)
+            return None if close is None else (close,)
+
+        return _guarding(handler, _is_websocket_accept, recovering)
+
+    return middleware
+
+
+def _guarding[In, Out](
+    handler: Processor[In, Out],
+    commits: Callable[[Out], bool],
+    recover: Callable[[Exception], Awaitable[tuple[Out, ...] | None]],
+) -> Processor[In, Out]:
+    # The shared core: relay the handler's outbound stream, remembering whether
+    # the protocol's commit event has gone out. An exception before the commit is
+    # offered to `recover`; once committed (or unrecognized) it propagates.
+    async def processor(inputs: Stream[In]) -> AsyncIterator[Out]:
+        committed = False  # pragma: no mutate - only read as a bool, None is falsy too
+        try:
+            async for event in handler(inputs):
+                committed = committed or commits(event)
+                yield event
+        except Exception as exc:
+            replacement = None if committed else await recover(exc)
+            if replacement is None:
+                raise
+            for event in replacement:
+                yield event
+
+    return processor
+
+
+def _is_response_start(event: Outbound) -> bool:
+    return isinstance(event, ResponseStart)
+
+
+def _is_websocket_accept(event: WebsocketOutbound) -> bool:
+    return isinstance(event, WebsocketAccept)