21.24. http.cookiejar
— HTTP クライアント用の Cookie 処理¶
ソースコード: Lib/http/cookiejar.py
http.cookiejar
モジュールは HTTP クッキーの自動処理をおこなうクラスを定義します。これは小さなデータの断片 – クッキー – を要求する web サイトにアクセスする際に有用です。クッキーとは web サーバの HTTP レスポンスによってクライアントのマシンに設定され、のちの HTTP リクエストをおこなうさいにサーバに返されるものです。
標準的な Netscape クッキープロトコルおよび RFC 2965 で定義されているプロトコルの両方を処理できます。RFC 2965 の処理はデフォルトではオフになっています。 RFC 2109 のクッキーは Netscape クッキーとして解析され、のちに有効な 'ポリシー' に従って Netscapeまたは RFC 2965 クッキーとして処理されます。但し、インターネット上の大多数のクッキーは Netscapeクッキーです。 http.cookiejar
はデファクトスタンダードの Netscape クッキープロトコル (これは元々 Netscape が策定した仕様とはかなり異なっています) に従うようになっており、RFC 2109 で導入された max-age
や port
などのクッキー属性にも注意を払います。
注釈
Set-Cookie や Set-Cookie2 ヘッダに現れる多種多様なパラメータの名前 (domain
や expires
など) は便宜上 属性 と呼ばれますが、ここでは Python の属性と区別するため、かわりに クッキー属性 と呼ぶことにします。
このモジュールは以下の例外を定義しています:
この例外は
FileCookieJar
インスタンスがファイルからクッキーを読み込むのに失敗した場合に発生します。LoadError
はOSError
のサブクラスです。
以下のクラスが提供されています:
policy は
CookiePolicy
インターフェイスを実装するオブジェクトです。CookieJar
クラスには HTTP クッキーを保管します。これは HTTP リクエストに応じてクッキーを取り出し、それを HTTP レスポンスの中で返します。必要に応じて、CookieJar
インスタンスは保管されているクッキーを自動的に破棄します。このサブクラスは、クッキーをファイルやデータベースに格納したり取り出したりする操作をおこなう役割を負っています。
policy は
CookiePolicy
インターフェイスを実装するオブジェクトです。これ以外の引数については、該当する属性の説明を参照してください。FileCookieJar
はディスク上のファイルからのクッキーの読み込み、もしくは書き込みをサポートします。実際には、load()
またはrevert()
のどちらかのメソッドが呼ばれるまでクッキーは指定されたファイルからはロード されません 。このクラスのサブクラスは FileCookieJar のサブクラスと web ブラウザとの連携 節で説明します。
このクラスは、あるクッキーをサーバから受け入れるべきか、そしてサーバに返すべきかを決定する役割を負っています。
コンストラクタはキーワード引数しか取りません。 blocked_domains はドメイン名からなるシーケンスで、ここからは決してクッキーを受けとらないし、このドメインにクッキーを返すこともありません。 allowed_domains が
None
でない場合、これはこのドメインのみからクッキーを受けとり、返すという指定になります。これ以外の引数についてはCookiePolicy
およびDefaultCookiePolicy
オブジェクトの説明をごらんください。DefaultCookiePolicy
implements the standard accept / reject rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling is turned off orrfc2109_as_netscape
isTrue
, RFC 2109 cookies are 'downgraded' by theCookieJar
instance to Netscape cookies, by setting theversion
attribute of theCookie
instance to 0.DefaultCookiePolicy
also provides some parameters to allow some fine-tuning of policy.
This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not expected that users of
http.cookiejar
construct their ownCookie
instances. Instead, if necessary, callmake_cookies()
on aCookieJar
instance.
参考
urllib.request
モジュール- クッキーの自動処理をおこない URL を開くモジュールです。
http.cookies
モジュール- HTTP のクッキークラスで、基本的にはサーバサイドのコードで有用です。
http.cookiejar
およびhttp.cookies
モジュールは互いに依存してはいません。 - https://curl.haxx.se/rfc/cookie_spec.html
- 元祖 Netscape のクッキープロトコルの仕様です。今でもこれが主流のプロトコルですが、現在のメジャーなブラウザ (と
http.cookiejar
) が実装している「Netscape クッキープロトコル」はcookie_spec.html
で述べられているものとおおまかにしか似ていません。 - RFC 2109 - HTTP State Management Mechanism
- Obsoleted by RFC 2965. Uses Set-Cookie with version=1.
- RFC 2965 - HTTP State Management Mechanism
- Netscape プロトコルのバグを修正したものです。 Set-Cookie のかわりに Set-Cookie2 を使いますが、普及してはいません。
- http://kristol.org/cookie/errata.html
- Unfinished errata to RFC 2965.
RFC 2964 - Use of HTTP State Management
21.24.1. CookieJar および FileCookieJar オブジェクト¶
CookieJar
オブジェクトは保管されている Cookie
オブジェクトをひとつずつ取り出すための、イテレータ(iterator)・プロトコルをサポートしています。
CookieJar
は以下のようなメソッドを持っています:
request に正しい Cookie ヘッダを追加します。
ポリシーが許すようであれば (
CookieJar
のCookiePolicy
インスタンスにある属性のうち、rfc2965
およびhide_cookie2
がそれぞれ真と偽であるような場合)、必要に応じて Cookie2 ヘッダも追加されます。The request object (usually a
urllib.request..Request
instance) must support the methodsget_full_url()
,get_host()
,get_type()
,unverifiable()
,has_header()
,get_header()
,header_items()
,add_unredirected_header()
andorigin_req_host
attribute as documented byurllib.request
.バージョン 3.3 で変更: request object needs
origin_req_host
attribute. Dependency on a deprecated methodget_origin_req_host()
has been removed.
HTTP response からクッキーを取り出し、ポリシーによって許可されていればこれを
CookieJar
内に保管します。CookieJar
は response 引数の中から許可されている Set-Cookie および Set-Cookie2 ヘッダを探しだし、適切に (CookiePolicy.set_ok()
メソッドの承認におうじて) クッキーを保管します。The response object (usually the result of a call to
urllib.request.urlopen()
, or similar) should support aninfo()
method, which returns anemail.message.Message
instance.The request object (usually a
urllib.request.Request
instance) must support the methodsget_full_url()
,get_host()
,unverifiable()
, andorigin_req_host
attribute, as documented byurllib.request
. The request is used to set default values for cookie-attributes as well as for checking that the cookie is allowed to be set.バージョン 3.3 で変更: request object needs
origin_req_host
attribute. Dependency on a deprecated methodget_origin_req_host()
has been removed.
使用する
CookiePolicy
インスタンスを指定します。
response オブジェクトから得られた
Cookie
オブジェクトからなるシーケンスを返します。response および request 引数で要求されるインスタンスについては、
extract_cookies()
の説明を参照してください。
ポリシーが許すのであれば、与えられた
Cookie
を設定します。
与えられた
Cookie
を、それが設定されるべきかどうかのポリシーのチェックを行わずに設定します。
いくつかのクッキーを消去します。
引数なしで呼ばれた場合は、すべてのクッキーを消去します。引数がひとつ与えられた場合、その domain に属するクッキーのみを消去します。ふたつの引数が与えられた場合、指定された domain と URL path に属するクッキーのみを消去します。引数が 3つ与えられた場合、domain, path および name で指定されるクッキーが消去されます。
与えられた条件に一致するクッキーがない場合は
KeyError
を発生させます。
すべてのセッションクッキーを消去します。
保存されているクッキーのうち、
discard
属性が真になっているものすべてを消去します (通常これはmax-age
またはexpires
のどちらのクッキー属性もないか、あるいは明示的にdiscard
クッキー属性が指定されているものです)。対話的なブラウザの場合、セッションの終了はふつうブラウザのウィンドウを閉じることに相当します。注意: ignore_discard 引数に真を指定しないかぎり、
save()
メソッドはセッションクッキーは保存しません。
さらに FileCookieJar
は以下のようなメソッドを実装しています:
クッキーをファイルに保存します。
この基底クラスは
NotImplementedError
を発生させます。サブクラスはこのメソッドを実装しないままにしておいてもかまいません。filename はクッキーを保存するファイルの名前です。 filename が指定されない場合、
self.filename
が使用されます (このデフォルト値は、それが存在する場合は、コンストラクタに渡されています)。self.filename
もNone
の場合はValueError
が発生します。ignore_discard : 破棄されるよう指示されていたクッキーでも保存します。ignore_expires : 期限の切れたクッキーでも保存します。
ここで指定されたファイルがもしすでに存在する場合は上書きされるため、以前にあったクッキーはすべて消去されます。保存したクッキーはあとで
load()
またはrevert()
メソッドを使って復元することができます。
ファイルからクッキーを読み込みます。
それまでのクッキーは新しいものに上書きされない限り残ります。
ここでの引数の値は
save()
と同じです。The named file must be in the format understood by the class, or
LoadError
will be raised. Also,OSError
may be raised, for example if the file does not exist.
FileCookieJar
インスタンスは以下のような公開の属性をもっています:
クッキーを保存するデフォルトのファイル名を指定します。この属性には代入することができます。
真であれば、クッキーを読み込むさいにディスクから遅延読み込みします。この属性には代入することができません。この情報は単なるヒントであり、 (ディスク上のクッキーが変わらない限りは) インスタンスのふるまいには影響を与えず、パフォーマンスのみに影響します。
CookieJar
オブジェクトはこの値を無視することもあります。標準ライブラリに含まれているFileCookieJar
クラスで遅延読み込みをおこなうものはありません。
21.24.2. FileCookieJar のサブクラスと web ブラウザとの連携¶
クッキーの読み書きのために、以下の CookieJar
サブクラスが提供されています。
Mozilla の
cookies.txt
ファイル形式 (この形式はまた Lynx と Netscape ブラウザによっても使われています) でディスクにクッキーを読み書きするためのFileCookieJar
です。注釈
This loses information about RFC 2965 cookies, and also about newer or non-standard cookie-attributes such as
port
.警告
もしクッキーの損失や欠損が望ましくない場合は、クッキーを保存する前にバックアップを取っておくようにしてください (ファイルへの読み込み / 保存をくり返すと微妙な変化が生じる場合があります)。
また、Mozilla の起動中にクッキーを保存すると、Mozilla によって内容が破壊されてしまうことにも注意してください。
libwww-perl のライブラリである
Set-Cookie3
ファイル形式でディスクにクッキーを読み書きするためのFileCookieJar
です。これはクッキーを人間に可読な形式で保存するのに向いています。
21.24.3. CookiePolicy オブジェクト¶
CookiePolicy
インターフェイスを実装するオブジェクトは以下のようなメソッドを持っています:
クッキーがサーバから受け入れられるべきかどうかを表わす boolean 値を返します。
cookie は
Cookie
インスタンスです。 request はCookieJar.extract_cookies()
の説明で定義されているインターフェイスを実装するオブジェクトです。
クッキーがサーバに返されるべきかどうかを表わす boolean 値を返します。
cookie は
Cookie
インスタンスです。 request はCookieJar.add_cookie_header()
の説明で定義されているインターフェイスを実装するオブジェクトです。
与えられたクッキーのドメインに対して、そこにクッキーを返すべきでない場合には false を返します。
このメソッドは高速化のためのものです。これにより、すべてのクッキーをある特定のドメインに対してチェックする (これには多数のファイル読みこみを伴なう場合があります) 必要がなくなります。
domain_return_ok()
およびpath_return_ok()
の両方から true が返された場合、すべての決定はreturn_ok()
に委ねられます。もし、このクッキードメインに対して
domain_return_ok()
が true を返すと、つぎにそのクッキーのパス名に対してpath_return_ok()
が呼ばれます。そうでない場合、そのクッキードメインに対するpath_return_ok()
およびreturn_ok()
は決して呼ばれることはありません。path_return_ok()
が true を返すと、return_ok()
がそのCookie
オブジェクト自身の全チェックのために呼ばれます。そうでない場合、そのクッキーパス名に対するreturn_ok()
は決して呼ばれることはありません。注意:
domain_return_ok()
は request ドメインだけではなく、すべての cookie ドメインに対して呼ばれます。たとえば request ドメインが"www.example.com"
だった場合、この関数は".example.com"
および"www.example.com"
の両方に対して呼ばれることがあります。同じことはpath_return_ok()
にもいえます。request 引数は
return_ok()
で説明されているとおりです。
与えられたクッキーのパス名に対して、そこにクッキーを返すべきでない場合には false を返します。
domain_return_ok()
の説明を参照してください。
上のメソッドの実装にくわえて、 CookiePolicy
インターフェイスの実装では以下の属性を設定する必要があります。これはどのプロトコルがどのように使われるべきかを示すもので、これらの属性にはすべて代入することが許されています。
Netscape プロトコルを実装していることを示します。
Implement RFC 2965 protocol.
Don’t add Cookie2 header to requests (the presence of this header indicates to the server that we understand RFC 2965 cookies).
もっとも有用な方法は、 DefaultCookiePolicy
をサブクラス化した CookiePolicy
クラスを定義して、いくつか (あるいはすべて) のメソッドをオーバーライドすることでしょう。 CookiePolicy
自体はどのようなクッキーも受け入れて設定を許可する「ポリシー無し」ポリシーとして使うこともできます (これが役に立つことはあまりありませんが)。
21.24.4. DefaultCookiePolicy オブジェクト¶
クッキーを受けつけ、またそれを返す際の標準的なルールを実装します。
Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched off by default.
自分のポリシーを提供するいちばん簡単な方法は、このクラスを継承して、自分用の追加チェックの前にオーバーライドした元のメソッドを呼び出すことです:
import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
def set_ok(self, cookie, request):
if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
return False
if i_dont_want_to_store_this_cookie(cookie):
return False
return True
CookiePolicy
インターフェイスを実装するのに必要な機能に加えて、このクラスではクッキーを受けとったり設定したりするドメインを許可したり拒絶したりできるようになっています。ほかにも、 Netscape プロトコルのかなり緩い規則をややきつくするために、いくつかの厳密性のスイッチがついています (いくつかの良性クッキーをブロックする危険性もありますが)。
ドメインのブラックリスト機能やホワイトリスト機能も提供されています (デフォルトではオフになっています)。ブラックリストになく、(ホワイトリスト機能を使用している場合は) ホワイトリストにあるドメインのみがクッキーを設定したり返したりすることを許可されます。コンストラクタの引数 blocked_domains 、および blocked_domains()
と set_blocked_domains()
メソッドを使ってください (allowed_domains に関しても同様の対応する引数とメソッドがあります)。ホワイトリストを設定した場合は、それを None
にすることでホワイトリスト機能をオフにすることができます。
ブラックリストあるいはホワイトリスト中にあるドメインのうち、ドット (.) で始まっていないものは、正確にそれと一致するドメインのクッキーにしか適用されません。たとえばブラックリスト中のエントリ "example.com"
は、"example.com"
にはマッチしますが、"www.example.com"
にはマッチしません。一方ドット (.) で始まっているドメインは、より特化されたドメインともマッチします。たとえば、".example.com"
は、"www.example.com"
と "www.coyote.example.com"
の両方にマッチします (が、"example.com"
自身にはマッチしません)。IP アドレスは例外で、つねに正確に一致する必要があります。たとえば、かりに blocked_domains が "192.168.1.2"
と ".168.1.2"
を含んでいたとして、192.168.1.2 はブロックされますが、193.168.1.2 はブロックされません。
DefaultCookiePolicy
は以下のような追加メソッドを実装しています:
ブロックしているドメインのシーケンスを (タプルとして) 返します。
ブロックするドメインを設定します。
domain がクッキーを授受しないブラックリストに載っているかどうかを返します。
None
あるいは明示的に許可されているドメインを (タプルとして) 返します。
許可するドメイン、あるいは
None
を設定します。
domain がクッキーを授受するホワイトリストに載っているかどうかを返します。
DefaultCookiePolicy
インスタンスは以下の属性をもっています。これらはすべてコンストラクタから同じ名前の引数をつかって初期化することができ、代入してもかまいません。
If true, request that the
CookieJar
instance downgrade RFC 2109 cookies (ie. cookies received in a Set-Cookie header with a version cookie-attribute of 1) to Netscape cookies by setting the version attribute of theCookie
instance to 0. The default value isNone
, in which case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned off. Therefore, RFC 2109 cookies are downgraded by default.
一般的な厳密性のスイッチ:
サイトに、国別コードとトップレベルドメインだけからなるドメイン名 (
.co.uk
,.gov.uk
,.co.nz
など) を設定させないようにします。これは完璧からはほど遠い実装であり、いつもうまくいくとは限りません!
RFC 2965 protocol strictness switches:
Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable transaction is one resulting from a redirect or a request for an image hosted on another site). If this is false, cookies are never blocked on the basis of verifiability
Netscape プロトコルの厳密性に関するスイッチ:
Apply RFC 2965 rules on unverifiable transactions even to Netscape cookies.
Netscape クッキーに対するドメインマッチングの規則をどの程度厳しくするかを指示するフラグです。とりうる値については下の説明を見てください。
Set-Cookie: ヘッダで、
'$'
で始まる名前のクッキーを無視します。
要求した URI にパスがマッチしないクッキーの設定を禁止します。
strict_ns_domain
はいくつかのフラグの集合です。これはいくつかの値を or することで構成します (たとえば DomainStrictNoDots|DomainStrictNonDomain
は両方のフラグが設定されていることになります)。
クッキーを設定するさい、ホスト名のプレフィクスにドットが含まれるのを禁止します (例:
www.foo.bar.com
は.bar.com
のクッキーを設定することはできません、なぜならwww.foo
はドットを含んでいるからです)。
domain
クッキー属性を明示的に指定していないクッキーは、そのクッキーを設定したドメインと同一のドメインだけに返されます (例:example.com
からのクッキーにdomain
クッキー属性がない場合、そのクッキーがspam.example.com
に返されることはありません)。
When setting cookies, require a full RFC 2965 domain-match.
以下の属性は上記のフラグのうちもっともよく使われる組み合わせで、便宜をはかるために提供されています:
0 と同じです (つまり、上述の Netscape のドメイン厳密性フラグがすべてオフにされます)。
DomainStrictNoDots|DomainStrictNonDomain
と同じです。
21.24.5. Cookieオブジェクト¶
Cookie
instances have Python attributes roughly corresponding to the
standard cookie-attributes specified in the various cookie standards. The
correspondence is not one-to-one, because there are complicated rules for
assigning default values, because the max-age
and expires
cookie-attributes contain equivalent information, and because RFC 2109 cookies
may be 'downgraded' by http.cookiejar
from version 1 to version 0 (Netscape)
cookies.
CookiePolicy
メソッド内でのごくわずかな例外を除けば、これらの属性に代入する必要はないはずです。このクラスは内部の一貫性を保つようにはしていないため、代入するのは自分のやっていることを理解している場合のみにしてください。
Integer or
None
. Netscape cookies haveversion
0. RFC 2965 and RFC 2109 cookies have aversion
cookie-attribute of 1. However, note thathttp.cookiejar
may 'downgrade' RFC 2109 cookies to Netscape cookies, in which caseversion
is 0.
クッキーの名前 (文字列)。
クッキーの値 (文字列)、あるいは
None
。
ポートあるいはポートの集合をあらわす文字列 (例: '80' または '80,8080')、あるいは
None
。
クッキーのパス名 (文字列、例:
'/acme/rocket_launchers'
)。
そのクッキーを返せるのがセキュアな接続のみならば
True
を返します。
クッキーの期限が切れる日時をあわらす整数 (エポックから経過した秒数)、あるいは
None
。is_expired()
も参照してください。
これがセッションクッキーであれば
True
を返します。
このクッキーの働きを説明する、サーバからのコメント文字列、あるいは
None
。
このクッキーの働きを説明する、サーバからのコメントのリンク URL、あるいは
None
。
True
if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived in a Set-Cookie header, and the value of the Version cookie-attribute in that header was 1). This attribute is provided becausehttp.cookiejar
may 'downgrade' RFC 2109 cookies to Netscape cookies, in which caseversion
is 0.
サーバがポート、あるいはポートの集合を (Set-Cookie / Set-Cookie2 ヘッダ内で) 明示的に指定していれば
True
を返します。
サーバにより明示的にドメインが指定されていれば
True
を返します。
サーバが明示的に指定したドメインがドット (
'.'
) で始まっていればTrue
を返します。
クッキーは、オプションとして標準的でないクッキー属性を持つこともできます。これらは以下のメソッドでアクセスできます:
そのクッキーが指定された名前のクッキー属性をもっている場合には真を返します。
クッキーが指定された名前のクッキー属性をもっていれば、その値を返します。そうでない場合は default を返します。
指定された名前のクッキー属性を設定します。
Cookie
クラスは以下のメソッドも定義しています:
サーバが要求するクッキーの有効期限を過ぎていれば
True
を返します。 now が (エポックからの経過秒で) 指定されているときは、特定の時刻で期限切れかどうかを判定します。
21.24.6. 使用例¶
The first example shows the most common usage of http.cookiejar
:
import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
以下の例では、URL を開く際に Netscape や Mozilla または Lynx のクッキーを使う方法を示しています (クッキーファイルの位置は Unix/Netscape の慣例にしたがうものと仮定しています):
import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
The next example illustrates the use of DefaultCookiePolicy
. Turn on
RFC 2965 cookies, be more strict about domains when setting and returning
Netscape cookies, and block some domains from setting cookies or having them
returned:
import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
rfc2965=True, strict_ns_domain=Policy.DomainStrict,
blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")