diff --git a/library/contextvars.po b/library/contextvars.po index b229a722fe..734d35fd88 100644 --- a/library/contextvars.po +++ b/library/contextvars.po @@ -5,7 +5,7 @@ msgstr "" "Project-Id-Version: Python 3.13\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2024-10-31 00:13+0000\n" -"PO-Revision-Date: 2018-07-15 18:56+0800\n" +"PO-Revision-Date: 2025-07-30 22:06+0800\n" "Last-Translator: \n" "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" "tw)\n" @@ -13,6 +13,7 @@ msgstr "" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" +"X-Generator: Poedit 3.6\n" #: ../../library/contextvars.rst:2 msgid ":mod:`!contextvars` --- Context Variables" @@ -26,6 +27,10 @@ msgid "" "the :class:`~contextvars.Context` class should be used to manage the current " "context in asynchronous frameworks." msgstr "" +"本模組供 API 來管理、儲存及存取單一情境各自的狀態(context-local state)。 " +"用 :class:`~contextvars.ContextVar` 類別宣告和處理\\ *情境變數*。 :func:" +"`~contextvars.copy_context` 函式和 :class:`~contextvars.Context` 類別應在非同" +"步框架中管理目前的情境。" #: ../../library/contextvars.rst:17 msgid "" @@ -33,18 +38,21 @@ msgid "" "func:`threading.local` to prevent their state from bleeding to other code " "unexpectedly, when used in concurrent code." msgstr "" +"帶有狀態的 Context Manager 應該使用情境變數,而不是 :func:`threading.local`," +"才能防止它們的狀態在並行(concurrent)程式碼中使用時意外外溢並干擾到其他程式" +"碼。" #: ../../library/contextvars.rst:21 msgid "See also :pep:`567` for additional details." -msgstr "額外資訊請見 :pep:`567`。" +msgstr "其他詳細資訊,請參閱 :pep:`567`。" #: ../../library/contextvars.rst:27 msgid "Context Variables" -msgstr "" +msgstr "情境變數" #: ../../library/contextvars.rst:31 msgid "This class is used to declare a new Context Variable, e.g.::" -msgstr "" +msgstr "此類別用在宣告新的情境變數,例如:" #: ../../library/contextvars.rst:33 msgid "var: ContextVar[int] = ContextVar('var', default=42)" @@ -53,7 +61,7 @@ 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 "" +msgstr "必要參數 *name* 用於自我檢查(introspection)和除錯。" #: ../../library/contextvars.rst:38 msgid "" @@ -61,6 +69,8 @@ msgid "" "`ContextVar.get` when no value for the variable is found in the current " "context." msgstr "" +"當在目前的情境中找不到變數的值時,:meth:`ContextVar.get` 會回傳可選的僅限關鍵字參" +"數 *default*。" #: ../../library/contextvars.rst:42 msgid "" @@ -69,6 +79,9 @@ msgid "" "context variables which prevents context variables from being properly " "garbage collected." msgstr "" +"**重要:**\\ 情境變數應該在最頂端的模組層級建立,絕對不要在閉包(closure)中" +"建立。 :class:`Context` 物件持有情境變數的強參照,這會阻止情境變數被正確地垃" +"圾回收(garbage collected)。" #: ../../library/contextvars.rst:49 msgid "The name of the variable. This is a read-only property." @@ -76,50 +89,52 @@ msgstr "這個變數的名稱。這是一個唯讀屬性。" #: ../../library/contextvars.rst:55 msgid "Return a value for the context variable for the current context." -msgstr "" +msgstr "回傳當前情境的情境變數值。" #: ../../library/contextvars.rst:57 msgid "" "If there is no value for the variable in the current context, the method " "will:" -msgstr "" +msgstr "如果在當前情境中沒有變數的值,此方法將:" #: ../../library/contextvars.rst:60 msgid "" "return the value of the *default* argument of the method, if provided; or" -msgstr "" +msgstr "回傳方法的 *default* 引數值(如果有的話);否則" #: ../../library/contextvars.rst:63 msgid "" "return the default value for the context variable, if it was created with " "one; or" -msgstr "" +msgstr "回傳情境變數的預設值(如果建立情境變數時有指定預設值的話);否則" #: ../../library/contextvars.rst:66 msgid "raise a :exc:`LookupError`." -msgstr "引發一個 :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 "" +msgstr "在目前的情境中,呼叫以設定情境變數的新值。" #: ../../library/contextvars.rst:73 msgid "" "The required *value* argument is the new value for the context variable." -msgstr "" +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 "" +msgstr "將情境變數重設為使用 :meth:`ContextVar.set` 建立 *token* 前的值。" #: ../../library/contextvars.rst:85 msgid "For example::" @@ -136,6 +151,14 @@ msgid "" "# 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 "" @@ -143,12 +166,14 @@ msgid "" "be passed to the :meth:`ContextVar.reset` method to revert the value of the " "variable to what it was before the corresponding *set*." msgstr "" +"*Token* 物件由 :meth:`ContextVar.set` 方法回傳,可以傳遞給 :meth:`ContextVar." +"reset` 方法,用以將變數的值還原為相對應的 *set* 之前的值。" #: ../../library/contextvars.rst:106 msgid "" "A read-only property. Points to the :class:`ContextVar` object that created " "the token." -msgstr "" +msgstr "唯讀屬性。 指向建立 token 的 :class:`ContextVar` 物件。" #: ../../library/contextvars.rst:111 msgid "" @@ -156,24 +181,27 @@ msgid "" "`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 "" +msgstr "由 :attr:`Token.old_value` 使用的標記物件。" #: ../../library/contextvars.rst:122 msgid "Manual Context Management" -msgstr "" +msgstr "手動情境管理" #: ../../library/contextvars.rst:126 msgid "Returns a copy of the current :class:`~contextvars.Context` object." -msgstr "" +msgstr "回傳目前 :class:`~contextvars.Context` 物件的複本(copy)。" #: ../../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 "" @@ -189,16 +217,20 @@ msgid "" "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 ` to their values." -msgstr "" +msgstr ":class:`ContextVars` 到其值的映射。" #: ../../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 "" @@ -207,6 +239,9 @@ msgid "" "current thread's stack. All :class:`!Context` objects in the stacks are " "considered to be *entered*." msgstr "" +"每個執行緒都有自己的 :class:`!Context` 物件中目前主控中的堆疊(stack)。:" +"term:`current context` 是目前執行緒堆疊頂端的 :class:`!Context` 物件。 堆疊" +"中的所有 :class:`!Context` 物件都被視為\\ *已進入*。" #: ../../library/contextvars.rst:152 msgid "" @@ -214,6 +249,8 @@ msgid "" "method, makes the context the current context by pushing it onto the top of " "the current thread's context stack." msgstr "" +"*進入*\\ 一個情境,可以藉由呼叫其 :meth:`~Context.run` 方法來完成,此\\ *進入" +"*\\ 的動作會將一情境推到目前執行緒的情境堆疊的頂端,使該情境成為目前的情境。" #: ../../library/contextvars.rst:156 msgid "" @@ -222,6 +259,9 @@ msgid "" "context to what it was before the context was entered by popping the context " "off the top of the context stack." msgstr "" +"如果你傳遞給 :meth:`~Context.run` 方法的回呼函式(callback functions),該函" +"式回傳之後,就會自動\\ *退出*\\ 目前的情境,這會將目前的情境還原到進入情境之" +"前的狀態,方法是將情境從情境堆疊的頂端彈出。" #: ../../library/contextvars.rst:161 msgid "" @@ -229,16 +269,20 @@ msgid "" "behave in a similar fashion to :func:`threading.local` when values are " "assigned in different threads." msgstr "" +"因為每個執行緒都有自己的情境堆疊,當值在不同的執行緒中被指定時, :class:" +"`ContextVar` 物件的行為與 :func:`threading.local` 相似。" #: ../../library/contextvars.rst:165 msgid "" "Attempting to enter an already entered context, including contexts entered " "in other threads, raises a :exc:`RuntimeError`." msgstr "" +"嘗試進入已進入的情境,包括在其他執行緒中進入的情境,會引發 :exc:" +"`RuntimeError`。" #: ../../library/contextvars.rst:168 msgid "After exiting a context, it can later be re-entered (from any thread)." -msgstr "" +msgstr "退出情境後,之後可以重新進入(從任何執行緒)。" #: ../../library/contextvars.rst:170 msgid "" @@ -249,10 +293,14 @@ msgid "" "context was entered (if needed, the values can be restored by re-entering " "the context)." msgstr "" +"任何透過 :meth:`ContextVar.set` 方法對 :class:`ContextVar` 值的改變都會記錄在" +"目前的情境中。 :meth:`ContextVar.get` 方法回傳與當前情境相關的值。 退出情境" +"實際造成的效果會像是將其在進入情境時對情境變數所做的任何變一一彈出並還原(如" +"果需要,可以透過重新進入情境來還原值)。" #: ../../library/contextvars.rst:177 msgid "Context implements the :class:`collections.abc.Mapping` interface." -msgstr "" +msgstr "情境(Context)實作了 :class:`collections.abc.Mapping` 介面。" #: ../../library/contextvars.rst:181 msgid "" @@ -260,10 +308,12 @@ msgid "" "Context. Returns *callable*'s return value, or propagates an exception if " "one occurred." msgstr "" +"進入 Context,執行``callable(*args, **kwargs)``,然後退出 Context。 回傳 " +"*callable* 的回傳值,如果發生例外(exception),則傳播例外。" #: ../../library/contextvars.rst:185 msgid "Example:" -msgstr "舉例來說:" +msgstr "例如:" #: ../../library/contextvars.rst:187 msgid "" @@ -298,50 +348,85 @@ msgid "" "# However, outside of 'ctx', 'var' is still set to 'spam':\n" "print(var.get()) # 'spam'" msgstr "" +"import contextvars\n" +"\n" +"var = contextvars.ContextVar('var')\n" +"var.set('spam')\n" +"print(var.get()) # 'spam'\n" +"\n" +"ctx = contextvars.copy_context()\n" +"\n" +"def main():\n" +" # 'var' 之前被設成 'spam'\n" +" # 呼叫 'copy_context()' 和 'ctx.run(main)',所以:\n" +" print(var.get()) # 'spam'\n" +" print(ctx[var]) # 'spam'\n" +"\n" +" var.set('ham')\n" +"\n" +" # 現在, 在把 'var' 的值設成 'ham' 後:\n" +" print(var.get()) # 'ham'\n" +" print(ctx[var]) # 'ham'\n" +"\n" +"# 'main' 函式對 'var' 所做的任何變更都會\n" +"# 包含在 'ctx 裡:.\n" +"ctx.run(main)\n" +"\n" +"# 'main()' 函式是在 'ctx' 情境中執行,\n" +"# 所以對 'var' 的變更會保存在 'ctx' 中:\n" +"print(ctx[var]) # 'ham'\n" +"\n" +"# 但是,在 'ctx' 外, 'var' 的值仍然是 'spam':\n" +"print(var.get()) # 'spam'" #: ../../library/contextvars.rst:233 msgid "Return a shallow copy of the context object." -msgstr "" +msgstr "回傳情境物件的淺層複本(shallow copy)。" #: ../../library/contextvars.rst:237 msgid "" "Return ``True`` if the *context* has a value for *var* set; return ``False`` " "otherwise." msgstr "" +"如果\\ *情境*\\ 裡面有 *var* 的值,則回傳 ``True``,否則回傳 ``False``。" #: ../../library/contextvars.rst:242 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:248 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:254 msgid "Return an iterator over the variables stored in the context object." -msgstr "" +msgstr "回傳儲存於情境物件中變數的疊代器。" #: ../../library/contextvars.rst:259 msgid "Return the number of variables set in the context object." -msgstr "" +msgstr "回傳情境物件中的變數個數。" #: ../../library/contextvars.rst:263 msgid "Return a list of all variables in the context object." -msgstr "" +msgstr "回傳情境物件中所有變數的串列。" #: ../../library/contextvars.rst:267 msgid "Return a list of all variables' values in the context object." -msgstr "" +msgstr "回傳情境物件中所有變數的值的串列。" #: ../../library/contextvars.rst:272 msgid "" "Return a list of 2-tuples containing all variables and their values in the " "context object." -msgstr "" +msgstr "回傳情境物件中所有變數與其值的 2-元組(2-tuples)的串列。" #: ../../library/contextvars.rst:277 msgid "asyncio support" @@ -354,6 +439,8 @@ msgid "" "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` 原生支援情境變數,不需任何額外設定。 舉例來說,以下是一個簡單" +"的 echo 伺服器,使用情境變數讓遠端用戶端的位址在處理該用戶端的任務中可用:" #: ../../library/contextvars.rst:285 msgid "" @@ -400,3 +487,45 @@ msgid "" "# 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" +" # 即使不把目前處理中的用戶端(client)傳入此函式\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') # 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" +"# 你可以使用 telnet 或 curl 測試:\n" +"# telnet 127.0.0.1 8081\n" +"# curl 127.0.0.1:8081"