18.22.1 CookieJar および FileCookieJar オブジェクト

CookieJar オブジェクトは保管されている Cookie オブジェクトをひとつずつ取り出すための、イテレータ・プロトコルをサポートしています。

CookieJar は以下のようなメソッドを持っています:

add_cookie_header( request)

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() の各メソッドをサポートしている必要があります。

extract_cookies( response, request)

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 はそのクッキーの保存が許可されているかを検査するとともに、クッキー属性のデフォルト値を設定するのに使われます。

set_policy( policy): 使用する CookiePolicy インスタンスを指定します。

make_cookies( response, request): response オブジェクトから得られた Cookie オブジェクトからなるシーケンスを返します。
response および request 引数で要求されるインスタンスについては、 extract_cookies の説明を参照してください。

set_cookie_if_ok( cookie, request): ポリシーが許すのであれば、与えられた Cookie を設定します。

set_cookie( cookie): 与えられた Cookie を、それが設定されるべきかどうかのポリシーのチェックを行わずに設定します。

clear( [domain[, path[, name]]])

いくつかのクッキーを消去します。

引数なしで呼ばれた場合は、すべてのクッキーを消去します。引数がひとつ与えられた場合、その domain に属するクッキーのみを消去します。ふたつの引数が与えられた場合、指定された domain と URL path に属するクッキーのみを消去します。引数が 3つ与えられた場合、 domain, path および name で指定されるクッキーが消去されます。

与えられた条件に一致するクッキーがない場合は KeyError を発生させます。

clear_session_cookies( )

すべてのセッションクッキーを消去します。

保存されているクッキーのうち、discard 属性が真になっているものすべてを消去します (通常これは max-age または expires のどちらのクッキー属性もないか、あるいは明示的に discard クッキー属性が指定されているものです)。対話的なブラウザの場合、セッションの終了はふつうブラウザのウィンドウを閉じることに相当します。

注意: ignore_discard 引数に真を指定しないかぎり、 save() メソッドはセッションクッキーは保存しません。

さらに FileCookieJar は以下のようなメソッドを実装しています:

save( filename=None, ignore_discard=False, ignore_expires=False)

クッキーをファイルに保存します。

この基底クラスは NotImplementedError を発生させます。サブクラスはこのメソッドを実装しないままにしておいてもかまいません。

filename はクッキーを保存するファイルの名前です。 filename が指定されない場合、 self.filename が使用されます (このデフォルト値は、それが存在する場合は、コンストラクタに渡されています)。 self.filename も None の場合は ValueError が発生します。

ignore_discard: 破棄されるよう指示されていたクッキーでも保存します。 ignore_expires: 期限の切れたクッキーでも保存します。

ここで指定されたファイルがもしすでに存在する場合は上書きされるため、以前にあったクッキーはすべて消去されます。保存したクッキーはあとで load() または revert() メソッドを使って復元することができます。

load( filename=None, ignore_discard=False, ignore_expires=False)

ファイルからクッキーを読み込みます。

それまでのクッキーは新しいものに上書きされない限り残ります。

ここでの引数の値は save() と同じです。

名前のついたファイルはこのクラスがわかるやり方で指定する必要があります。さもないと LoadError が発生します。さらに、例えばファイルが存在しないような時に IOError が発生する場合があります。 注意: (IOErrorを発行する)Python 2.4との後方互換性のために、LoadErrorは IOErrorのサブクラスです。

revert( filename=None, ignore_discard=False, ignore_expires=False): すべてのクッキーを破棄し、保存されているファイルから読み込み直します。
revert() は load() と同じ例外を発生させる事ができます。失敗した場合、オブジェクトの状態は変更されません。

FileCookieJar インスタンスは以下のような公開の属性をもっています:

filename: クッキーを保存するデフォルトのファイル名を指定します。この属性には代入することができます。

delayload: 真であれば、クッキーを読み込むさいにディスクから遅延読み込み (lazy) します。この属性には代入することができません。この情報は単なるヒントであり、 (ディスク上のクッキーが変わらない限りは) インスタンスのふるまいには影響を与えず、パフォーマンスのみに影響します。CookieJar オブジェクトはこの値を無視することもあります。標準ライブラリに含まれている FileCookieJar クラスで遅延読み込みをおこなうものはありません。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。