`contextvars` --- 情境變數¶

本模組供 API 來管理、儲存及存取單一情境各自的狀態（context-local state）。用 ContextVar 類別宣告和處理情境變數。 copy_context() 函式和 Context 類別應在非同步框架中管理目前的情境。

帶有狀態的 Context Manager 應該使用情境變數，而不是 threading.local()，才能防止它們的狀態在並行（concurrent）程式碼中使用時意外外溢並干擾到其他程式碼。

其他詳細資訊，請參閱 PEP 567。

在 3.7 版被加入.

情境變數¶

class contextvars.ContextVar(name[, *, default])¶

此類別用在宣告新的情境變數，例如：

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

必要參數 name 用於自我檢查（introspection）和除錯。

當在目前的情境中找不到變數的值時，ContextVar.get() 會回傳可選的僅限關鍵字參數 default。

重要：情境變數應該在最頂端的模組層級建立，絕對不要在閉包（closure）中建立。 Context 物件持有情境變數的強參照，這會阻止情境變數被正確地垃圾回收（garbage collected）。

name¶: 這個變數的名稱。這是一個唯讀屬性。

在 3.7.1 版被加入.

get([default])¶

回傳目前情境的情境變數值。

如果在目前情境中沒有變數的值，此方法將：

回傳方法的 default 引數值（如果有的話）；否則
回傳情境變數的預設值（如果建立情境變數時有指定預設值的話）；否則
會引發一個 LookupError。

set(value)¶

在目前的情境中，呼叫以設定情境變數的新值。

value 屬必要引數，是情境變數的新值。

回傳一個 Token 物件，該物件可透過 ContextVar.reset() 方法，用來將變數還原到之前的值。

為了方便起見，token 物件可以用作情境管理器，以避免手動呼叫 ContextVar.reset()：

var = ContextVar('var', default='default value')

with var.set('new value'):
    assert var.get() == 'new value'

assert var.get() == 'default value'

它是以下程式碼的簡寫：

var = ContextVar('var', default='default value')

token = var.set('new value')
try:
    assert var.get() == 'new value'
finally:
    var.reset(token)

assert var.get() == 'default value'

在 3.14 版被加入: 新增對將 token 用作情境管理器的支援。

reset(token)¶

將情境變數重設為使用 ContextVar.set() 建立 token 前的值。

舉例來說：

var = ContextVar('var')

token = var.set('new value')
# 使用 'var' 的程式碼；var.get() 回傳 'new value'。
var.reset(token)

# 在重設呼叫之後，var 又沒有值了，所以
# var.get() 會引發 LookupError。

同一個 token 不能被使用兩次。

class contextvars.Token¶

Token 物件由 ContextVar.set() 方法回傳，可以傳遞給 ContextVar.reset() 方法，用以將變數的值還原為相對應的 set 之前的值。單一 token 不能重設情境變數超過一次。

Token 支援情境管理器協定，可自動重設情境變數。請參閱 ContextVar.set()。

在 3.14 版被加入: 新增對用作情境管理器的支援。

var¶: 唯讀屬性。指向建立 token 的 ContextVar 物件。

old_value¶: 唯讀屬性。值為變數在呼叫 ContextVar.set() 方法之前的值。如果變數在呼叫前沒有設定，則指向 Token.MISSING。

MISSING¶: 由 Token.old_value 使用的標記物件。

手動情境管理¶

contextvars.copy_context()¶

回傳目前 Context 物件的複本（copy）。

以下程式碼片段會取得目前情境的複本，並顯示在其中設定的所有變數及其值：:

ctx

contextvars --- 情境變數¶

情境變數¶

手動情境管理¶

`contextvars` --- 情境變數¶