API reference#

Generated directly from Hayavega's own docstrings and type hints (the same ones mypy checks in CI) — this page can't drift from the actual public API the way a hand-maintained second copy would.

Routing#

path #

path(pattern: str, view: Callable, methods: tuple[str, ...] = ('GET',)) -> Route

Register a route. The root route is written as an empty string.

Source code in src/hayavega/routing.py

def path(pattern: str, view: Callable, methods: tuple[str, ...] = ("GET",)) -> Route:
    """Register a route. The root route is written as an empty string."""
    return Route(pattern.strip("/"), view, tuple(method.upper() for method in methods))

hayavega.rest.api_route #

api_route(pattern: str, view: Callable, methods: Iterable[str] = ('GET',), *, secured: bool = False, request_schema: dict | None = None, responses: dict[int, dict] | None = None) -> Route

Create a JSON endpoint. Views may return a dict/list or a Response.

secured, request_schema, and responses describe the endpoint for the generated OpenAPI document at /openapi.json. secured marks the endpoint as requiring a Bearer session token. request_schema is a JSON Schema dict for the request body. responses maps a status code to {"description": str, "schema": dict} (schema is optional). None of these change runtime behavior -- omit them and Hayavega documents the endpoint with its previous generic fallback schema.

view may be async def when deployed under hayavega.asgi (see DEPLOYMENT.md): the wrapper stays a coroutine function itself so the ASGI runtime awaits it directly rather than running it in a thread.

Source code in src/hayavega/rest.py

def api_route(
    pattern: str,
    view: Callable,
    methods: Iterable[str] = ("GET",),
    *,
    secured: bool = False,
    request_schema: dict | None = None,
    responses: dict[int, dict] | None = None,
) -> Route:
    """Create a JSON endpoint. Views may return a dict/list or a Response.

    ``secured``, ``request_schema``, and ``responses`` describe the endpoint
    for the generated OpenAPI document at ``/openapi.json``. ``secured``
    marks the endpoint as requiring a Bearer session token. ``request_schema``
    is a JSON Schema dict for the request body. ``responses`` maps a status
    code to ``{"description": str, "schema": dict}`` (``schema`` is optional).
    None of these change runtime behavior -- omit them and Hayavega documents
    the endpoint with its previous generic fallback schema.

    ``view`` may be ``async def`` when deployed under ``hayavega.asgi`` (see
    ``DEPLOYMENT.md``): the wrapper stays a coroutine function itself so the
    ASGI runtime awaits it directly rather than running it in a thread.
    """

    if inspect.iscoroutinefunction(view):

        async def endpoint(request):
            result = await view(request)
            return result if isinstance(result, Response) else json_response(result)
    else:

        def endpoint(request):  # type: ignore[misc]
            result = view(request)
            return result if isinstance(result, Response) else json_response(result)

    route = path(pattern, endpoint, tuple(methods))
    return Route(route.pattern, route.view, route.methods, is_api=True, secured=secured, request_schema=request_schema, responses=responses)

Request & Response#

hayavega.request.Request `dataclass` #

Request(method: str, path: str, query_params: dict[str, list[str]], body: bytes, headers: dict[str, str], remote_addr: str = '', is_secure: bool = False, raw_query: str = '')

cookies `property` #

cookies: dict[str, str]

Return safely parsed request cookies.

files #

files() -> dict[str, UploadedFile]

Parse a multipart/form-data body into uploaded files, keyed by field name (the first file, if more than one was submitted under the same field name). Returns {} for any other content type. Requires python-multipart -- see MultipartUnavailableError.

Source code in src/hayavega/request.py

def files(self) -> dict[str, UploadedFile]:
    """Parse a `multipart/form-data` body into uploaded files, keyed
    by field name (the first file, if more than one was submitted
    under the same field name). Returns `{}` for any other content
    type. Requires `python-multipart` -- see `MultipartUnavailableError`.
    """
    content_type = self.headers.get("Content-Type", "")
    if not content_type.startswith("multipart/form-data"):
        return {}
    _, files = _parse_multipart(content_type, self.body)
    return {name: items[0] for name, items in files.items()}

form #

form() -> dict[str, str]

Parse a form body into plain fields -- last value wins per field. Handlesapplication/x-www-form-urlencoded(the default) andmultipart/form-data(needspython-multipart; seefiles()`).

Source code in src/hayavega/request.py

def form(self) -> dict[str, str]:
    """Parse a form body into plain fields -- `last value wins per
    field. Handles `application/x-www-form-urlencoded` (the
    default) and `multipart/form-data` (needs `python-multipart`;
    see `files()`)."""
    content_type = self.headers.get("Content-Type", "")
    if content_type.startswith("multipart/form-data"):
        fields, _ = _parse_multipart(content_type, self.body)
        return fields
    return {name: values[-1] for name, values in parse_qs(self.body.decode("utf-8")).items()}

hayavega.response.Response `dataclass` #

Response(body: str | bytes, status: int = 200, content_type: str = 'text/html; charset=utf-8', headers: tuple[tuple[str, str], ...] = ())

hayavega.response.json_response #

json_response(data, status: int = 200, headers: tuple[tuple[str, str], ...] = ()) -> Response

Source code in src/hayavega/response.py

def json_response(data, status: int = 200, headers: tuple[tuple[str, str], ...] = ()) -> Response:
    return Response(
        msgspec.json.encode(data),
        status=status,
        content_type="application/json; charset=utf-8",
        headers=headers,
    )