diff --git a/README.md b/README.md index a510d5071..94aa72388 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ - [x] installation [@greyli](https://github.com/greyli) Grey Li - [ ] logging [@FesonX](https://github.com/FesonX) FesonX - [ ] quickstart (reserved) -- [ ] reqcontext [@rosekc](https://github.com/rosekc) rosekc +- [x] reqcontext [@rosekc](https://github.com/rosekc) rosekc - [ ] security [@kylinbin](https://github.com/kylinbin) kylin - [ ] server [@LeeRnnGii](https://github.com/LeeRnnGii) LeeRnnGii - [x] shell [@LTakamori](https://github.com/LTakamori) LTakamori diff --git a/docs/locales/zh_CN/LC_MESSAGES/reqcontext.po b/docs/locales/zh_CN/LC_MESSAGES/reqcontext.po index 49cfc1914..b6daabcce 100644 --- a/docs/locales/zh_CN/LC_MESSAGES/reqcontext.po +++ b/docs/locales/zh_CN/LC_MESSAGES/reqcontext.po @@ -10,7 +10,7 @@ msgstr "" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2021-05-25 19:31+0800\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" +"Last-Translator: rosekc \n" "Language-Team: zh_CN \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" @@ -19,7 +19,7 @@ msgstr "" #: ../../reqcontext.rst:4 msgid "The Request Context" -msgstr "" +msgstr "请求上下文" #: ../../reqcontext.rst:6 msgid "" @@ -28,6 +28,9 @@ msgid "" "runs during a request, the :data:`request` and :data:`session` proxies " "are accessed instead." msgstr "" +"在请求当中,请求上下文保持对请求层级的数据的追踪。相比在请求当中把请求对" +"象传递到每个函数当中,Flask 使用了 :data:`request` 与 :data:`session` 代理" +"对象来访问请求对象。" #: ../../reqcontext.rst:11 msgid "" @@ -35,10 +38,12 @@ msgid "" "application-level data independent of a request. A corresponding " "application context is pushed when a request context is pushed." msgstr "" +"这与 :doc:`/appcontext` 类似,只不过应用上下文跟踪独立于请求的应用层级数据。" +"在请求上下文被推入线程局部栈时,对应的应用上下文也被推入。" #: ../../reqcontext.rst:17 msgid "Purpose of the Context" -msgstr "" +msgstr "上下文的目的" #: ../../reqcontext.rst:19 msgid "" @@ -49,6 +54,11 @@ msgid "" "be considered global to that worker during that request. Flask uses the " "term *context local* for this." msgstr "" +"当 :class:`Flask` 应用处理请求,根据从 WSGI 服务器获取到的环境,创建出相应的 :" +"class:`Request` 对象。因为 *工作者* (根据不同的服务器可能为线" +"程,进程或协程)一次只能处理一个请求,在请求当中,请求数据可以认为" +"对工作者全局可见、Flask 用术语 *上下文局部变量(context local)* 来表示" +"这种设计。" #: ../../reqcontext.rst:26 msgid "" @@ -57,10 +67,13 @@ msgid "" "request will have access to the :data:`request` proxy, which points to " "the request object for the current request." msgstr "" +"Flask 在处理请求时,会自动 *推入* 请求上下文。视图函数,错误处理钩" +"子函数与其他在请求当中运行的函数可以访问指向当前请求的请求对象代理对象 :" +"data:`request`。" #: ../../reqcontext.rst:33 msgid "Lifetime of the Context" -msgstr "" +msgstr "上下文的生命周期" #: ../../reqcontext.rst:35 msgid "" @@ -68,6 +81,8 @@ msgid "" "context, which also pushes an :doc:`/appcontext`. When the request ends " "it pops the request context then the application context." msgstr "" +"当 Flask 应用开始处理请求时,推入请求上下文的同时也推入了 :doc:`/" +"appcontext`。当请求结束,会先弹出请求上下文,然后再弹出应用上下文。" #: ../../reqcontext.rst:39 msgid "" @@ -76,22 +91,28 @@ msgid "" " have a different context stack and will not know about the request the " "parent thread was pointing to." msgstr "" +"每个线程(或者其他工作者类型)的上下文是独立的。:data:`request` 不能传入其" +"他线程,其他线程有不同的上下文栈,因此不会知道父线程会指向哪个请求。" #: ../../reqcontext.rst:44 msgid "" "Context locals are implemented in Werkzeug. See :doc:`werkzeug:local` for" " more information on how this works internally." msgstr "" +"上下文局部变量的实现在 Werkzeug 中。若要了解更多内部工作细节,参见 :doc:" +"`werkzeug:local`。" #: ../../reqcontext.rst:49 msgid "Manually Push a Context" -msgstr "" +msgstr "手动推入上下文" #: ../../reqcontext.rst:51 msgid "" "If you try to access :data:`request`, or anything that uses it, outside a" " request context, you'll get this error message:" msgstr "" +"如果要在应用上下文之外的地方试图去获取或者使用依赖 :data:`request` 的任何东西," +"有可能会收到这样的错误信息:" #: ../../reqcontext.rst:62 msgid "" @@ -102,6 +123,10 @@ msgid "" "that runs in the block will have access to :data:`request`, populated " "with your test data. ::" msgstr "" +"这通常只会在测试需要活动请求的代码时候发生。其中一个方法是使用 :meth:" +"`test client ` 来模拟一个完整请求。或者可以在 ``with`` " +"块使用 :meth:`~Flask.test_request_context`,所有在块中运行的代码将会可以访" +"问由测试数据生成的 :data:`request`。 ::" #: ../../reqcontext.rst:77 msgid "" @@ -109,16 +134,20 @@ msgid "" " it most likely indicates that you should move that code into a view " "function." msgstr "" +"如果你在测试应用以外场景遇到这个错误,绝大多数情况下意味着这些代码应该转移" +"到视图函数下。" #: ../../reqcontext.rst:81 msgid "" "For information on how to use the request context from the interactive " "Python shell, see :doc:`/shell`." msgstr "" +"了解更多如何在 Python 交互式命令行中使用请求上下文的信息,参见 :doc:`/" +"shell`。" #: ../../reqcontext.rst:86 msgid "How the Context Works" -msgstr "" +msgstr "上下文的运作原理" #: ../../reqcontext.rst:88 msgid "" @@ -129,6 +158,10 @@ msgid "" "proxies that depend on them are available and point at information from " "the top context on the stack." msgstr "" +"在处理每个请求时,都会调用 :meth:`Flask.wsgi_app` 方法。它在请求中控制上下" +"文。具体来说,存储请求上下文和应用上下文的数据结构为栈,分别为 :data:" +"`_request_ctx_stack` 以及 :data:`_app_ctx_stack`。当上下文被推入栈,依赖栈" +"的代理对象变得可用,指向在栈顶的上下文。" #: ../../reqcontext.rst:95 msgid "" @@ -139,6 +172,10 @@ msgid "" " and :data:`session` proxies are available to the original thread " "handling the request." msgstr "" +"当请求开始,将创建并推入 :class:`~ctx.RequestContext` 对象。如果此时应" +"用上下文不在上下文栈的顶部,将先创建 :class:`~ctx.AppContext`。当这些" +"上下文被推入,代理对象 :data:`current_app`、:data:`g`、:data:`request` 以" +"及 :data:`session` 在处理请求的线程变得可用。" #: ../../reqcontext.rst:102 msgid "" @@ -147,6 +184,9 @@ msgid "" "be used in advanced applications to, for example, do internal redirects " "or chain different applications together." msgstr "" +"因为上下文对象存放在栈中,在请求中,其他上下文对象推入时可能会改变代理" +"对象的指向。尽管这不是常见的设计模式,但它可以让应用能够内部重定向或者" +"将不同应用串联在一起。" #: ../../reqcontext.rst:107 msgid "" @@ -156,10 +196,14 @@ msgid "" "and :meth:`~Flask.teardown_appcontext` functions are executed. These " "execute even if an unhandled exception occurred during dispatch." msgstr "" +"当请求被分配到视图函数,生成并发送响应,请求上下文先被弹出,然后应用上下文" +"也被弹出。在上下文被弹出前,函数 :meth:`~Flask.teardown_request` 以及 :" +"meth:`~Flask.teardown_appcontext` 会被执行。即使在请求被分配过程中有未处理" +"的请求抛出,这些函数也会被执行。" #: ../../reqcontext.rst:117 msgid "Callbacks and Errors" -msgstr "" +msgstr "回调与错误" #: ../../reqcontext.rst:119 msgid "" @@ -167,6 +211,8 @@ msgid "" "request, response, and how errors are handled. The contexts are active " "during all of these stages." msgstr "" +"Flask 在不同阶段中会分配请求,这会影响请求、响应以及错误处理。在这些阶段" +"中,上下文处于可用状态。" #: ../../reqcontext.rst:123 msgid "" @@ -174,6 +220,8 @@ msgid "" "to the blueprint. The handlers for a blueprint will run if the blueprint " "owns the route that matches the request." msgstr "" +":class:`Blueprint` 可以为这些事件添加蓝图专属的钩子函数。当蓝图所属的路由" +"匹配上请求,那么蓝图内的钩子函数将被执行。" #: ../../reqcontext.rst:127 msgid "" @@ -182,6 +230,9 @@ msgid "" "skipped. The return value is treated as the response and the view " "function is not called." msgstr "" +"在每个请求前,会调用 :meth:`~Flask.before_request` 函数。如果其中的一个函" +"数返回了值,那么其他函数会被跳过执行。返回值会当作响应,视图函数不会被调" +"用。" #: ../../reqcontext.rst:132 msgid "" @@ -189,6 +240,8 @@ msgid "" " the view function for the matched route is called and returns a " "response." msgstr "" +"如果 :meth:`~Flask.before_request` 函数不返回响应,被路由匹配的视图函" +"数将被调用,返回请求。" #: ../../reqcontext.rst:136 msgid "" @@ -196,6 +249,8 @@ msgid "" "and passed to the :meth:`~Flask.after_request` functions. Each function " "returns a modified or new response object." msgstr "" +"视图函数返回的值会被转换成实际的响应对象,然后传递到 :meth:`~Flask." +"after_request` 函数。每个函数返回一个被修改的或者是新的响应对象。" #: ../../reqcontext.rst:140 msgid "" @@ -204,6 +259,9 @@ msgid "" "functions. These functions are called even if an unhandled exception was " "raised at any point above." msgstr "" +"当响应被返回,在弹出上下文的过程中,会调用 :meth:`~Flask." +"teardown_request` 和 :meth:`~Flask.teardown_appcontext` 函数。即使内部有一" +"个未处理的异常抛出,这些函数也会被执行。" #: ../../reqcontext.rst:145 msgid "" @@ -214,6 +272,10 @@ msgid "" "Internal Server Error`` response. The teardown functions are still " "called, and are passed the exception object." msgstr "" +"如果异常在清理(teardown)函数中抛出,Flask 会尝试使用 :meth:`~Flask." +"errorhandler` 函数去处理异常,返回响应。如果没有错误钩子函数,或者钩子函数" +"本身抛出了异常,Flask 返回了通用的 ``500 Internal Server Error`` 响" +"应。清理函数一样会调用,而且会传入异常对象。" #: ../../reqcontext.rst:152 msgid "" @@ -222,10 +284,13 @@ msgid "" "allows the development server to present the interactive debugger with " "the traceback." msgstr "" +"在 debug 模式开启的时候,未处理的异常不会被转换为 ``500`` 响应,而是传递" +"给 WSGI 服务器。这让开发服务器可以展示带有异常跟踪(trackback)的交互式" +"调试器。" #: ../../reqcontext.rst:159 msgid "Teardown Callbacks" -msgstr "" +msgstr "清理钩子函数" #: ../../reqcontext.rst:161 msgid "" @@ -237,6 +302,10 @@ msgid "" "functions in a way that does not depend on other callbacks and will not " "fail." msgstr "" +"清理钩子函数独立于请求分配,而是在上下文被弹出的时候才调用。当在请求分配的" +"过程中,或者在手动推入的的上下文中有未捕抓的异常,这些函数依然会被调用。这" +"意味着不会保证在请求分配的每一部分都会首先执行。确保在编写这些函数的时候不" +"要依赖其他钩子函数,不要假设函数不会失败。" #: ../../reqcontext.rst:169 msgid "" @@ -245,28 +314,35 @@ msgid "" "Use the :meth:`~Flask.test_client` as a ``with`` block to preserve the " "contexts until the ``with`` block exits." msgstr "" +"在测试的过程中,在请求结束的时候推迟弹出上下文是一种很有用的手段,它可以让" +"测试函数访问上下文中的数据。在 ``with`` 块中使用 :meth:`~Flask." +"test_client` 来让上下文在离开 ``with`` 块前保留。" #: ../../reqcontext.rst:203 msgid "Signals" -msgstr "" +msgstr "信号" #: ../../reqcontext.rst:205 msgid "" "If :data:`~signals.signals_available` is true, the following signals are " "sent:" -msgstr "" +msgstr "如果 :data:`~signals.signals_available` 为真,下列信号将被发送:" #: ../../reqcontext.rst:208 msgid "" ":data:`request_started` is sent before the :meth:`~Flask.before_request` " "functions are called." msgstr "" +"在 :meth:`~Flask.before_request` 被调用前,:data:`request_started` 信号会" +"被发送。" #: ../../reqcontext.rst:211 msgid "" ":data:`request_finished` is sent after the :meth:`~Flask.after_request` " "functions are called." msgstr "" +"在 :meth:`~Flask.after_request` 被调用前,:data:`request_finished` 信号会" +"被发送。" #: ../../reqcontext.rst:214 msgid "" @@ -274,16 +350,20 @@ msgid "" "handled, but before an :meth:`~Flask.errorhandler` is looked up or " "called." msgstr "" +"当异常开始处理时,:data:`got_request_exception` 信号会在 :meth:`~Flask." +"errorhandler` 被查看或调用前被发送。" #: ../../reqcontext.rst:218 msgid "" ":data:`request_tearing_down` is sent after the " ":meth:`~Flask.teardown_request` functions are called." msgstr "" +"在 :meth:`~Flask.teardown_request` 被调用后,:data:`request_tearing_down` " +"信号会被发送。" #: ../../reqcontext.rst:223 msgid "Context Preservation on Error" -msgstr "" +msgstr "在错误时保留上下文" #: ../../reqcontext.rst:225 msgid "" @@ -291,6 +371,8 @@ msgid "" "associated with it is destroyed. If an error occurs during development, " "it is useful to delay destroying the data for debugging purposes." msgstr "" +"在请求结束时,上下文会被弹出,所有与上下文相关的数据会被销毁。如果在开发环" +"境中有错误发生,推迟销毁上下文数据对调试来说非常有用。" #: ../../reqcontext.rst:229 msgid "" @@ -298,6 +380,8 @@ msgid "" "``FLASK_ENV`` environment variable is set to ``'development'``), the " "error and data will be preserved and shown in the interactive debugger." msgstr "" +"当开发服务器在开发模式运行(``FLASK_ENV`` 环境变量被设置为 " +"``'development'``),错误与数据会被保留,在交互式调试器中展示。" #: ../../reqcontext.rst:233 msgid "" @@ -305,16 +389,20 @@ msgid "" ":data:`PRESERVE_CONTEXT_ON_EXCEPTION` config. As described above, it " "defaults to ``True`` in the development environment." msgstr "" +"这一行为能被 :data:`PRESERVE_CONTEXT_ON_EXCEPTION` 设置项所控制。如上文所" +"述。在开发环境中默认设置为 ``True``。" #: ../../reqcontext.rst:237 msgid "" "Do not enable :data:`PRESERVE_CONTEXT_ON_EXCEPTION` in production, as it " "will cause your application to leak memory on exceptions." msgstr "" +"不要在生产环境中开启 :data:`PRESERVE_CONTEXT_ON_EXCEPTION`,因为这会让应用" +"在出现异常时内存泄露。" #: ../../reqcontext.rst:244 msgid "Notes On Proxies" -msgstr "" +msgstr "代理对象的注意事项" #: ../../reqcontext.rst:246 msgid "" @@ -323,12 +411,17 @@ msgid "" " the unique object bound to each worker behind the scenes as described on" " this page." msgstr "" +"一些 Flask 提供的对象,是其他对象的代理。在每个工作线程中,代理对象会以" +"相同的方式被访问。在内部实现中,代理对象指向绑定到工作者的唯一的对象。细" +"节如本页所述。" #: ../../reqcontext.rst:251 msgid "" "Most of the time you don't have to care about that, but there are some " "exceptions where it is good to know that this object is actually a proxy:" msgstr "" +"大多数时候,这些细节无需担心。但有些时候最好还是知道这个对象实际上是一个代" +"理:" #: ../../reqcontext.rst:254 msgid "" @@ -336,15 +429,21 @@ msgid "" "you want to perform instance checks, you have to do that on the object " "being proxied." msgstr "" +"代理对象不能冒充实际指向的对象类型。如果要进行实例检查,应当要在被代理的对" +"象本身进行检查。" #: ../../reqcontext.rst:257 msgid "" "The reference to the proxied object is needed in some situations, such as" " sending :doc:`signals` or passing data to a background thread." msgstr "" +"在某些要使用被代理对象的引用的时候,如发送 :doc:`signals` 或者向后台线程传" +"递数据。" #: ../../reqcontext.rst:261 msgid "" "If you need to access the underlying object that is proxied, use the " ":meth:`~werkzeug.local.LocalProxy._get_current_object` method::" msgstr "" +"如果需要访问在底层被代理的对象,使用 :meth:`~werkzeug.local.LocalProxy." +"_get_current_object` 这个方法: ::"