`microdot.session` --- 已簽署的 cookie 工作階段¶

一個以單一 session cookie 中的 jwt 為後盾的每使用者鍵/值儲存區。該 JWT 以只有應用程式知道的密鑰簽署，因此用戶端可以讀取該 cookie，但無法在不被伺服器偵測到的情況下竄改酬載。

class Session¶

class microdot.session.Session(app: Microdot | None = None, secret_key: bytes | str | None = None, cookie_options: dict | None = None)¶

app: 要安裝到其上的 microdot.Microdot 實例。為選用；若未提供，可稍後呼叫 initialize()。
secret_key: 用於簽署工作階段 JWT 的對稱金鑰。在讀取或寫入任何工作階段之前都必須提供 —— 在沒有它的情況下存取 get() 會引發 ValueError。請將其儲存在原始碼控制之外；在相機上，這通常是 FAT 檔案系統上的一個檔案。
cookie_options: 每當寫入工作階段 cookie 時，會轉發給 microdot.Response.set_cookie() 的選項字典。預設會設定 path='/' 與 http_only=True。對於僅限 HTTPS 的部署，請加上 secure=True。

initialize(app: Microdot, secret_key=None, cookie_options=None)¶: 若建構被延遲，則附掛到 app。若有提供，secret_key / cookie_options 會覆寫建構函式的值。

get(request) → SessionDict¶: 回傳 request 的工作階段字典。該字典會在首次存取時從 session cookie 延遲解碼，並在該請求的其餘期間快取於 request.g._session。已遭竄改 / 無法驗證簽章的 cookie 會回傳空字典。

encode(payload: dict, secret_key=None) → str¶: 以工作階段的密鑰將 payload 編碼為 JWT。供內部使用；公開出來是供希望鑄造相容權杖的呼叫端使用。

decode(session: str, secret_key=None) → dict¶: 驗證並解碼一個 JWT 字串工作階段值。在任何驗證失敗時回傳 {}。

secret_key: bytes | str | None¶: 用於簽署及驗證工作階段 JWT 的簽署密鑰。可在建構後設定。在設定之前為 None；在未設定它的情況下讀取工作階段會引發 ValueError。

cookie_options: dict¶: 寫入工作階段 cookie 時所套用的選項字典，會轉發給 microdot.Response.set_cookie()。在 initialize() 執行之後，預設會設定 path='/' 與 http_only=True。

class SessionDict¶

class microdot.session.SessionDict(request, session_dict)¶

由 Session.get() 回傳的類字典物件。其繼承 dict，因此所有標準的變動操作都可運作；另有兩個額外的方法可將變更提交回回應中。

save()¶: 將（可能已變動的）工作階段以新的 session cookie 寫回回應。若不呼叫此方法，就地的編輯會在請求結束時遺失。

delete()¶: 藉由在回應上發出一個 cookie 刪除標頭來移除工作階段。

模組層級裝飾器¶

microdot.session.with_session(f)¶

將工作階段字典作為第二個引數傳給路由處理常式的裝飾器：：

from microdot import Microdot
from microdot.session import Session, with_session

app = Microdot()
Session(app, secret_key=load_secret())

@app.get('/counter')
@with_session
async def counter(request, session):
    session['n'] = session.get('n', 0) + 1
    session.save()
    return {'n': session['n']}

此裝飾器不會自動儲存 —— 當工作階段被修改時，請呼叫 SessionDict.save()。

工作階段酬載本身是一個一般的 Python 字典，序列化為 JSON 後置於 JWT 之中。請保持其精簡：每個請求與每個回應都會夾帶完整的 cookie，而 JWT 並非設計用來儲存大型物件。對於大於數百位元組的每使用者狀態，請以一個小型工作階段識別碼為鍵，將資料儲存在伺服器端。