class falcon.API(*args, **kwargs)[源代码]

此类是的兼容性别名 falcon.App 。

API 已重命名为 App 在Falcon3.0中，为了反映应用程序的广度， App ，特别是其对应的ASGI，现在可以用于。

此兼容性别名应视为已弃用；它将在将来的版本中删除。

add_error_handler(exception: Union[Type[BaseException], Iterable[Type[BaseException]]], handler: Optional[Callable[[Request, Response, BaseException, dict], Any]] = None)

为一个或多个异常类型注册处理程序。

可以为任何异常类型注册错误处理程序，包括 HTTPError 或 HTTPStatus .这个特性为日志记录和处理由响应程序、钩子和中间件组件引发的异常提供了一个中心位置。

处理程序可以引发的实例 HTTPError 或 HTTPStatus 向客户传达有关问题的信息。或者，处理程序可以修改 resp 直接。

如果引发的异常是相应异常类型的实例，则错误处理程序与该异常“匹配”。如果多个错误处理程序与引发的异常匹配，框架将选择最具体的一个，这由引发的异常类型的方法解析顺序确定。如果注册了多个错误处理程序，则 same 异常类，则使用最近注册的处理程序。

例如，假设我们按如下方式注册错误处理程序：

app = App()
app.add_error_handler(falcon.HTTPNotFound, custom_handle_not_found)
app.add_error_handler(falcon.HTTPError, custom_handle_http_error)
app.add_error_handler(Exception, custom_handle_uncaught_exception)
app.add_error_handler(falcon.HTTPNotFound, custom_handle_404)

如果有一个实例 falcon.HTTPForbidden 被引发，它将由 custom_handle_http_error() 。 falcon.HTTPError 是的超类 falcon.HTTPForbidden 和一个子类 Exception ，因此它是具有注册处理程序的最具体的异常类型。

如果有一个实例 falcon.HTTPNotFound 被引发，它将由 custom_handle_404() ，而不是由 custom_handle_not_found() ，因为 custom_handle_404() 是最近注册的。

备注

缺省情况下，框架安装三个处理程序，一个用于 HTTPError ，一个用于 HTTPStatus ，一个用于标准 Exception 类型，这样可以防止将未捕获的异常传递给WSGI服务器。可以通过为所讨论的异常类型添加自定义错误处理程序方法来覆盖这些方法。

参数:

  • exception (type or iterable of types) -- 在处理请求时，每当发生属于指定类型的实例的错误时，将调用关联的处理程序。可以指定单个类型或类型的ITerable。

  • handler (callable) -- 采用以下形式的函数或可调用对象 func(req, resp, ex, params) 。如果未显式指定，则处理程序将缺省为 exception.handle ，在哪里 exception 是上面指定的错误类型，并且 handle 是静电方法(即，用 @staticmethod )，它接受与刚才描述的参数相同的参数。例如：：CLASS CustomException(CustomBaseException)：@staticmethod def Handle(req，resp，ex，params)：#TODO：记录错误#CONVERT TO TERVER TO FORK FORCON。HTTPError RAISE FORCON.HTTPError(FLACON.HTTP_792)如果指定的是异常类型的可迭代类型，而不是单个类型，则必须显式指定处理程序。

在 3.0 版本发生变更: 错误处理程序现在由最具体的匹配错误类选择，而不是由最近注册的匹配错误类选择。

add_middleware(middleware: object) → None

添加一个或多个附加中间件组件。

参数:

middleware -- 要添加的单个中间件组件或组件的可迭代。组件将被按顺序调用，就好像它们已被附加到传递给类初始化器的原始中间件列表中一样。

add_route(uri_template: str, resource: object, **kwargs)

将模板化的URI路径与资源关联。

Falcon根据一组URI模板将传入请求路由到资源。如果客户机请求的路径与给定路由的模板匹配，则请求将被传递到关联的资源进行处理。

备注

如果没有与请求匹配的路由，则控件将传递给只引发 HTTPRouteNotFound . 默认情况下，此错误将呈现为404响应，但可以通过添加自定义错误处理程序来修改此行为（另请参见 this FAQ topic ）

另一方面，如果路由匹配，但资源没有为请求的HTTP方法实现响应程序，则框架将调用一个默认响应程序，该响应程序将引发 HTTPMethodNotAllowed .

此方法委托给已配置的路由器的 add_route() 方法。若要重写默认行为，请将自定义路由器对象传递给 App 初始化器。

（另见： Routing ）

参数:

  • uri_template (str) -- 模板化的URI。必须注意确保模板不会掩蔽任何水槽图案(如果注册了任何水槽图案)。(另请参阅： add_sink() )..警告：：如果 strip_url_path_trailing_slash 已启用， uri_template 应该在没有尾随劈开的情况下提供。(另请参阅： Falcon如何处理请求路径中的尾随斜杠？ )

  • resource (instance) -- 对象，该对象表示睡觉资源。Falcon将GET请求传递给 on_get() ，将请求提交给 on_put() 如果您的资源不支持任何HTTP方法，只要不定义相应的请求处理程序，Falcon就会做正确的事情。。。注意：使用异步版本的 App ，所有请求处理程序都必须是可等待的协程函数。

关键字参数:

  • suffix (str) -- 此路由的可选响应方名称后缀。如果提供后缀，Falcon会将GET请求映射到 on_get_{{suffix}}() ，将请求发布到 on_post_{{suffix}}() 这样，可以将多个紧密相关的路由映射到同一资源。例如，单个资源类可以使用带后缀的响应器来区分对单个项目的请求与对这些相同项目的集合的请求。除了资源的常规路由之外，另一个类可能使用带后缀的响应器来处理快捷链接路由。例如：：class baz(Object)：def on_get_foo(self，req，resp)：pass def on_get_bar(self，req，resp)：pass baz=baz()app=Falcon.App()app.add_route(‘/foo’，baz，suffix=‘foo’)app.add_route(‘/bar’，baz，suffix=‘bar’)

  • compile (bool) -- 使用默认值时可以提供的可选标志 CompiledRouter 编译此调用的路由逻辑，因为否则它将延迟编译，直到路由第一个请求。看见 CompiledRouter.add_route() 了解更多详细信息。

备注

上面未定义的任何其他关键字参数都将传递给基础路由器 add_route() 方法。默认路由器忽略任何其他关键字参数，但自定义路由器可能利用此功能在设置路由时接收其他选项。自定义路由器必须使用可变模式接受此类参数 (**kwargs ）并忽略它们不支持的任何关键字参数。

add_sink(sink: Callable, prefix: Union[str, Pattern] = '/')

为App注册接收器方法。

如果没有与请求匹配的路由，但请求的URI中的路径与接收器前缀匹配，则falcon将把控制权传递给关联的接收器，而不考虑请求的HTTP方法。

当创建静态资源和响应程序时，使用接收器可以排出并动态处理大量路由，这是不切实际的。例如，您可以使用接收器创建智能代理，将请求转发到一个或多个后端服务。

参数:

  • sink (callable) -- 采用以下形式的可调用对象 func(req, resp, **kwargs) 。。。注意：使用异步版本的 App ，这一定是一个协和程序。

  • prefix (str) -- 一个正则表达式字符串，通常以“/”开头，如果它与请求的URI的路径部分匹配，它将触发接收器。可以同时指定字符串和预编译的regex对象。字符从URI路径的开头开始匹配。。注意：命名的组被转换成kwargs，并以此方式传递到接收器。。警告：如果前缀与已注册的路由模板重叠，则路由将优先，并屏蔽接收器。（另见： add_route() ）

add_static_route(prefix: str, directory: Union[str, Path], downloadable: bool = False, fallback_filename: Optional[str] = None)

将路由添加到静态文件目录。

静态路由提供了一种直接服务文件的方法。当您没有该选项、需要授权或出于测试目的时，此功能提供了在Web服务器级别提供文件的替代方法。

警告

直接从Web服务器（而不是通过python应用程序）提供文件服务的效率总是更高的，因此在生产部署中应该首选。出于安全原因，对于运行应用程序的帐户，目录和回退文件名（如果提供）应为只读。

警告

如果您需要通过Falcon应用程序提供大文件和/或渐进式下载(例如视频流)，请检查您的应用程序服务器的超时设置是否可以满足预期的请求持续时间(例如，流行的Gunicorn Kill sync 30秒后工作)，除非另有配置)。

备注

对于ASGI应用程序，通过在默认执行器上调度文件读取，使文件读取成为非阻塞的。

静态路由按后进先出顺序匹配。因此，如果两个路由使用相同的前缀，则第二个路由将覆盖第一个路由。这也意味着应该增加更具体的路线 之后 不太具体的。例如，以下序列将导致 '/foo/bar/thing.js' 被映射到 '/foo/bar' 路线，以及 '/foo/xyz/thing.js' 被映射到 '/foo' 路线：

app.add_static_route('/foo', foo_path)
app.add_static_route('/foo/bar', foobar_path)
参数:

  • prefix (str) -- 与此路由匹配的路径前缀。如果请求的URI中的路径以该字符串开头，则路径的其余部分将附加到源目录以确定要提供的文件。这样做是安全的，以防止攻击者在指定目录之外请求文件。请注意，静态路由按后进先出的顺序匹配，并且仅在检查动态路由和接收器之后尝试。

  • directory (Union[str, pathlib.Path]) -- 提供文件的源目录。

  • downloadable (bool) -- 设置为 True 在响应中包含内容处置头。“file name”指令只是设置为请求文件的名称。

  • fallback_filename (str) -- 找不到请求的文件时使用的回退文件名。可以是前缀文件夹内的相对路径，也可以是任何有效的绝对路径。

set_error_serializer(serializer: Callable[[Request, Response, BaseException], Any])

重写的实例的默认序列化程序 HTTPError .

当响应程序引发的实例 HTTPError ，falcon自动将其转换为HTTP响应。默认序列化程序支持JSON和XML，但可以被此方法重写以使用自定义序列化程序以支持其他媒体类型。

备注

如果使用自定义媒体类型，并且该类型包含“+json”或“+xml”后缀，则默认序列化程序将分别将错误转换为json或xml。

备注

的默认错误处理程序，则可能无法调用使用此方法设置的自定义序列化程序 HTTPError 已被覆盖。看见 add_error_handler() 了解更多详细信息。

这个 HTTPError 类包含助手方法，例如 to_json() 和 to_dict() ，可以在自定义序列化程序中使用。例如：：

def my_serializer(req, resp, exception):
    representation = None

    preferred = req.client_prefers((falcon.MEDIA_YAML, falcon.MEDIA_JSON))

    if preferred is not None:
        if preferred == falcon.MEDIA_JSON:
            resp.data = exception.to_json()
        else:
            resp.text = yaml.dump(exception.to_dict(), encoding=None)
        resp.content_type = preferred

    resp.append_header('Vary', 'Accept')
参数:

serializer (callable) -- 形式上的函数 func(req, resp, exception) 在哪里 req 是传递给响应程序方法的请求对象， resp 是响应对象，并且 exception 是的实例 falcon.HTTPError .