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#
| Attribute | Type | Description |
|---|---|---|
layer | Layer[HttpRouter] | The |
params | Effect[Mapping[str, str], Never, RouteContext] | The matched route's path parameters. |
disable_logger | Layer[Never, Never, Requires[Never] | Raises[Never]] | Route middleware turning off the request log for the routes it wraps. |
make | Effect[HttpRouterService] |
Types#
| Type | Definition | Description |
|---|---|---|
GlobalProvided | type GlobalProvided = HttpServerRequest | Scope | |
Provided | type Provided = HttpServerRequest | Scope | ParsedSearchParams | RouteContext | |
Handler | type Handler[E, R] = HttpServerResponse | Effect[HttpServerResponse, E, R] | Callable[[ServerRequest], Effect[HttpServerResponse, E, R]] | |
Method | type 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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[T, Any, RD, Any] | |
reviver | Reviver | None = None | |
options | Unpack[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).
| Parameter | Type | Description |
|---|---|---|
schema | Codec[T, Any, RD, Any] | |
options | Unpack[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.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[T, Any, RD, Any] | |
options | Unpack[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.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[T, Any, RD, Any] | |
options | Unpack[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).
| Parameter | Type | Description |
|---|---|---|
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) -> AsgiAppAn 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).
| Parameter | Type | Description |
|---|---|---|
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 |
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>).
| Parameter | Type | Description |
|---|---|---|
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) -> WebHandlerLayerAn 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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
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 runlayer_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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
options | Unpack[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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
services | Layer[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) -> strpath under prefix: "*" becomes prefix + "/*" and
"/" the prefix itself.
| Parameter | Type | Description |
|---|---|---|
path | str | |
prefix | str |
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 + pathprefix_route#
prefix_route[E, R](prefix) -> Callable[[Route[E, R]], Route[E, R]]Mount a route under prefix. Use with .pipe.
| Parameter | Type | Description |
|---|---|---|
prefix | str |
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 applyroute#
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.
| Parameter | Type | Description |
|---|---|---|
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)