GitHub

API reference for router.

HttpRouter: routes added by layers, matched with find-my-way.

Add routes with add / add_all / use layers, then serve them (or to_web_handler / to_http_effect, or in_memory_client in tests). A handler's errors and requirements flow into the served app's types through the route layers' requirements (Requires / Raises).

Values

AttributeTypeDescription
layerLayer[HttpRouter]

The HttpRouter service, configured by RouterConfig.

paramsEffect[Mapping[str, str], Never, RouteContext]

The matched route's path parameters.

disable_loggerLayer[Never, Never, Requires[Never] | Raises[Never]]

Route middleware turning off the request log for the routes it wraps.

makeEffect[HttpRouterService]

Types

TypeDefinitionDescription
GlobalProvidedtype GlobalProvided = HttpServerRequest | Scope
Providedtype Provided = HttpServerRequest | Scope | ParsedSearchParams | RouteContext
Handlertype Handler[E, R] = HttpServerResponse | Effect[HttpServerResponse, E, R] | Callable[[ServerRequest], Effect[HttpServerResponse, E, R]]
Methodtype Method = Literal['*', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'QUERY', 'HEAD']

Classes

Functions

add

add(method: Method, path: str, handler: HttpServerResponse | Effect[HttpServerResponse, Never, Provided] | Callable[[ServerRequest], Effect[HttpServerResponse, Never, Provided]], *, uninterruptible: bool = False) -> Layer[Never, Never, HttpRouter]
add[E](method: Method, path: str, handler: Effect[HttpServerResponse, E, Provided] | Callable[[ServerRequest], Effect[HttpServerResponse, E, Provided]], *, uninterruptible: bool = False) -> Layer[Never, Never, HttpRouter | Raises[E]]
add[R](method: Method, path: str, handler: Effect[HttpServerResponse, Never, R | Provided] | Callable[[ServerRequest], Effect[HttpServerResponse, Never, R | Provided]], *, uninterruptible: bool = False) -> Layer[Never, Never, HttpRouter | Requires[R]]
add[E, R](method: Method, path: str, handler: Effect[HttpServerResponse, E, R | Provided] | Callable[[ServerRequest], Effect[HttpServerResponse, E, R | Provided]], *, uninterruptible: bool = False) -> Layer[Never, Never, HttpRouter | Requires[R] | Raises[E]]

A layer adding one route.

ParameterTypeDescription
method
path
handler
uninterruptible= False
@overload
def add(
    method: Method,
    path: str,
    handler: HttpServerResponse
    | Effect[HttpServerResponse, Never, Provided]
    | Callable[[ServerRequest], Effect[HttpServerResponse, Never, Provided]],
    *,
    uninterruptible: bool = False,
) -> Layer[Never, Never, HttpRouter]: ...
@overload
def add[E](
    method: Method,
    path: str,
    handler: Effect[HttpServerResponse, E, Provided]
    | Callable[[ServerRequest], Effect[HttpServerResponse, E, Provided]],
    *,
    uninterruptible: bool = False,
) -> Layer[Never, Never, HttpRouter | Raises[E]]: ...
@overload
def add[R](
    method: Method,
    path: str,
    handler: Effect[HttpServerResponse, Never, R | Provided]
    | Callable[[ServerRequest], Effect[HttpServerResponse, Never, R | Provided]],
    *,
    uninterruptible: bool = False,
) -> Layer[Never, Never, HttpRouter | Requires[R]]: ...
@overload
def add[E, R](
    method: Method,
    path: str,
    handler: Effect[HttpServerResponse, E, R | Provided]
    | Callable[[ServerRequest], Effect[HttpServerResponse, E, R | Provided]],
    *,
    uninterruptible: bool = False,
) -> Layer[Never, Never, HttpRouter | Requires[R] | Raises[E]]: ...
def add(
    method: Method,
    path: str,
    # Spelled out (not ``Handler``): a function is a valid handler.
    handler: HttpServerResponse
    | Effect[HttpServerResponse, Any, Any]
    | Callable[[ServerRequest], Effect[HttpServerResponse, Any, Any]],
    *,
    uninterruptible: bool = False,
) -> Layer[Never, Never, Any]:
    """A layer adding one route."""
    route = Route(method, path, to_effect(handler), uninterruptible)
    return effect_discard(HttpRouter().flat_map(lambda router: router.add_all([route])))

add_all

add_all(routes: Sequence[Route[Never, Never]], *, prefix: str | None = None) -> Layer[Never, Never, HttpRouter]
add_all[E](routes: Sequence[Route[E, Never]], *, prefix: str | None = None) -> Layer[Never, Never, HttpRouter | Raises[E]]
add_all[R](routes: Sequence[Route[Never, R]], *, prefix: str | None = None) -> Layer[Never, Never, HttpRouter | Requires[R]]
add_all[E, R](routes: Sequence[Route[E, R]], *, prefix: str | None = None) -> Layer[Never, Never, HttpRouter | Requires[R] | Raises[E]]
add_all[E, R, EX, RX](routes: Effect[Sequence[Route[E, R]], EX, RX | Scope], *, prefix: str | None = None) -> Layer[Never, EX, HttpRouter | RX | Requires[R] | Raises[E]]

A layer adding routes (or the routes an effect makes), under prefix when given.

ParameterTypeDescription
routes
prefix= None
@overload
def add_all(
    routes: Sequence[Route[Never, Never]], *, prefix: str | None = None
) -> Layer[Never, Never, HttpRouter]: ...
@overload
def add_all[E](
    routes: Sequence[Route[E, Never]], *, prefix: str | None = None
) -> Layer[Never, Never, HttpRouter | Raises[E]]: ...
@overload
def add_all[R](
    routes: Sequence[Route[Never, R]], *, prefix: str | None = None
) -> Layer[Never, Never, HttpRouter | Requires[R]]: ...
@overload
def add_all[E, R](
    routes: Sequence[Route[E, R]], *, prefix: str | None = None
) -> Layer[Never, Never, HttpRouter | Requires[R] | Raises[E]]: ...
@overload
def add_all[E, R, EX, RX](
    routes: Effect[Sequence[Route[E, R]], EX, RX | Scope], *, prefix: str | None = None
) -> Layer[Never, EX, HttpRouter | RX | Requires[R] | Raises[E]]: ...
def add_all(
    routes: Sequence[Route[Any, Any]] | Effect[Sequence[Route[Any, Any]], Any, Any],
    *,
    prefix: str | None = None,
) -> Layer[Never, Any, Any]:
    """A layer adding routes (or the routes an effect makes), under
    ``prefix`` when given."""
    if not isinstance(routes, Sequence):
        require_effect(routes, "routes")
    made: Effect[Sequence[Route[Any, Any]], Any, Any] = (
        routes if isinstance(routes, Effect) else succeed(routes)
    )

    def add_to(router: HttpRouterService) -> Effect[None, Any, Any]:
        target = router.prefixed(prefix) if prefix else router
        return made.flat_map(target.add_all)

    return effect_discard(HttpRouter().flat_map(add_to))

schema_json

schema_json[T, RD](schema, *, reviver=None, **options) -> Effect[T, HttpServerError | SchemaError, RD | HttpServerRequest | ParsedSearchParams | RouteContext]

As schema_no_body, with the JSON body too (parsed with reviver): the struct's keys are body, method, url, headers, cookies, pathParams and searchParams.

ParameterTypeDescription
schemaCodec[T, Any, RD, Any]
reviverReviver | None = None
optionsUnpack[ParseOptions] = {}

Returns Effect[T, HttpServerError | SchemaError, RD | HttpServerRequest | ParsedSearchParams | RouteContext]

def schema_json[T, RD](
    schema: Codec[T, Any, RD, Any],
    *,
    reviver: Reviver | None = None,
    **options: Unpack[ParseOptions],
) -> Effect[
    T, HttpServerError | SchemaError, RD | HttpServerRequest | ParsedSearchParams | RouteContext
]:
    """As ``schema_no_body``, with the JSON ``body`` too (parsed with
    ``reviver``): the struct's keys are ``body``, ``method``, ``url``,
    ``headers``, ``cookies``, ``pathParams`` and ``searchParams``."""
    decode = decode_unknown_effect(schema, **options)

    def parsed(json: object) -> object:
        return json if reviver is None else revive(json, reviver)

    def body(fiber: Fiber[Any, Any]) -> Effect[T, HttpServerError | SchemaError, RD]:
        fields = _request_fields(fiber)
        request = fiber._context.get_unsafe(HttpServerRequest)
        return request.json.flat_map(lambda json: decode({**fields, "body": parsed(json)}))

    return _WithFiber(body)

schema_no_body

schema_no_body[T, RD](schema, **options) -> Effect[T, SchemaError, RD | HttpServerRequest | ParsedSearchParams | RouteContext]

The request decoded by schema, a struct of any of the keys method, url, headers, cookies, pathParams and searchParams (camelCase, as in Effect).

ParameterTypeDescription
schemaCodec[T, Any, RD, Any]
optionsUnpack[ParseOptions] = {}

Returns Effect[T, SchemaError, RD | HttpServerRequest | ParsedSearchParams | RouteContext]

def schema_no_body[T, RD](
    schema: Codec[T, Any, RD, Any], **options: Unpack[ParseOptions]
) -> Effect[T, SchemaError, RD | HttpServerRequest | ParsedSearchParams | RouteContext]:
    """The request decoded by ``schema``, a struct of any of the keys
    ``method``, ``url``, ``headers``, ``cookies``, ``pathParams`` and
    ``searchParams`` (camelCase, as in Effect)."""
    decode = decode_unknown_effect(schema, **options)
    return _WithFiber(lambda fiber: decode(_request_fields(fiber)))

schema_params

schema_params[T, RD](schema, **options) -> Effect[T, SchemaError, RD | RouteContext | ParsedSearchParams]

The query and path parameters (path ones win) decoded by schema.

ParameterTypeDescription
schemaCodec[T, Any, RD, Any]
optionsUnpack[ParseOptions] = {}

Returns Effect[T, SchemaError, RD | RouteContext | ParsedSearchParams]

def schema_params[T, RD](
    schema: Codec[T, Any, RD, Any], **options: Unpack[ParseOptions]
) -> Effect[T, SchemaError, RD | RouteContext | ParsedSearchParams]:
    """The query and path parameters (path ones win) decoded by
    ``schema``."""
    decode = decode_unknown_effect(schema, **options)
    return ParsedSearchParams().flat_map(
        lambda search: params.flat_map(lambda path: decode({**search, **path}))
    )

schema_path_params

schema_path_params[T, RD](schema, **options) -> Effect[T, SchemaError, RD | RouteContext]

The path parameters decoded by schema.

ParameterTypeDescription
schemaCodec[T, Any, RD, Any]
optionsUnpack[ParseOptions] = {}

Returns Effect[T, SchemaError, RD | RouteContext]

def schema_path_params[T, RD](
    schema: Codec[T, Any, RD, Any], **options: Unpack[ParseOptions]
) -> Effect[T, SchemaError, RD | RouteContext]:
    """The path parameters decoded by ``schema``."""
    decode = decode_unknown_effect(schema, **options)
    return params.flat_map(lambda values: decode(dict(values)))

serve

serve[A, LE, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | X], *, router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, disable_listen_log: bool = False) -> Layer[A, LE, HttpServer | X]
serve[A, LE, E = Never, R = Never, GE = Never, GR = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X], *, router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, disable_listen_log: bool = False) -> Layer[A, LE, HttpServer | R | GR | X]
serve[A, LE, HE, HR = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | X], *, middleware: Callable[[_Routed[Never, Never]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]], router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, disable_listen_log: bool = False) -> Layer[A, LE, HttpServer | HR | X]
serve[A, LE, HE, E = Never, R = Never, HR = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | X], *, middleware: Callable[[_Routed[E, R]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]], router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, disable_listen_log: bool = False) -> Layer[A, LE, HttpServer | HR | X]
serve[A, LE, HE, HR, E = Never, R = Never, GE = Never, GR = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X], *, middleware: Callable[[_Routed[E | GE, R | GR]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]], router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, disable_listen_log: bool = False) -> Layer[A, LE, HttpServer | HR | X]

Serve the routes app_layer adds on the HttpServer, logging each request (unless disable_logger) and the address (unless disable_listen_log). The layer's other services are the server layer's requirements (Effect's Exclude<R, HttpRouter>).

middleware wraps the whole request, sending included, so the response it returns is dropped (as in Effect): it is for middleware such as middleware.compression() that change the response through http_effect.append_pre_response_handler. Change every response with router.middleware(f, global_=True).

ParameterTypeDescription
app_layer
middleware= None
router_config= None
disable_logger= False
disable_listen_log= False
@overload
def serve[A, LE, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | X],
    *,
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    disable_listen_log: bool = False,
) -> Layer[A, LE, HttpServer | X]: ...
@overload
def serve[A, LE, E = Never, R = Never, GE = Never, GR = Never, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X
    ],
    *,
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    disable_listen_log: bool = False,
) -> Layer[A, LE, HttpServer | R | GR | X]: ...
@overload
def serve[A, LE, HE, HR = Never, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | X],
    *,
    middleware: Callable[
        [_Routed[Never, Never]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]
    ],
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    disable_listen_log: bool = False,
) -> Layer[A, LE, HttpServer | HR | X]: ...
@overload
def serve[A, LE, HE, E = Never, R = Never, HR = Never, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | X],
    *,
    middleware: Callable[
        [_Routed[E, R]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]
    ],
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    disable_listen_log: bool = False,
) -> Layer[A, LE, HttpServer | HR | X]: ...
@overload
def serve[
    A,
    LE,
    HE,
    HR,
    E = Never,
    R = Never,
    GE = Never,
    GR = Never,
    X: Tag[Any] | ServiceMarker = Never,
](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X
    ],
    *,
    middleware: Callable[
        [_Routed[E | GE, R | GR]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]
    ],
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    disable_listen_log: bool = False,
) -> Layer[A, LE, HttpServer | HR | X]: ...
def serve(
    app_layer: Layer[Any, Any, Any],
    *,
    middleware: Callable[[Any], Effect[HttpServerResponse, Any, Any]] | None = None,
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    disable_listen_log: bool = False,
) -> Layer[Any, Any, Any]:
    """Serve the routes ``app_layer`` adds on the ``HttpServer``, logging
    each request (unless ``disable_logger``) and the address (unless
    ``disable_listen_log``). The layer's other services are the server
    layer's requirements (Effect's ``Exclude<R, HttpRouter>``).

    ``middleware`` wraps the whole request, sending included, so the
    response it returns is dropped (as in Effect): it is for middleware such
    as ``middleware.compression()`` that change the response through
    ``http_effect.append_pre_response_handler``. Change every response with
    ``router.middleware(f, global_=True)``."""
    require_layer(app_layer, "app_layer")
    app_middleware = _app_middleware(middleware, disable_logger)
    with_router = _with_router(app_layer, router_config)

    def body(fiber: Fiber[Any, Any]) -> Effect[Layer[Any, Any, Any], Any, Any]:
        context = fiber._context
        built: Effect[Context[Any], Any, Any] = with_router.build_with_memo_map(
            fork_or_create(context), context.get_unsafe(Scope)
        )

        def serving(ctx: Context[Any]) -> Layer[Any, Any, Any]:
            app = ctx.get_unsafe(HttpRouter).as_http_effect()
            served: Layer[Any, Any, Any] = (
                server.serve(app) if app_middleware is None else server.serve(app, app_middleware)
            )
            return merge(served, succeed_context(ctx))

        return built.map(serving)

    served: Layer[Any, Any, Any] = unwrap(_WithFiber(body))
    return served if disable_listen_log else server.with_log_address(served)

to_asgi

to_asgi[A, LE, E = Never, GE = Never](app_layer, *, middleware=None, router_config=None, disable_logger=False, memo_map=None) -> AsgiApp

An ASGI 3 application for the routes app_layer adds (asgi.to_asgi_with): the layer is built at the server's lifespan startup and released at its shutdown. The routes' requests run with the layer's services, so whatever they need (Requires[...]) the layer must build: give it with provide_request or layer.provide_merge (layer.provide builds a service only for the layer it feeds).

ParameterTypeDescription
app_layerLayer[A, LE, HttpRouter | Requires[A] | Raises[E] | GlobalRequires[A] | GlobalRaises[GE]]
middlewareCallable[[_Routed[E | GE, A]], Effect[HttpServerResponse, Any, A | HttpServerRequest | Scope]] | None = None
router_configfind_my_way.RouterConfig | None = None
disable_loggerbool = False
memo_mapMemoMap | None = None

Returns AsgiApp

def to_asgi[A, LE, E = Never, GE = Never](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[A] | Raises[E] | GlobalRequires[A] | GlobalRaises[GE]
    ],
    *,
    middleware: Callable[
        [_Routed[E | GE, A]], Effect[HttpServerResponse, Any, A | HttpServerRequest | Scope]
    ]
    | None = None,
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    memo_map: MemoMap | None = None,
) -> AsgiApp:
    """An ASGI 3 application for the routes ``app_layer`` adds
    (``asgi.to_asgi_with``): the layer is built at the server's lifespan
    startup and released at its shutdown. The routes' requests run with the
    layer's services, so whatever they need (``Requires[...]``) the layer
    must build: give it with ``provide_request`` or ``layer.provide_merge``
    (``layer.provide`` builds a service only for the layer it feeds)."""
    require_layer(app_layer, "app_layer")
    return to_asgi_with(
        _with_router(app_layer, router_config),
        lambda ctx: ctx.get_unsafe(HttpRouter).as_http_effect(),
        middleware=_app_middleware(middleware, disable_logger),
        memo_map=memo_map,
    )

to_http_effect

to_http_effect[A, LE, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | X]) -> Effect[_Routed[Never, Never], LE, Scope | X]
to_http_effect[A, LE, E = Never, R = Never, GE = Never, GR = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X]) -> Effect[_Routed[E | GE, R | GR], LE, Scope | X]

Build app_layer with a router (into the current scope) and give the app serving its routes. The layer's other services are the outer effect's requirements (Effect's Exclude<R, HttpRouter>).

ParameterTypeDescription
app_layer
@overload
def to_http_effect[A, LE, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | X],
) -> Effect[_Routed[Never, Never], LE, Scope | X]: ...
@overload
def to_http_effect[
    A,
    LE,
    E = Never,
    R = Never,
    GE = Never,
    GR = Never,
    X: Tag[Any] | ServiceMarker = Never,
](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X
    ],
) -> Effect[_Routed[E | GE, R | GR], LE, Scope | X]: ...
def to_http_effect(app_layer: Layer[Any, Any, Any]) -> Effect[Any, Any, Any]:
    """Build ``app_layer`` with a router (into the current scope) and give
    the app serving its routes. The layer's other services are the outer
    effect's requirements (Effect's ``Exclude<R, HttpRouter>``)."""
    require_layer(app_layer, "app_layer")

    def body(fiber: Fiber[Any, Any]) -> Effect[Any, Any, Any]:
        context = fiber._context
        built: Effect[Context[Any], Any, Any] = _with_router(app_layer, None).build_with_memo_map(
            fork_or_create(context), context.get_unsafe(Scope)
        )
        return built.map(lambda ctx: ctx.get_unsafe(HttpRouter).as_http_effect())

    return _WithFiber(body)

to_web_handler

to_web_handler[A, LE](app_layer: Layer[A, LE, HttpRouter], *, router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, memo_map: MemoMap | None = None) -> WebHandlerLayer
to_web_handler[A, LE, E = Never, R = Never, GE = Never, GR = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE]], *, router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, memo_map: MemoMap | None = None) -> WebHandlerLayer
to_web_handler[A, LE, HE, HR = Never](app_layer: Layer[A, LE, HttpRouter], *, middleware: Callable[[_Routed[Never, Never]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]], router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, memo_map: MemoMap | None = None) -> WebHandlerLayer
to_web_handler[A, LE, HE, E = Never, R = Never, HR = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E]], *, middleware: Callable[[_Routed[E, R]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]], router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, memo_map: MemoMap | None = None) -> WebHandlerLayer
to_web_handler[A, LE, HE, HR, E = Never, R = Never, GE = Never, GR = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE]], *, middleware: Callable[[_Routed[E | GE, R | GR]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]], router_config: find_my_way.RouterConfig | None = None, disable_logger: bool = False, memo_map: MemoMap | None = None) -> WebHandlerLayer

An asyncio handler for the routes app_layer adds; the layer is built at once (sharing the layers of other handlers built with memo_map) and released by dispose. Request services the app still needs come from the handler's context argument.

ParameterTypeDescription
app_layer
middleware= None
router_config= None
disable_logger= False
memo_map= None
@overload
def to_web_handler[A, LE](
    app_layer: Layer[A, LE, HttpRouter],
    *,
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer: ...
@overload
def to_web_handler[A, LE, E = Never, R = Never, GE = Never, GR = Never](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE]
    ],
    *,
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer: ...
@overload
def to_web_handler[A, LE, HE, HR = Never](
    app_layer: Layer[A, LE, HttpRouter],
    *,
    middleware: Callable[
        [_Routed[Never, Never]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]
    ],
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer: ...
@overload
def to_web_handler[A, LE, HE, E = Never, R = Never, HR = Never](
    app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E]],
    *,
    middleware: Callable[
        [_Routed[E, R]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]
    ],
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer: ...
@overload
def to_web_handler[A, LE, HE, HR, E = Never, R = Never, GE = Never, GR = Never](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE]
    ],
    *,
    middleware: Callable[
        [_Routed[E | GE, R | GR]], Effect[HttpServerResponse, HE, HR | HttpServerRequest | Scope]
    ],
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer: ...
def to_web_handler(
    app_layer: Layer[Any, Any, Any],
    *,
    middleware: Callable[[Any], Effect[HttpServerResponse, Any, Any]] | None = None,
    router_config: find_my_way.RouterConfig | None = None,
    disable_logger: bool = False,
    memo_map: MemoMap | None = None,
) -> WebHandlerLayer:
    """An asyncio handler for the routes ``app_layer`` adds; the layer is
    built at once (sharing the layers of other handlers built with
    ``memo_map``) and released by ``dispose``. Request services the app
    still needs come from the handler's ``context`` argument."""
    require_layer(app_layer, "app_layer")
    return to_web_handler_layer_with(
        _with_router(app_layer, router_config),
        lambda ctx: succeed(ctx.get_unsafe(HttpRouter).as_http_effect()),
        _app_middleware(middleware, disable_logger),
        memo_map=memo_map,
    )

use

use[E](f: Callable[[HttpRouterService], Effect[object, E, Scope]]) -> Layer[Never, E, HttpRouter]
use[E, R](f: Callable[[HttpRouterService], Effect[object, E, R | Scope]]) -> Layer[Never, E, HttpRouter | R]

A layer doing f with the router while it builds.

ParameterTypeDescription
f
@overload
def use[E](
    f: Callable[[HttpRouterService], Effect[object, E, Scope]],
) -> Layer[Never, E, HttpRouter]: ...
@overload
def use[E, R](
    f: Callable[[HttpRouterService], Effect[object, E, R | Scope]],
) -> Layer[Never, E, HttpRouter | R]: ...
def use(f: Callable[[HttpRouterService], Effect[object, Any, Any]]) -> Layer[Never, Any, Any]:
    """A layer doing ``f`` with the router while it builds."""
    return effect_discard(HttpRouter().flat_map(f))

in_memory_client

in_memory_client[A, LE, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | X]) -> Effect[HttpClientService[HttpClientError], LE, Scope | X]
in_memory_client[A, LE, E = Never, GE = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Raises[E] | GlobalRaises[GE] | X]) -> Effect[HttpClientService[HttpClientError], LE, Scope | X]
in_memory_client[A, LE, E = Never, R = Never, GE = Never, GR = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X]) -> Effect[HttpClientService[HttpClientError, R | GR], LE, Scope | X]

A client whose requests the routes of app_layer answer in memory, built into the current Scope (the client of Effect's HttpApiTest, for any router). As there, every failure is a defect of the request (Effect.orDie), including those a server answers with a response: a route not found dies with its HttpServerError, an HttpApi payload failing its schema with its HttpApiSchemaError, and schema_path_params failing with its SchemaError. The services its routes need come from the request's context. A streamed body reaches the client chunk by chunk, as the handler writes it, so a test can read server-sent events while the handler runs; the handler's request scope closes when the body ends or its reader stops.

ParameterTypeDescription
app_layer
@overload
def in_memory_client[A, LE, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | X],
) -> Effect[HttpClientService[HttpClientError], LE, Scope | X]: ...
@overload
def in_memory_client[A, LE, E = Never, GE = Never, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | Raises[E] | GlobalRaises[GE] | X],
) -> Effect[HttpClientService[HttpClientError], LE, Scope | X]: ...
@overload
def in_memory_client[
    A,
    LE,
    E = Never,
    R = Never,
    GE = Never,
    GR = Never,
    X: Tag[Any] | ServiceMarker = Never,
](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X
    ],
) -> Effect[HttpClientService[HttpClientError, R | GR], LE, Scope | X]: ...
def in_memory_client(app_layer: Layer[Any, Any, Any]) -> Effect[Any, Any, Any]:
    """A client whose requests the routes of ``app_layer`` answer in
    memory, built into the current ``Scope`` (the client of Effect's
    ``HttpApiTest``, for any router). As there, every failure is a defect of
    the request (``Effect.orDie``), including those a server answers with a
    response: a route not found dies with its ``HttpServerError``, an
    ``HttpApi`` payload failing its schema with its ``HttpApiSchemaError``,
    and ``schema_path_params`` failing with its ``SchemaError``. The
    services its routes need come from the request's context. A streamed
    body reaches the client chunk by chunk, as the handler writes it, so a
    test can read server-sent events while the handler runs; the handler's
    request scope closes when the body ends or its reader stops."""
    require_layer(app_layer, "app_layer")

    @gen
    def run():
        app = yield from to_http_effect(app_layer)
        scope: CloseableScope = yield from Scope()
        return _in_memory.client(app, scope)

    return run

layer_in_memory_client

layer_in_memory_client[A, LE, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | X]) -> Layer[HttpClient, LE, X]
layer_in_memory_client[A, LE, E = Never, GE = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Raises[E] | GlobalRaises[GE] | X]) -> Layer[HttpClient, LE, X]
layer_in_memory_client[A, LE, E = Never, R = Never, GE = Never, GR = Never, X: Tag[Any] | ServiceMarker = Never](app_layer: Layer[A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X]) -> Layer[HttpClient, LE, R | GR | X]

in_memory_client as the HttpClient. The services the routes need are the layer's, as with serve; one the request provides itself comes first.

ParameterTypeDescription
app_layer
@overload
def layer_in_memory_client[A, LE, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | X],
) -> Layer[HttpClient, LE, X]: ...
@overload
def layer_in_memory_client[A, LE, E = Never, GE = Never, X: Tag[Any] | ServiceMarker = Never](
    app_layer: Layer[A, LE, HttpRouter | Raises[E] | GlobalRaises[GE] | X],
) -> Layer[HttpClient, LE, X]: ...
@overload
def layer_in_memory_client[
    A,
    LE,
    E = Never,
    R = Never,
    GE = Never,
    GR = Never,
    X: Tag[Any] | ServiceMarker = Never,
](
    app_layer: Layer[
        A, LE, HttpRouter | Requires[R] | Raises[E] | GlobalRequires[GR] | GlobalRaises[GE] | X
    ],
) -> Layer[HttpClient, LE, R | GR | X]: ...
def layer_in_memory_client(app_layer: Layer[Any, Any, Any]) -> Layer[Any, Any, Any]:
    """``in_memory_client`` as the ``HttpClient``. The services the routes
    need are the layer's, as with ``serve``; one the request provides itself
    comes first."""
    require_layer(app_layer, "app_layer")

    @gen
    def build():
        client: HttpClientService[HttpClientError, Any] = yield from in_memory_client(app_layer)
        services: Context[Any] = yield from context()

        def under_request(current: Context[Any]) -> Context[Any]:
            return services.merge(current)

        return client.transform(
            lambda sending, _request: sending.pipe(update_context(under_request))
        )

    return layer_effect(HttpClient, build)

cors

cors(**options) -> Layer[Never, Never, HttpRouter]

http.middleware.cors for every request, as global middleware.

ParameterTypeDescription
optionsUnpack[CorsOptions] = {}

Returns Layer[Never, Never, HttpRouter]

def cors(**options: Unpack[CorsOptions]) -> Layer[Never, Never, HttpRouter]:
    """``http.middleware.cors`` for every request, as global middleware."""
    return _global_layer(http_middleware.cors(**options))

middleware

middleware[E = Never](fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, Provided]], /, *, global_: Literal[False] = False) -> Middleware[E]
middleware[E = Never, R = Never](fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | Provided]], /, *, global_: Literal[False] = False) -> Middleware[E, R]
middleware[LE, LR, E = Never, R = Never](fn: Effect[Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | Provided]], LE, LR], /, *, global_: Literal[False] = False) -> Middleware[E, R, LE, LR]
middleware[E = Never](fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, GlobalProvided]], /, *, global_: Literal[True]) -> Layer[Never, Never, HttpRouter | GlobalRaises[E]]
middleware[E = Never, R = Never](fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | GlobalProvided]], /, *, global_: Literal[True]) -> Layer[Never, Never, HttpRouter | GlobalRequires[R] | GlobalRaises[E]]
middleware[LE, LR, E = Never, R = Never](fn: Effect[Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | GlobalProvided]], LE, LR], /, *, global_: Literal[True]) -> Layer[Never, LE, HttpRouter | LR | GlobalRequires[R] | GlobalRaises[E]]

Middleware from a function of the handler (or an effect making one). The handler's own errors arrive as Unhandled, which the result must keep.

global_=True gives a layer wrapping every request, matched or not, instead.

ParameterTypeDescription
fn
global_= False
@overload
def middleware[E = Never](
    fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, Provided]],
    /,
    *,
    global_: Literal[False] = False,
) -> Middleware[E]: ...
@overload
def middleware[E = Never, R = Never](
    fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | Provided]],
    /,
    *,
    global_: Literal[False] = False,
) -> Middleware[E, R]: ...
@overload
def middleware[LE, LR, E = Never, R = Never](
    fn: Effect[Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | Provided]], LE, LR],
    /,
    *,
    global_: Literal[False] = False,
) -> Middleware[E, R, LE, LR]: ...
@overload
def middleware[E = Never](
    fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, GlobalProvided]],
    /,
    *,
    global_: Literal[True],
) -> Layer[Never, Never, HttpRouter | GlobalRaises[E]]: ...
@overload
def middleware[E = Never, R = Never](
    fn: Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | GlobalProvided]],
    /,
    *,
    global_: Literal[True],
) -> Layer[Never, Never, HttpRouter | GlobalRequires[R] | GlobalRaises[E]]: ...
@overload
def middleware[LE, LR, E = Never, R = Never](
    fn: Effect[
        Callable[[_In], Effect[HttpServerResponse, E | Unhandled, R | GlobalProvided]], LE, LR
    ],
    /,
    *,
    global_: Literal[True],
) -> Layer[Never, LE, HttpRouter | LR | GlobalRequires[R] | GlobalRaises[E]]: ...
def middleware(fn: object, /, *, global_: bool = False) -> Any:
    """Middleware from a function of the handler (or an effect making
    one). The handler's own errors arrive as ``Unhandled``, which the
    result must keep.

    ``global_=True`` gives a layer wrapping every request, matched or not,
    instead."""
    return _global_layer(fn) if global_ else Middleware(_fn_layer(fn))

provide_request

provide_request[A2, E2 = Never, R2 = Never](services) -> _ProvideRequest[A2, E2, R2]

Build services once and provide them to every request of the route layers this wraps: a route's Requires[S] goes when services builds S, and services' own errors and requirements take its place. Use with .pipe.

ParameterTypeDescription
servicesLayer[A2, E2, R2]

Returns _ProvideRequest[A2, E2, R2]

def provide_request[A2, E2 = Never, R2 = Never](
    services: Layer[A2, E2, R2],
) -> _ProvideRequest[A2, E2, R2]:
    """Build ``services`` once and provide them to every request of the
    route layers this wraps: a route's ``Requires[S]`` goes when ``services``
    builds ``S``, and ``services``' own errors and requirements take its
    place. Use with ``.pipe``."""
    require_layer(services, "services")

    def fn(context: Context[Any]) -> Callable[[_In], Effect[HttpServerResponse, Unhandled]]:
        return lambda eff: eff.pipe(provide(context))

    made: Effect[Any, Any, Any] = services.build().map(fn)
    return _ProvideRequest(provide(Middleware(_fn_layer(made)).layer))

prefix_path

prefix_path(path, prefix) -> str

path under prefix: "*" becomes prefix + "/*" and "/" the prefix itself.

ParameterTypeDescription
pathstr
prefixstr

Returns str

def prefix_path(path: str, prefix: str) -> str:
    """``path`` under ``prefix``: ``"*"`` becomes ``prefix + "/*"`` and
    ``"/"`` the prefix itself."""
    prefix = remove_trailing_slash(prefix)
    if path == "*":
        return f"{prefix}/*"
    if path == "/":
        return prefix
    return prefix + path

prefix_route

prefix_route[E, R](prefix) -> Callable[[Route[E, R]], Route[E, R]]

Mount a route under prefix. Use with .pipe.

ParameterTypeDescription
prefixstr

Returns Callable[[Route[E, R]], Route[E, R]]

def prefix_route[E, R](prefix: str) -> Callable[[Route[E, R]], Route[E, R]]:
    """Mount a route under ``prefix``. Use with ``.pipe``."""

    def apply(self: Route[E, R]) -> Route[E, R]:
        return replace(
            self,
            path=prefix_path(self.path, prefix),
            prefix=remove_trailing_slash(prefix)
            if self.prefix is None
            else prefix_path(self.prefix, prefix),
        )

    return apply

route

route(method: Method, path: str, handler: HttpServerResponse, *, uninterruptible: bool = False) -> Route
route[E](method: Method, path: str, handler: Effect[HttpServerResponse, E, Provided] | Callable[[ServerRequest], Effect[HttpServerResponse, E, Provided]], *, uninterruptible: bool = False) -> Route[E]
route[E, R](method: Method, path: str, handler: Effect[HttpServerResponse, E, R | Provided] | Callable[[ServerRequest], Effect[HttpServerResponse, E, R | Provided]], *, uninterruptible: bool = False) -> Route[E, R]

A route for add_all. handler is a response, an effect, or a function of the request. Handlers run interruptibly unless uninterruptible.

ParameterTypeDescription
method
path
handler
uninterruptible= False
@overload
def route(
    method: Method, path: str, handler: HttpServerResponse, *, uninterruptible: bool = False
) -> Route: ...
@overload
def route[E](
    method: Method,
    path: str,
    handler: Effect[HttpServerResponse, E, Provided]
    | Callable[[ServerRequest], Effect[HttpServerResponse, E, Provided]],
    *,
    uninterruptible: bool = False,
) -> Route[E]: ...
@overload
def route[E, R](
    method: Method,
    path: str,
    handler: Effect[HttpServerResponse, E, R | Provided]
    | Callable[[ServerRequest], Effect[HttpServerResponse, E, R | Provided]],
    *,
    uninterruptible: bool = False,
) -> Route[E, R]: ...
def route(
    method: Method,
    path: str,
    # Spelled out (not ``Handler``): a function is a valid handler.
    handler: HttpServerResponse
    | Effect[HttpServerResponse, Any, Any]
    | Callable[[ServerRequest], Effect[HttpServerResponse, Any, Any]],
    *,
    uninterruptible: bool = False,
) -> Route[Any, Any]:
    """A route for ``add_all``. ``handler`` is a response, an effect, or a
    function of the request. Handlers run interruptibly unless
    ``uninterruptible``."""
    return Route(method, path, to_effect(handler), uninterruptible)