# 22 `cookielib` -- HTTP クライアント用の Cookie 処理

バージョン 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 の属性と区別するため、かわりに クッキー属性 と呼ぶことにします。

このモジュールは以下の例外を定義しています:

exception `LoadError`
  この例外は `FileCookieJar` インスタンスがファイルからクッキーを 読み込むのに失敗した場合に発生します。

以下のクラスが提供されています:

クラス `CookieJar`( | policy=`None`)

  policy は `CookiePolicy` インターフェイスを実装するオブジェクトです。

  `CookieJar` クラスには HTTP クッキーを保管します。 これは HTTP リクエストに応じてクッキーを取り出し、それを HTTP レスポンスの中で返します。必要に応じて、 `CookieJar` インスタンスは保管されているクッキーを 自動的に破棄します。このサブクラスは、クッキーをファイルや データベースに格納したり取り出したりする操作をおこなう役割を負っています。

クラス `FileCookieJar`( | filename, delayload=`None`, policy=`None`)

  policy は `CookiePolicy` インターフェイスを実装するオブジェクトです。 これ以外の引数については、該当する属性の説明を参照してください。

  `FileCookieJar` はディスク上のファイルからのクッキーの読み込み、 もしくは書き込みをサポートします。実際には、`load()` または `revert()` のどちらかのメソッドが呼ばれるまでクッキーは 指定されたファイルからはロードされません。 このクラスのサブクラスは 18.22.2 節で説明します。

クラス `CookiePolicy`( | )

  このクラスは、あるクッキーをサーバから受け入れるべきか、 そしてサーバに返すべきかを決定する役割を負っています。

クラス `DefaultCookiePolicy`( | blocked_domains=`None`, allowed_domains=`None`, netscape=`True`, rfc2965=`False`, rfc2109_as_netscape=`None`, hide_cookie2=`False`, strict_domain=`False`, strict_rfc2965_unverifiable=`True`, strict_ns_unverifiable=`False`, strict_ns_domain=`DefaultCookiePolicy.DomainLiberal`, strict_ns_set_initial_dollar=`False`, strict_ns_set_path=`False` )

  コンストラクタはキーワード引数しか取りません。 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` には いくつかの細かいポリシー設定をおこなうパラメータが用意されています。

クラス `Cookie`( | )

  このクラスは Netscape クッキー、RFC 2109 のクッキー、および RFC 2965 のクッキーを 表現します。`cookielib` のユーザが自分で `Cookie` インスタンスを 作成することは想定されていません。かわりに、必要に応じて `CookieJar` インスタンスの `make_cookies()` を呼ぶことになっています。

参考:

`urllib2`:モジュール
  クッキーの自動処理をおこない URL を開くモジュールです。.

`Cookie`:モジュール
  HTTP のクッキークラスで、基本的にはサーバサイドの コードで有用です。`cookielib` および `Cookie` モジュールは 互いに依存してはいません。.

http://wwwsearch.sf.net/ClientCookie/
  このモジュールの拡張で、 Windows 上の Microsoft Internet Explorer クッキーを読みこむクラスが含まれています。

http://www.netscape.com/newsref/std/cookie_spec.html
  元祖 Netscape の クッキープロトコルの仕様です。今でもこれが主流のプロトコルですが、 現在のメジャーなブラウザ (と `cookielib`) が実装している 「Netscape クッキープロトコル」は `cookie_spec.html` で述べられているものと おおまかにしか似ていません。

RFC 2109, HTTP State Management Mechanism
  RFC 2965 によって過去の遺物になりました。 Set-Cookie: の version=1 で使います。

RFC 2965, HTTP State Management Mechanism
  Netscape プロトコルの バグを修正したものです。 Set-Cookie: のかわりに Set-Cookie2: を使いますが、普及してはいません。

http://kristol.org/cookie/errata.html
  RFC 2965 に対する未完の正誤表です。

RFC 2964, Use of HTTP State Management