ノート
cookielib モジュールは、Python 3では http.cookiejar にリネームされました。 2to3 ツールは自動的にソースコード内のimportをPython 3用に修正します。
バージョン 2.4 で追加.
cookielib モジュールは HTTP クッキーの自動処理をおこなうクラスを定義します。これは小さなデータの断片 – クッキー – を要求する web サイトにアクセスする際に有用です。クッキーとは web サーバの HTTP レスポンスによってクライアントのマシンに設定され、のちの HTTP リクエストをおこなうさいにサーバに返されるものです。
標準的な Netscape クッキープロトコルおよび RFC 2965 で定義されているプロトコルの両方を処理できます。RFC 2965 の処理はデフォルトではオフになっています。 RFC 2109 のクッキーは Netscape クッキーとして解析され、のちに有効な ‘ポリシー’ に従って Netscapeまたは RFC 2965 クッキーとして処理されます。但し、インターネット上の大多数のクッキーは Netscapeクッキーです。 cookielib はデファクトスタンダードの Netscape クッキープロトコル (これは元々 Netscape が策定した仕様とはかなり異なっています) に従うようになっており、RFC 2109 で導入された max-age や port などの クッキー属性にも注意を払います。
ノート
Set-Cookie や Set-Cookie2 ヘッダに現れる多種多様なパラメータの名前 (domain や expires など) は便宜上 属性 と呼ばれますが、ここでは Python の属性と区別するため、かわりに クッキー属性 と呼ぶことにします。
このモジュールは以下の例外を定義しています:
この例外は FileCookieJar インスタンスがファイルからクッキーを読み込むのに失敗した場合に発生します。
以下のクラスが提供されています:
policy は CookiePolicy インターフェイスを実装するオブジェクトです。
CookieJar クラスには HTTP クッキーを保管します。これは HTTP リクエストに応じてクッキーを取り出し、それを HTTP レスポンスの中で返します。必要に応じて、 CookieJar インスタンスは保管されているクッキーを 自動的に破棄します。このサブクラスは、クッキーをファイルやデータベースに格納したり取り出したりする操作をおこなう役割を負っています。
policy は CookiePolicy インターフェイスを実装するオブジェクトです。 これ以外の引数については、該当する属性の説明を参照してください。
FileCookieJar はディスク上のファイルからのクッキーの読み込み、 もしくは書き込みをサポートします。実際には、 load() または revert() のどちらかのメソッドが呼ばれるまでクッキーは 指定されたファイルからはロード されません 。このクラスのサブクラスは FileCookieJar のサブクラスと web ブラウザとの連携 節で説明します。
このクラスは、あるクッキーをサーバから受け入れるべきか、そしてサーバに返すべきかを決定する役割を負っています。
コンストラクタはキーワード引数しか取りません。 blocked_domains はドメイン名からなるシーケンスで、ここからは 決してクッキーを受けとらないし、このドメインにクッキーを返すこともありません。 allowed_domains が None でない場合、これはこのドメインのみからクッキーを受けとり、返すという指定になります。これ以外の引数については CookiePolicy および DefaultCookiePolicy オブジェクトの説明をごらんください。
DefaultCookiePolicy は Netscape および RFC 2965 クッキーの標準的な許可 / 拒絶のルールを実装しています。デフォルトでは、RFC 2109 のクッキー (Set-Cookie の version クッキー属性が 1 で受けとられるもの) は RFC 2965 のルールで扱われます。しかし、RFC 2965処理が無効に設定されているか rfc2109_as_netscape が Trueの場合、RFC 2109クッキーは CookieJar インスタンスによって Cookie のインスタンスの version 属性を 0に設定する事で Netscapeクッキーに「ダウングレード」されます。 また DefaultCookiePolicy にはいくつかの細かいポリシー設定をおこなうパラメータが用意されています。
このクラスは Netscape クッキー、RFC 2109 のクッキー、および RFC 2965 のクッキーを表現します。 cookielib のユーザが自分で Cookie インスタンスを作成することは想定されていません。かわりに、必要に応じて CookieJar インスタンスの make_cookies() を呼ぶことになっています。
参考
RFC 2964 - Use of HTTP State Management
CookieJar オブジェクトは保管されている Cookie オブジェクトを ひとつずつ取り出すための、イテレータ(iterator)・プロトコルをサポートしています。
CookieJar は以下のようなメソッドを持っています:
request に正しい Cookie ヘッダを追加します。
ポリシーが許すようであれば (CookieJar の CookiePolicy インスタンスにある 属性のうち、 rfc2965 および hide_cookie2 がそれぞれ真と偽であるような場合)、必要に応じて Cookie2 ヘッダも追加されます。
request オブジェクト (通常は urllib2.Request インスタンス) は、 urllib2 のドキュメントに記されているように、 get_full_url(), get_host(), get_type(), unverifiable(), get_origin_req_host(), has_header(), get_header(), header_items() および add_unredirected_header() の各メソッドをサポートしている必要があります。
HTTP response からクッキーを取り出し、ポリシーによって許可されていればこれを CookieJar 内に保管します。
CookieJar は response 引数の中から許可されている Set-Cookie および Set-Cookie2 ヘッダを探しだし、適切に (CookiePolicy.set_ok() メソッドの承認におうじて) クッキーを保管します。
response オブジェクト (通常は urllib2.urlopen() あるいはそれに類似する呼び出しによって得られます) は info() メソッドをサポートしている必要があります。これは getallmatchingheaders() メソッドのある オブジェクト (通常は mimetools.Message インスタンス) を返すものです。
request オブジェクト (通常は urllib2.Request インスタンス) は urllib2 のドキュメントに記されているように、 get_full_url(), get_host(), unverifiable() および get_origin_req_host() の各メソッドをサポートしている必要があります。この request はそのクッキーの保存が許可されているかを検査するとともに、クッキー属性のデフォルト値を設定するのに使われます。
使用する 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() と同じです。
名前のついたファイルはこのクラスがわかるやり方で指定する必要があります。さもないと LoadError が発生します。 さらに、例えばファイルが存在しないような時に IOError が発生する場合があります。
FileCookieJar インスタンスは以下のような公開の属性をもっています:
クッキーを保存するデフォルトのファイル名を指定します。この属性には代入することができます。
真であれば、クッキーを読み込むさいにディスクから遅延読み込み (lazy) します。この属性には代入することができません。この情報は単なるヒントであり、 (ディスク上のクッキーが変わらない限りは) インスタンスのふるまいには影響を与えず、パフォーマンスのみに影響します。 CookieJar オブジェクトはこの値を無視することもあります。標準ライブラリに含まれている FileCookieJar クラスで遅延読み込みを おこなうものはありません。
クッキーの読み書きのために、以下の CookieJar サブクラスが提供されています。これ以外の CookieJar サブクラスは、Microsoft Internet Explorer ブラウザのクッキーを読みこむものも含め、 http://wwwsearch.sf.net/ClientCookie/ から使用可能です。
Mozilla の cookies.txt ファイル形式 (この形式はまた Lynx と Netscape ブラウザによっても使われています) でディスクにクッキーを読み書きするための FileCookieJar です。
ノート
Firefox 3 は、 cookie を cookies.txt ファイルフォーマットで保存しません。
ノート
このクラスは RFC 2965 クッキーに関する情報を失います。また、より新しいか、標準でない port などの クッキー属性についての情報も失います。
警告
もしクッキーの損失や欠損が望ましくない場合は、クッキーを保存する前にバックアップを取っておくようにしてください (ファイルへの読み込み / 保存をくり返すと微妙な変化が生じる場合があります)。
また、 Mozilla の起動中にクッキーを保存すると、 Mozilla によって内容が破壊されてしまうことにも注意してください。
libwww-perl のライブラリである Set-Cookie3 ファイル形式でディスクにクッキーを読み書きするための FileCookieJar です。これはクッキーを人間に可読な形式で保存するのに向いています。
CookiePolicy インターフェイスを実装するオブジェクトは以下のようなメソッドを持っています:
クッキーがサーバから受け入れられるべきかどうかを表わす boolean 値を返します。
cookie は cookielib.Cookie インスタンスです。 request は CookieJar.extract_cookies() の説明で定義されているインターフェイスを実装するオブジェクトです。
クッキーがサーバに返されるべきかどうかを表わす boolean 値を返します。
cookie は cookielib.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 プロトコルを実装していることを示します。
RFC 2965 プロトコルを実装していることを示します。
Cookie2 ヘッダをリクエストに含めないようにします (このヘッダが存在する場合、私たちは RFC 2965 クッキーを理解するということをサーバに示すことになります)。
もっとも有用な方法は、 DefaultCookiePolicy をサブクラス化した CookiePolicy クラスを定義して、いくつか (あるいはすべて) のメソッドをオーバーライドすることでしょう。 CookiePolicy 自体は どのようなクッキーも受け入れて設定を許可する「ポリシー無し」ポリシーとして使うこともできます (これが役に立つことはあまりありませんが)。
クッキーを受けつけ、またそれを返す際の標準的なルールを実装します。
RFC 2965 クッキーと Netscape クッキーの両方に対応しています。デフォルトでは、RFC 2965 の処理はオフになっています。
自分のポリシーを提供するいちばん簡単な方法は、このクラスを継承して、自分用の追加チェックの前にオーバーライドした元のメソッドを呼び出すことです:
import cookielib
class MyCookiePolicy(cookielib.DefaultCookiePolicy):
def set_ok(self, cookie, request):
if not cookielib.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 インスタンスは以下の属性をもっています。 これらはすべてコンストラクタから同じ名前の引数をつかって初期化することができ、代入してもかまいません。
Trueの場合、 CookieJar のインスタンスに RFC 2109 クッキー (即ち Set-Cookie ヘッダのVersion cookie属性の値が1のクッキー)を Netscapeクッキーへ、 Cookie インスタンスのversion属性を0に設定する事で ダウングレードするように要求します。デフォルトの値は None であり、この場合 RFC 2109 クッキーは RFC 2965 処理が無効に設定されている場合に限りダウングレードされます。それ故に RFC 2109 クッキーはデフォルトではダウングレードされます。
バージョン 2.5 で追加.
一般的な厳密性のスイッチ:
サイトに、国別コードとトップレベルドメインだけからなるドメイン名 (.co.uk, .gov.uk, .co.nz など) を設定させないようにします。これは完璧からはほど遠い実装であり、いつもうまくいくとは限りません!
RFC 2965 プロトコルの厳密性に関するスイッチ:
検証不可能なトランザクション (通常これはリダイレクトか、別のサイトがホスティングしているイメージの読み込み要求です) に関する RFC 2965 の規則に従います。この値が偽の場合、検証可能性を基準にしてクッキーがブロックされることは 決して ありません。
Netscape プロトコルの厳密性に関するスイッチ:
検証不可能なトランザクションに関する RFC 2965 の規則を Netscape クッキーに対しても適用します。
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 に返されることはありません)。
クッキーを設定するさい、RFC 2965 の完全ドメインマッチングを要求します。
以下の属性は上記のフラグのうちもっともよく使われる組み合わせで、便宜をはかるために提供されています。
0 と同じです (つまり、上述の Netscape のドメイン厳密性フラグがすべてオフにされます)。
DomainStrictNoDots|DomainStrictNonDomain と同じです。
Cookie インスタンスは、さまざまなクッキーの標準で規定されている標準的なクッキー属性とおおまかに対応する Python 属性をもっています。しかしデフォルト値を決める複雑なやり方が存在しており、また max-age および expires クッキー属性は 同じ値をもつことになっているので、また RFC 2109クッキーは cookielib によって version 1から version 0 (Netscape)クッキーへ ‘ダウングレード’ される場合があるため、この対応は 1対 1 ではありません。
CookiePolicy メソッド内でのごくわずかな例外を除けば、これらの属性に代入する必要はないはずです。このクラスは 内部の一貫性を保つようにはしていないため、代入するのは自分のやっていることを理解している場合のみにしてください。
整数または None 。 Netscape クッキーはバージョン 0 であり、 RFC 2965 および RFC 2109 クッキーは バージョン 1 です。しかし、 cookielib は RFC 2109クッキーを Netscapeクッキー (version が 0)に’ダウングレード’する場合がある事に注意して下さい。
クッキーの名前 (文字列)。
クッキーの値 (文字列)、あるいは None 。
ポートあるいはポートの集合をあらわす文字列 (例: ‘80’ または ‘80,8080’)、あるいは None 。
クッキーのパス名 (文字列、例: '/acme/rocket_launchers')。
そのクッキーを返せるのが安全な接続のみならば真を返します。
クッキーの期限が切れる日時をあわらす整数 (エポックから経過した秒数)、あるいは None 。 is_expired() も参照してください。
これがセッションクッキーであれば真を返します。
このクッキーの働きを説明する、サーバからのコメント文字列、あるいは None 。
このクッキーの働きを説明する、サーバからのコメントのリンク URL、あるいは None 。
RFC 2109クッキー(即ち Set-Cookie ヘッダにあり、かつVersion cookie属性の値が1のクッキー)の場合、Trueを返します。 cookielib が RFC 2109クッキーを Netscapeクッキー (version が 0)に’ダウングレード’する場合があるので、この属性が提供されています。
バージョン 2.5 で追加.
サーバがポート、あるいはポートの集合を (Set-Cookie / Set-Cookie2 ヘッダ内で) 明示的に指定していれば真を返します。
サーバがドメインを明示的に指定していれば真を返します。
サーバが明示的に指定したドメインが、ドット ('.') で始まっていれば真を返します。
クッキーは、オプションとして標準的でないクッキー属性を持つこともできます。これらは以下のメソッドでアクセスできます:
そのクッキーが指定された名前のクッキー属性をもっている場合には真を返します。
クッキーが指定された名前のクッキー属性をもっていれば、その値を返します。そうでない場合は default を返します。
指定された名前のクッキー属性を設定します。
Cookie クラスは以下のメソッドも定義しています:
サーバが指定した、クッキーの期限が切れるべき時が過ぎていれば真を返します。 now が指定されているときは (エポックから経過した秒数です)、 そのクッキーが指定された時間において期限切れになっているかどうかを判定します。
はじめに、もっとも一般的な cookielib の使用例をあげます:
import cookielib, urllib2
cj = cookielib.CookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
以下の例では、 URL を開く際に Netscape や Mozilla または Lynx のクッキーを使う方法を示しています (クッキーファイルの位置は Unix/Netscape の慣例にしたがうものと仮定しています):
import os, cookielib, urllib2
cj = cookielib.MozillaCookieJar()
cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
つぎの例は DefaultCookiePolicy の使用例です。 RFC 2965 クッキーをオンにし、Netscape クッキーを設定したり返したりするドメインに対してより厳密な規則を適用します。そしていくつかのドメインから クッキーを設定あるいは返還するのをブロックしています:
import urllib2
from cookielib import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
rfc2965=True, strict_ns_domain=DefaultCookiePolicy.DomainStrict,
blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")