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

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

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

add_cookie_header( request)
request に正しい Cookie: ヘッダを追加します。

ポリシーが許すようであれば (CookieJarCookiePolicy インスタンスにある 属性のうち、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 内に保管します。

CookieJarresponse 引数の中から 許可されている 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.filenameNone の場合は ValueError が発生します。

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

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

load( filename=None, ignore_discard=False, ignore_expires=False)
ファイルからクッキーを読み込みます。

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

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

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

revert( filename=None, ignore_discard=False, ignore_expires=False)
すべてのクッキーを破棄し、保存されているファイルから読み込み直します。

revert()load() と同じ例外を発生させる事ができます。 失敗した場合、オブジェクトの状態は変更されません。

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

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

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

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