# SOME DESCRIPTIVE TITLE.

# Copyright (C) 2001-2025, Python Software Foundation

# This file is distributed under the same license as the Python package.

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

#

# Translators:

# Rafael Fontenelle <[email protected]>, 2025

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.12\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2025-07-25 16:03+0000\n"

"PO-Revision-Date: 2025-07-18 19:57+0000\n"

"Last-Translator: Rafael Fontenelle <[email protected]>, 2025\n"

"Language-Team: Chinese (China) (https://app.transifex.com/python-doc/teams/5390/zh_CN/)\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Language: zh_CN\n"

"Plural-Forms: nplurals=1; plural=0;\n"

#: ../../library/contextvars.rst:2

msgid ":mod:`!contextvars` --- Context Variables"

msgstr ":mod:`!contextvars` --- 上下文变量"

#: ../../library/contextvars.rst:11

msgid ""

"This module provides APIs to manage, store, and access context-local state."

" The :class:`~contextvars.ContextVar` class is used to declare and work "

"with *Context Variables*. The :func:`~contextvars.copy_context` function "

"and the :class:`~contextvars.Context` class should be used to manage the "

"current context in asynchronous frameworks."

msgstr ""

"本模块提供了相关API用于管理、存储和访问上下文相关的状态。 :class:`~contextvars.ContextVar` 类用于声明 "

"*上下文变量* 并与其一起使用。函数 :func:`~contextvars.copy_context`  和类 "

":class:`~contextvars.Context` 用于管理当前上下文和异步框架中。"

#: ../../library/contextvars.rst:17

msgid ""

"Context managers that have state should use Context Variables instead of "

":func:`threading.local` to prevent their state from bleeding to other code "

"unexpectedly, when used in concurrent code."

msgstr ""

"当在并发代码中使用时，有状态的上下文管理器应当使用上下文变量而不是 :func:`threading.local` "

"以防止它们的状态意外地泄露到其他代码中。"

#: ../../library/contextvars.rst:21

msgid "See also :pep:`567` for additional details."

msgstr "更多信息参见 :pep:`567` 。"

#: ../../library/contextvars.rst:27

msgid "Context Variables"

msgstr "上下文变量"

#: ../../library/contextvars.rst:31

msgid "This class is used to declare a new Context Variable, e.g.::"

msgstr "此类用于声明一个新的上下文变量，如::"

#: ../../library/contextvars.rst:33

msgid "var: ContextVar[int] = ContextVar('var', default=42)"

msgstr "var: ContextVar[int] = ContextVar('var', default=42)"

#: ../../library/contextvars.rst:35

msgid ""

"The required *name* parameter is used for introspection and debug purposes."

msgstr "*name* 参数用于内省和调试，必需。"

#: ../../library/contextvars.rst:38

msgid ""

"The optional keyword-only *default* parameter is returned by "

":meth:`ContextVar.get` when no value for the variable is found in the "

"current context."

msgstr "调用 :meth:`ContextVar.get` 时，如果上下文中没有找到此变量的值，则返回可选的仅命名参数 *default* 。"

#: ../../library/contextvars.rst:42

msgid ""

"**Important:** Context Variables should be created at the top module level "

"and never in closures. :class:`Context` objects hold strong references to "

"context variables which prevents context variables from being properly "

"garbage collected."

msgstr ""

"**重要：** 上下文变量应该在顶级模块中创建，且永远不要在闭包中创建。 :class:`Context` "

"对象拥有对上下文变量的强引用，这可以让上下文变量被垃圾收集器正确回收。"

#: ../../library/contextvars.rst:49

msgid "The name of the variable. This is a read-only property."

msgstr "上下文变量的名称，只读属性。"

#: ../../library/contextvars.rst:55

msgid "Return a value for the context variable for the current context."

msgstr "返回当前上下文中此上下文变量的值。"

#: ../../library/contextvars.rst:57

msgid ""

"If there is no value for the variable in the current context, the method "

"will:"

msgstr "如果当前上下文中此变量没有值，则此方法会:"

#: ../../library/contextvars.rst:60

msgid ""

"return the value of the *default* argument of the method, if provided; or"

msgstr "如果提供了 *default*，返回其值；或者"

#: ../../library/contextvars.rst:63

msgid ""

"return the default value for the context variable, if it was created with "

"one; or"

msgstr "返回上下文变量本身的默认值， 如果创建此上下文变量时提供了默认值；或者"

#: ../../library/contextvars.rst:66

msgid "raise a :exc:`LookupError`."

msgstr "抛出 :exc:`LookupError` 异常。"

#: ../../library/contextvars.rst:70

msgid ""

"Call to set a new value for the context variable in the current context."

msgstr "调用此方法设置上下文变量在当前上下文中的值。"

#: ../../library/contextvars.rst:73

msgid ""

"The required *value* argument is the new value for the context variable."

msgstr "必选参数 *value* 是上下文变量的新值。"

#: ../../library/contextvars.rst:76

msgid ""

"Returns a :class:`~contextvars.Token` object that can be used to restore the"

" variable to its previous value via the :meth:`ContextVar.reset` method."

msgstr ""

"返回一个 :class:`~contextvars.Token`  对象，可通过 :meth:`ContextVar.reset` "

"方法将上下文变量还原为之前某个状态。"

#: ../../library/contextvars.rst:82

msgid ""

"Reset the context variable to the value it had before the "

":meth:`ContextVar.set` that created the *token* was used."

msgstr "将上下文变量重置为调用 :meth:`ContextVar.set` 之前、创建 *token* 时候的状态。"

#: ../../library/contextvars.rst:85

msgid "For example::"

msgstr "例如："

#: ../../library/contextvars.rst:87

msgid ""

"var = ContextVar('var')\n"

"\n"

"token = var.set('new value')\n"

"# code that uses 'var'; var.get() returns 'new value'.\n"

"var.reset(token)\n"

"\n"

"# After the reset call the var has no value again, so\n"

"# var.get() would raise a LookupError."

msgstr ""

"var = ContextVar('var')\n"

"\n"

"token = var.set('new value')\n"

"# 使用 'var' 的代码；var.get() 将返回 'new value'。\n"

"var.reset(token)\n"

"\n"

"# 在重置调用之后 var 将不再有值，\n"

"# 因此 var.get() 将引发一个 LookupError。"

#: ../../library/contextvars.rst:99

msgid ""

"*Token* objects are returned by the :meth:`ContextVar.set` method. They can "

"be passed to the :meth:`ContextVar.reset` method to revert the value of the "

"variable to what it was before the corresponding *set*."

msgstr ""

":meth:`ContextVar.set` 方法返回 *Token* 对象。此对象可以传递给 :meth:`ContextVar.reset` "

"方法用于将上下文变量还原为调用 *set* 前的状态。"

#: ../../library/contextvars.rst:106

msgid ""

"A read-only property. Points to the :class:`ContextVar` object that created"

" the token."

msgstr "只读属性。指向创建此 token 的 :class:`ContextVar` 对象。"

#: ../../library/contextvars.rst:111

msgid ""

"A read-only property. Set to the value the variable had before the "

":meth:`ContextVar.set` method call that created the token. It points to "

":attr:`Token.MISSING` if the variable was not set before the call."

msgstr ""

"一个只读属性。 会被设为在创建此令牌的 :meth:`ContextVar.set` 方法调用之前该变量所具有的值。 "

"如果调用之前变量没有设置值则它会指令 :attr:`Token.MISSING`。"

#: ../../library/contextvars.rst:118

msgid "A marker object used by :attr:`Token.old_value`."

msgstr ":attr:`Token.old_value` 会用到的一个标记对象。"

#: ../../library/contextvars.rst:122

msgid "Manual Context Management"

msgstr "手动上下文管理"

#: ../../library/contextvars.rst:126

msgid "Returns a copy of the current :class:`~contextvars.Context` object."

msgstr "返回当前上下文中 :class:`~contextvars.Context` 对象的拷贝。"

#: ../../library/contextvars.rst:128

msgid ""

"The following snippet gets a copy of the current context and prints all "

"variables and their values that are set in it::"

msgstr "以下代码片段会获取当前上下文的拷贝并打印设置到其中的所有变量及其值::"

#: ../../library/contextvars.rst:131

msgid ""

"ctx: Context = copy_context()\n"

"print(list(ctx.items()))"

msgstr ""

"ctx: Context = copy_context()\n"

"print(list(ctx.items()))"

#: ../../library/contextvars.rst:134

msgid ""

"The function has an *O*\\ (1) complexity, i.e. works equally fast for "

"contexts with a few context variables and for contexts that have a lot of "

"them."

msgstr "此函数具有 *O*\\ (1) 复杂度，也就是说对于只包含几个上下文变量和很多上下文变量的情况运行速度是相同的。"

#: ../../library/contextvars.rst:141

msgid "A mapping of :class:`ContextVars <ContextVar>` to their values."

msgstr ":class:`ContextVars <ContextVar>` 与其值的映射。"

#: ../../library/contextvars.rst:143

msgid ""

"``Context()`` creates an empty context with no values in it. To get a copy "

"of the current context use the :func:`~contextvars.copy_context` function."

msgstr ""

"``Context()`` 创建一个不包含任何值的空上下文。如果要获取当前上下文的拷贝，使用 "

":func:`~contextvars.copy_context` 函数。"

#: ../../library/contextvars.rst:147

msgid ""

"Every thread will have a different top-level :class:`~contextvars.Context` "

"object. This means that a :class:`ContextVar` object behaves in a similar "

"fashion to :func:`threading.local` when values are assigned in different "

"threads."

msgstr ""

"每个线程将有一个不同的最高层级 :class:`~contextvars.Context` 对象。 这意味着当在不同的线程中赋值时 "

":class:`ContextVar` 对象的行为方式与 :func:`threading.local` 类似。"

#: ../../library/contextvars.rst:152

msgid "Context implements the :class:`collections.abc.Mapping` interface."

msgstr "Context 实现了 :class:`collections.abc.Mapping` 接口。"

#: ../../library/contextvars.rst:156

msgid ""

"Execute ``callable(*args, **kwargs)`` code in the context object the *run* "

"method is called on. Return the result of the execution or propagate an "

"exception if one occurred."

msgstr ""

"按照 *run* 方法中的参数在上下文对象中执行 ``callable(*args, **kwargs)`` "

"代码。返回执行结果，如果发生异常，则将异常透传出来。"

#: ../../library/contextvars.rst:160

msgid ""

"Any changes to any context variables that *callable* makes will be contained"

" in the context object::"

msgstr "*callable* 对上下文变量所做的任何修改都会保留在上下文对象中::"

#: ../../library/contextvars.rst:163

msgid ""

"var = ContextVar('var')\n"

"var.set('spam')\n"

"\n"

"def main():\n"

" # 'var' was set to 'spam' before\n"

" # calling 'copy_context()' and 'ctx.run(main)', so:\n"

" # var.get() == ctx[var] == 'spam'\n"

"\n"

" var.set('ham')\n"

"\n"

" # Now, after setting 'var' to 'ham':\n"

" # var.get() == ctx[var] == 'ham'\n"

"\n"

"ctx = copy_context()\n"

"\n"

"# Any changes that the 'main' function makes to 'var'\n"

"# will be contained in 'ctx'.\n"

"ctx.run(main)\n"

"\n"

"# The 'main()' function was run in the 'ctx' context,\n"

"# so changes to 'var' are contained in it:\n"

"# ctx[var] == 'ham'\n"

"\n"

"# However, outside of 'ctx', 'var' is still set to 'spam':\n"

"# var.get() == 'spam'"

msgstr ""

"var = ContextVar('var')\n"

"var.set('spam')\n"

"\n"

"def main():\n"

" # 在调用 'copy_context()' 和 'ctx.run(main)' 之前\n"

" # 'var' 被设为 'spam'，因此：\n"

" # var.get() == ctx[var] == 'spam'\n"

"\n"

" var.set('ham')\n"

"\n"

" # 现在，将 'var' 设为 'ham' 之后：\n"

" # var.get() == ctx[var] == 'ham'\n"

"\n"

"ctx = copy_context()\n"

"\n"

"# 'main' 函数对 'var' 的任何修改\n"

"# 都将包含在 'ctx' 中。\n"

"ctx.run(main)\n"

"\n"

"# 'main()' 函数是在 'ctx' 上下文中运行的，\n"

"# 因此对 'var' 的修改包含在其中：\n"

"# ctx[var] == 'ham'\n"

"\n"

"# 不过，在 'ctx' 之外，'var' 仍然被设为 'spam'：\n"

"# var.get() == 'spam'"

#: ../../library/contextvars.rst:189

msgid ""

"The method raises a :exc:`RuntimeError` when called on the same context "

"object from more than one OS thread, or when called recursively."

msgstr "当在多个系统线程或者递归调用同一个上下文对象的此方法，抛出 :exc:`RuntimeError` 异常。"

#: ../../library/contextvars.rst:195

msgid "Return a shallow copy of the context object."

msgstr "返回此上下文对象的浅拷贝。"

#: ../../library/contextvars.rst:199

msgid ""

"Return ``True`` if the *context* has a value for *var* set; return ``False``"

" otherwise."

msgstr "如果 *context* 中含有名称为 *var* 的变量，返回 ``True``， 否则返回 ``False``。"

#: ../../library/contextvars.rst:204

msgid ""

"Return the value of the *var* :class:`ContextVar` variable. If the variable "

"is not set in the context object, a :exc:`KeyError` is raised."

msgstr ""

"返回名称为 *var* 的 :class:`ContextVar` 变量。如果上下文对象中不包含这个变量，则抛出 :exc:`KeyError` 异常。"

#: ../../library/contextvars.rst:210

msgid ""

"Return the value for *var* if *var* has the value in the context object. "

"Return *default* otherwise. If *default* is not given, return ``None``."

msgstr ""

"如果 *var* 在上下文对象中具有值则返回 *var* 的值。 在其他情况下返回 *default*。 如果未给出 *default* 则返回 "

"``None``。"

#: ../../library/contextvars.rst:216

msgid "Return an iterator over the variables stored in the context object."

msgstr "返回一个存储在上下文对象中的变量的迭代器。"

#: ../../library/contextvars.rst:221

msgid "Return the number of variables set in the context object."

msgstr "返回上下文对象中所设的变量的数量。"

#: ../../library/contextvars.rst:225

msgid "Return a list of all variables in the context object."

msgstr "返回上下文对象中的所有变量的列表。"

#: ../../library/contextvars.rst:229

msgid "Return a list of all variables' values in the context object."

msgstr "返回上下文对象中所有变量值的列表。"

#: ../../library/contextvars.rst:234

msgid ""

"Return a list of 2-tuples containing all variables and their values in the "

"context object."

msgstr "返回包含上下文对象中所有变量及其值的 2 元组的列表。"

#: ../../library/contextvars.rst:239

msgid "asyncio support"

msgstr "asyncio 支持"

#: ../../library/contextvars.rst:241

msgid ""

"Context variables are natively supported in :mod:`asyncio` and are ready to "

"be used without any extra configuration. For example, here is a simple echo"

" server, that uses a context variable to make the address of a remote client"

" available in the Task that handles that client::"

msgstr ""

"上下文变量在 :mod:`asyncio` 中有原生的支持并且无需任何额外配置即可被使用。 "

"例如，以下是一个简单的回显服务器，它使用上下文变量来让远程客户端的地址在处理该客户端的 Task 中可用::"

#: ../../library/contextvars.rst:247

msgid ""

"import asyncio\n"

"import contextvars\n"

"\n"

"client_addr_var = contextvars.ContextVar('client_addr')\n"

"\n"

"def render_goodbye():\n"

" # The address of the currently handled client can be accessed\n"

" # without passing it explicitly to this function.\n"

"\n"

" client_addr = client_addr_var.get()\n"

" return f'Good bye, client @ {client_addr}\\r\\n'.encode()\n"

"\n"

"async def handle_request(reader, writer):\n"

" addr = writer.transport.get_extra_info('socket').getpeername()\n"

" client_addr_var.set(addr)\n"

"\n"

" # In any code that we call is now possible to get\n"

" # client's address by calling 'client_addr_var.get()'.\n"

"\n"

" while True:\n"

" line = await reader.readline()\n"

" print(line)\n"

" if not line.strip():\n"

" break\n"

"\n"

" writer.write(b'HTTP/1.1 200 OK\\r\\n') # status line\n"

" writer.write(b'\\r\\n') # headers\n"

" writer.write(render_goodbye()) # body\n"

" writer.close()\n"

"\n"

"async def main():\n"

" srv = await asyncio.start_server(\n"

" handle_request, '127.0.0.1', 8081)\n"

"\n"

" async with srv:\n"

" await srv.serve_forever()\n"

"\n"

"asyncio.run(main())\n"

"\n"

"# To test it you can use telnet or curl:\n"

"# telnet 127.0.0.1 8081\n"

"# curl 127.0.0.1:8081"

msgstr ""

"import asyncio\n"

"import contextvars\n"

"\n"

"client_addr_var = contextvars.ContextVar('client_addr')\n"

"\n"

"def render_goodbye():\n"

" # 可直接访问当前处理的客户端地址\n"

" # 而无需显式地将其传给此函数。\n"

"\n"

" client_addr = client_addr_var.get()\n"

" return f'Good bye, client @ {client_addr}\\r\\n'.encode()\n"

"\n"

"async def handle_request(reader, writer):\n"

" addr = writer.transport.get_extra_info('socket').getpeername()\n"

" client_addr_var.set(addr)\n"

"\n"

" # 现在将可以在我们所调用的任何代码中通过\n"

" # 'client_addr_var.get()' 调用来获取客户端地址。\n"

"\n"

" while True:\n"

" line = await reader.readline()\n"

" print(line)\n"

" if not line.strip():\n"

" break\n"

"\n"

" writer.write(b'HTTP/1.1 200 OK\\r\\n') # 状态行\n"

" writer.write(b'\\r\\n') # 标头\n"

" writer.write(render_goodbye()) # 消息体\n"

" writer.close()\n"

"\n"

"async def main():\n"

" srv = await asyncio.start_server(\n"

" handle_request, '127.0.0.1', 8081)\n"

"\n"

" async with srv:\n"

" await srv.serve_forever()\n"

"\n"

"asyncio.run(main())\n"

"\n"

"# 要进行测试你可以使用 telnet 或 curl：\n"

"# telnet 127.0.0.1 8081\n"

"# curl 127.0.0.1:8081"