http.cookiejar --- HTTP クライアント用の Cookie 処理

ソースコード: Lib/http/cookiejar.py

http.cookiejar モジュールは、HTTP クッキーを自動で扱うクラスを定義しています。 ウェブサーバーからの HTTP レスポンスで小さなデータ (クッキー) をクライアントのマシンに設定し、 後続の HTTP リクエストでサーバーに送り返す必要のあるウェブサイトへのアクセスに役立ちます。

通常の Netscape クッキープロトコルと、RFC 2965 で定義されたプロトコルの両方を扱います。 RFC 2965 の処理はデフォルトでは無効です。 RFC 2109 のクッキーは Netscape クッキーとして解析し、その後は有効な「ポリシー」に従って Netscape クッキーまたは RFC 2965 クッキーとして扱います。 インターネット上のクッキーの大半は Netscape クッキーです。 http.cookiejar は、RFC 2965 で導入されたクッキー属性 max-age と port も考慮しながら、 事実上の標準となっている Netscape クッキープロトコル (当初の Netscape の仕様とは大きく異なります) に従おうとします。

注釈

Set-Cookie ヘッダーと Set-Cookie2 ヘッダーに含まれるさまざまな名前付きパラメータ (domain や expires など) は、慣例として 属性 と呼ばれます。 このモジュールのドキュメントでは、Python の属性と区別するために クッキー属性 という用語を使います。

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

exception http.cookiejar.LoadError

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

バージョン 3.3 で変更: LoadError は以前は IOError のサブタイプでした。 現在、IOError は OSError のエイリアスです。

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

class http.cookiejar.CookieJar(policy=None)

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

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

class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)

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

ディスク上のファイルからクッキーを読み込める CookieJar で、ファイルへの保存も可能な場合があります。 load() または revert() メソッドを呼び出すまで、指定されたファイルからクッキーは読み込まれ ません。 このクラスのサブクラスについては FileCookieJar のサブクラスと web ブラウザとの連携 を参照してください。

これは直接初期化されるべきではありません。以下のサブクラスを代わりに使用してください。

バージョン 3.8 で変更: filename 引数が path-like object を受け付けるようになりました。

class http.cookiejar.CookiePolicy

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

class http.cookiejar.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, secure_protocols=('https', 'wss'))

コンストラクタの引数はキーワード引数としてだけ渡してください。 blocked_domains は、クッキーを受け入れることも返すこともしないドメイン名のシーケンスです。 allowed_domains が None でない場合は、クッキーの受け入れと返送を許可するドメインだけを含むシーケンスです。 secure_protocols は、セキュアなクッキーを追加できるプロトコルのシーケンスです。 デフォルトでは https と wss (セキュアな WebSocket) をセキュアなプロトコルとみなします。 その他の引数については、CookiePolicy オブジェクトと DefaultCookiePolicy オブジェクトのドキュメントを参照してください。

DefaultCookiePolicy は、Netscape クッキーと RFC 2965 クッキーを受け入れるか拒否するかについての標準的な規則を実装しています。 デフォルトでは、RFC 2109 クッキー (version クッキー属性が 1 の Set-Cookie ヘッダーで受信したクッキー) を RFC 2965 の規則に従って扱います。 ただし、RFC 2965 の処理を無効にしている場合や rfc2109_as_netscape が True の場合、 CookieJar インスタンスは Cookie インスタンスの version 属性を 0 に設定し、RFC 2109 クッキーを Netscape クッキーに「ダウングレード」します。 DefaultCookiePolicy は、ポリシーを細かく調整するためのパラメータも提供します。

class http.cookiejar.Cookie

このクラスは Netscape、RFC 2109、RFC 2965 のクッキーを表します。 http.cookiejar の利用者が Cookie インスタンスを直接作成することは想定していません。 必要であれば、代わりに CookieJar インスタンスの make_cookies() を呼び出してください。

参考

urllib.request モジュール

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

http.cookies モジュール

主にサーバー側のコードで役立つ HTTP クッキーのクラスです。 http.cookiejar モジュールと http.cookies モジュールは互いに依存していません。

https://curl.se/rfc/cookie_spec.html

当初の Netscape クッキープロトコルの仕様です。 今も主流のプロトコルではありますが、主要なブラウザーすべて (および http.cookiejar) が実装する「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 を使いますが、普及してはいません。

https://kristol.org/cookie/errata.html

RFC 2965 に対する未完の正誤表です。

RFC 2964 - Use of HTTP State Management

CookieJar オブジェクトと FileCookieJar オブジェクト

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

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

request に正しい Cookie ヘッダを追加します。

ポリシーで許可している場合 (つまり CookieJar の CookiePolicy インスタンスの rfc2965 属性が真、hide_cookie2 属性が偽の場合) は、 必要に応じて Cookie2 ヘッダーも追加します。

request オブジェクト (通常は urllib.request.Request インスタンス) は、urllib.request で記述されているメソッド get_full_url()、has_header()、get_header()、 header_items()、add_unredirected_header() と、 属性 host、type、unverifiable、origin_req_host をサポートしなければなりません。

バージョン 3.3 で変更: request オブジェクトに origin_req_host 属性が必要になりました。 非推奨のメソッド get_origin_req_host() への依存を取り除きました。

CookieJar.extract_cookies(response, request)

HTTP response からクッキーを取り出し、ポリシーによって許可されていればこれを CookieJar 内に保管します。

CookieJar は response 引数の中から許可されている Set-Cookie および Set-Cookie2 ヘッダを探しだし、適切に (CookiePolicy.set_ok() メソッドの承認におうじて) クッキーを保管します。

response オブジェクト (通常は urllib.request.urlopen() などの呼び出しの結果) は、 email.message.Message インスタンスを返す info() メソッドをサポートしなければなりません。

request オブジェクト (通常は urllib.request.Request インスタンス) は、urllib.request で記述されている get_full_url() メソッドと、属性 host、unverifiable、origin_req_host をサポートしなければなりません。 リクエストは、クッキーの設定が許可されているかを確認するだけでなく、クッキー属性のデフォルト値を設定するためにも使います。

バージョン 3.3 で変更: request オブジェクトに origin_req_host 属性が必要になりました。 非推奨のメソッド get_origin_req_host() への依存を取り除きました。

CookieJar.set_policy(policy)

使用する CookiePolicy インスタンスを指定します。

CookieJar.make_cookies(response, request)

response オブジェクトから得られた Cookie オブジェクトからなるシーケンスを返します。

response および request 引数で要求されるインターフェイスについては、 extract_cookies() の説明を参照してください。

ポリシーが許すのであれば、与えられた Cookie を設定します。

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

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

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

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

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

CookieJar.clear_session_cookies()

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

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

save() メソッドは、ignore_discard 引数に真を渡して指示しない限り、いずれにせよセッションクッキーを保存しません。

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

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() メソッドを使って復元することができます。

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

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

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

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

指定されたファイルは、このクラスが理解できる形式でなければなりません。 そうでなければ LoadError が送出されます。 さらに、例えばファイルが存在しない場合などには OSError が送出されることがあります。

バージョン 3.3 で変更: 以前は IOError が送出されました; それは現在 OSError のエイリアスです。

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

すべてのクッキーを破棄し、保存されているファイルから読み込み直します。

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

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

FileCookieJar.filename

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

FileCookieJar.delayload

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

FileCookieJar のサブクラスと web ブラウザとの連携

クッキーの読み書きのために、以下の CookieJar サブクラスが提供されています。

class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)

Mozilla の cookies.txt ファイル形式 (この形式はまた curl や Lynx と Netscape ブラウザによっても使われています) でディスクにクッキーを読み書きするための FileCookieJar です。

注釈

このクラスは RFC 2965 クッキーに関する情報を失います。また、より新しいか、標準でない port などのクッキー属性についての情報も失います。

警告

もしクッキーの損失や欠損が望ましくない場合は、クッキーを保存する前にバックアップを取っておくようにしてください (ファイルへの読み込み / 保存をくり返すと微妙な変化が生じる場合があります)。

また、Mozilla の起動中にクッキーを保存すると、Mozilla によって内容が破壊されてしまうことにも注意してください。

class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)

libwww-perl ライブラリの Set-Cookie3 ファイル形式と互換性のある形式で、ディスクからクッキーを読み込み、ディスクへ保存できる FileCookieJar です。 人間が読めるファイルにクッキーを保存したい場合に便利です。

バージョン 3.8 で変更: filename 引数が path-like object を受け付けるようになりました。

CookiePolicy オブジェクト

CookiePolicy インターフェイスを実装するオブジェクトは以下のようなメソッドを持っています:

CookiePolicy.set_ok(cookie, request)

クッキーがサーバから受け入れられるべきかどうかを表わす boolean 値を返します。

cookie は Cookie インスタンスです。 request は CookieJar.extract_cookies() の説明で定義されているインターフェイスを実装するオブジェクトです。

CookiePolicy.return_ok(cookie, request)

クッキーがサーバに返されるべきかどうかを表わす boolean 値を返します。

cookie は Cookie インスタンスです。 request は CookieJar.add_cookie_header() の説明で定義されているインターフェイスを実装するオブジェクトです。

CookiePolicy.domain_return_ok(domain, request)

与えられたクッキーのドメインに対して、そこにクッキーを返すべきでない場合には 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() で説明されているとおりです。

CookiePolicy.path_return_ok(path, request)

与えられたクッキーのパス名に対して、そこにクッキーを返すべきでない場合には False を返します。

domain_return_ok() の説明を参照してください。

上のメソッドの実装にくわえて、 CookiePolicy インターフェイスの実装では以下の属性を設定する必要があります。これはどのプロトコルがどのように使われるべきかを示すもので、これらの属性にはすべて代入することが許されています。

CookiePolicy.netscape

Netscape プロトコルを実装していることを示します。

CookiePolicy.rfc2965

RFC 2965 プロトコルを実装していることを示します。

CookiePolicy.hide_cookie2

Cookie2 ヘッダをリクエストに含めないようにします (このヘッダが存在する場合、私たちは RFC 2965 クッキーを理解するということをサーバに示すことになります)。

もっとも有用な方法は、 DefaultCookiePolicy をサブクラス化した CookiePolicy クラスを定義して、いくつか (あるいはすべて) のメソッドをオーバーライドすることでしょう。 CookiePolicy 自体はどのようなクッキーも受け入れて設定を許可する「ポリシー無し」ポリシーとして使うこともできます (これが役に立つことはあまりありませんが)。

DefaultCookiePolicy オブジェクト

クッキーを受けつけ、またそれを返す際の標準的なルールを実装します。

RFC 2965 クッキーと Netscape クッキーの両方に対応しています。デフォルトでは、RFC 2965 の処理はオフになっています。

自分のポリシーを提供するいちばん簡単な方法は、このクラスを継承して、自分用の追加チェックの前にオーバーライドした元のメソッドを呼び出すことです:

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 は以下のような追加メソッドを実装しています:

DefaultCookiePolicy.blocked_domains()

ブロックしているドメインのシーケンスを (タプルとして) 返します。

DefaultCookiePolicy.set_blocked_domains(blocked_domains)

ブロックするドメインを設定します。

DefaultCookiePolicy.is_blocked(domain)

domain がクッキーを授受しない拒否リストに載っていれば True を返します。

DefaultCookiePolicy.allowed_domains()

None、または許可したドメインのシーケンスをタプルとして返します。

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

許可するドメインのシーケンス、または None を設定します。

DefaultCookiePolicy.is_not_allowed(domain)

domain がクッキーを授受する許可リストに載っていなければ True を返します。

DefaultCookiePolicy インスタンスは以下の属性をもっています。これらはすべてコンストラクタから同じ名前の引数をつかって初期化することができ、代入してもかまいません。

DefaultCookiePolicy.rfc2109_as_netscape

真の場合、CookieJar インスタンスに対し、RFC 2109 クッキー (version クッキー属性が 1 の Set-Cookie ヘッダーで受信したクッキー) を、 Cookie インスタンスの version 属性を 0 に設定して Netscape クッキーにダウングレードするよう指示します。 デフォルト値は None で、この場合は RFC 2965 の処理が無効なときだけ RFC 2109 クッキーをダウングレードします。 したがって、デフォルトでは RFC 2109 クッキーはダウングレードされます。

一般的な厳密性のスイッチ:

DefaultCookiePolicy.strict_domain

サイトに、国別コードとトップレベルドメインだけからなるドメイン名 (.co.uk, .gov.uk, .co.nz など) を設定させないようにします。これは完璧からはほど遠い実装であり、いつもうまくいくとは限りません!

RFC 2965 プロトコルの厳密性に関するスイッチ:

DefaultCookiePolicy.strict_rfc2965_unverifiable

検証不可能なトランザクション (通常これはリダイレクトか、別のサイトがホスティングしているイメージの読み込み要求です) に関する RFC 2965 の規則に従います。この値が偽の場合、検証可能性を基準にしてクッキーがブロックされることは 決して ありません

Netscape プロトコルの厳密性に関するスイッチ:

DefaultCookiePolicy.strict_ns_unverifiable

検証不可能なトランザクションに関する RFC 2965 の規則を Netscape クッキーに対しても適用します。

DefaultCookiePolicy.strict_ns_domain

Netscape クッキーに対するドメインマッチングの規則をどの程度厳しくするかを指示するフラグです。とりうる値については下の説明を見てください。

DefaultCookiePolicy.strict_ns_set_initial_dollar

Set-Cookie: ヘッダで、'$' で始まる名前のクッキーを無視します。

DefaultCookiePolicy.strict_ns_set_path

要求した URI にパスがマッチしないクッキーの設定を禁止します。

strict_ns_domain はフラグの集まりです。 値はビットごとの OR で組み合わせて作ります (例えば DomainStrictNoDots|DomainStrictNonDomain は両方のフラグが設定されていることを表します)。

DefaultCookiePolicy.DomainStrictNoDots

クッキーを設定するときに、「ホスト接頭辞」にドットを含めることを禁止します (例えば www.foo.bar.com は、www.foo にドットが含まれるため、.bar.com のクッキーを設定できません)。

DefaultCookiePolicy.DomainStrictNonDomain

domain クッキー属性を明示的に指定していないクッキーは、そのクッキーを設定したドメインと同じドメインにだけ返せます (例えば example.com が設定した domain クッキー属性のないクッキーは、spam.example.com には返されません)。

DefaultCookiePolicy.DomainRFC2965Match

クッキーを設定するさい、 RFC 2965 の完全ドメインマッチングを要求します。

以下の属性は上記のフラグのうちもっともよく使われる組み合わせで、便宜をはかるために提供されています:

DefaultCookiePolicy.DomainLiberal

0 と同等です (上に挙げた Netscape ドメインの厳密性フラグをすべて無効にします)。

DefaultCookiePolicy.DomainStrict

DomainStrictNoDots|DomainStrictNonDomain と同じです。

使用例

最初の例は、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/")

つぎの例は DefaultCookiePolicy の使用例です。 RFC 2965 クッキーをオンにし、Netscape クッキーを設定したり返したりするドメインに対してより厳密な規則を適用します。そしていくつかのドメインからクッキーを設定あるいは返還するのをブロックしています:

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/")