http.cookies --- HTTP の状態管理

ソースコード: Lib/http/cookies.py

http.cookies モジュールはHTTPの状態管理機能であるcookieの概念を抽象化、定義しているクラスです。単純な文字列のみで構成されるcookieのほか、シリアル化可能なあらゆるデータ型でクッキーの値を保持するための機能も備えています。

このモジュールは元々 RFC 2109 と RFC 2068 に定義されている構文解析の規則を厳密に守っていました。しかし、MSIE 3.0x がこれらの RFC で定義された文字の規則に従っていなかったことが判明し、現在の多くのブラウザーとサーバーも Cookie の処理に関しては緩い解析を行っています。結局、このモジュールは昔よりもやや厳密さを欠く構文解析規則になっています。

文字集合 string.ascii_letters 、 string.digits 、 !#$%&'*+-.^_`|~: を、このモジュールは cookie 名 (key) として有効と認めています。

バージョン 3.3 で変更: ':' が有効な cookie 名の文字として認められました。

注釈

不正な cookie に遭遇した場合、 CookieError 例外を送出します。そのため、ブラウザから持ってきた cookie データをパースするときには常に不正なデータに備え CookieError 例外を捕捉してください。

exception http.cookies.CookieError

属性や Set-Cookie ヘッダが正しくないなど、 RFC 2109 に合致していないときに発生する例外です。

class http.cookies.BaseCookie([input])

このクラスはキーが文字列、値が Morsel インスタンスで構成される辞書風オブジェクトです。値に対するキーを設定するときは、値がキーと値を含む Morsel に変換されることに注意してください。

input が与えられたときは、そのまま load() メソッドへ渡されます。

class http.cookies.SimpleCookie([input])

このクラスは BaseCookie を継承し、 value_decode() と value_encode() をオーバーライドします。 SimpleCookie は文字列と cookie 値をサポートします。値を設定するとき、 SimpleCookie は組み込みの str() を呼び出して値を文字列に変換します。HTTP から受け取った値は文字列として保持されます。

参考

モジュール http.cookiejar

Web クライアント 向けの HTTP クッキー処理です。 http.cookiejar と http.cookies は互いに独立しています。

RFC 2109 - HTTP State Management Mechanism

このモジュールが実装しているHTTPの状態管理に関する規格です。

Morselオブジェクト

class http.cookies.Morsel

RFC 2109 の属性をキーと値で保持するabstractクラスです。

Morselは辞書風のオブジェクトで、キーは次のような RFC 2109 準拠の定数となっています:

expires
path
comment
domain
max-age
secure
version
httponly
samesite
partitioned

httponly 属性は、 cookie が HTTP リクエストでのみ送信されて、 JavaScript からのはアクセスできない事を示します。これはいくつかのクロスサイトスクリプティングの脅威を和らげることを意図しています。

samesite 属性は、ブラウザーがクロスサイトリクエストに加えて cookie の送信も禁止することを指定します。これは CSRF 攻撃の軽減に役立ちます。この属性い有効な値は、 "Strict" と "Lax" です。

The attribute partitioned indicates to user agents that these cross-site cookies should only be available in the same top-level context that the cookie was first set in. For this to be accepted by the user agent, you must also set Secure.

In addition, it is recommended to use the __Host prefix when setting partitioned cookies to make them bound to the hostname and not the registrable domain. Read CHIPS (Cookies Having Independent Partitioned State) for full details and examples.

キーの大小文字は区別されません。そのデフォルト値は '' です。

バージョン 3.5 で変更: __eq__() は key 及び value を考慮するようになりました。

バージョン 3.7 で変更: key と value 、 coded_value 属性は読み出し専用です。設定には、 set() を使用してください。

バージョン 3.8 で変更: samesite 属性がサポートされました。

バージョン 3.14 で変更: Added support for the partitioned attribute.

Morsel.value

クッキーの値。

Morsel.coded_value

実際に送信する形式にエンコードされたcookieの値。

Morsel.key

cookieの名前。

Morsel.set(key, value, coded_value)

属性 key 、 value 、 coded_value に値をセットします。

Morsel.isReservedKey(K)

K が Morsel のキーであるかどうかを判定します。

Morsel.output(attrs=None, header='Set-Cookie:')

MoselをHTTPヘッダ形式の文字列表現にして返します。 attrs を指定しない場合、デフォルトですべての属性を含めます。 attrs を指定する場合、属性をリストで渡さなければなりません。 header のデフォルトは "Set-Cookie:" です。

Morsel.js_output(attrs=None)

ブラウザがJavaScriptをサポートしている場合、HTTPヘッダを送信した場合と同様に動作する埋め込み可能なJavaScript snippetを返します。

attrs の意味は output() と同じです。

Morsel.OutputString(attrs=None)

Moselの文字列表現をHTTPやJavaScriptで囲まずに出力します。

attrs の意味は output() と同じです。

Morsel.update(values)

Morsel 辞書の値を辞書 values の値で更新します。values 辞書のキーのいずれかが有効な RFC 2109 属性でない場合エラーを送出します。

バージョン 3.5 で変更: 不正なキーではエラーが送出されます。

Morsel.copy(value)

Morsel オブジェクトの浅いコピーを返します。

バージョン 3.5 で変更: 辞書ではなく Morsel オブジェクトを返します。

Morsel.setdefault(key, value=None)

キーが有効な RFC 2109 属性でない場合エラーを送出します。そうでない場合は dict.setdefault() と同じように振る舞います。

使用例

次の例は http.cookies の使い方を示したものです。

>>>
>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = cookies.SimpleCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print(C.output(header="Cookie:"))
Cookie: rocky=road; Path=/cookie
>>> print(C.output(attrs=[], header="Cookie:"))
Cookie: rocky=road
>>> C = cookies.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print(C)
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = cookies.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print(C)
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = cookies.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print(C)
Set-Cookie: oreo=doublestuff; Path=/
>>> C = cookies.SimpleCookie()
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = cookies.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print(C)
Set-Cookie: number=7
Set-Cookie: string=seven