"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" は以下のようなメソッドを持っています:

CookieJar.add_cookie_header(request)

   *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()" の説明を参照してください。

CookieJar.set_cookie_if_ok(cookie, request)

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

CookieJar.set_cookie(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" と同じです。


Cookie オブジェクト
===================

"Cookie" インスタンスは、各種クッキー標準で定められた標準クッキー属性
におおむね対応する Python 属性を持ちます。 対応が一対一でないのは、デ
フォルト値の設定規則が複雑なこと、クッキー属性 "max-age" と "expires"
が同等の情報を持つこと、 そして "http.cookiejar" が **RFC 2109** クッ
キーをバージョン 1 からバージョン 0 (Netscape) に「ダウングレード」す
る場合があるためです。

"CookiePolicy" メソッド内でのごくわずかな例外を除けば、これらの属性に
代入する必要はないはずです。このクラスは内部の一貫性を保つようにはして
いないため、代入するのは自分のやっていることを理解している場合のみにし
てください。

Cookie.version

   整数または "None" です。 Netscape クッキーの "version" は 0 です。
   **RFC 2965** クッキーと **RFC 2109** クッキーの "version" クッキー
   属性は 1 です。 ただし "http.cookiejar" が RFC 2109 クッキーを
   Netscape クッキーに「ダウングレード」すると、"version" は 0 になり
   ます。

Cookie.name

   クッキーの名前 (文字列)。

Cookie.value

   クッキーの値 (文字列)、または "None"。

Cookie.port

   ポートまたはポートの集合を表す文字列 (例えば '80' や '80,8080')、ま
   たは "None"。

Cookie.domain

   クッキーのドメイン (文字列) 。

Cookie.path

   クッキーのパス ("'/acme/rocket_launchers'" などの文字列)。

Cookie.secure

   そのクッキーを返せるのがセキュアな接続のみならば "True" です。

Cookie.expires

   エポックからの経過秒数を表す整数で指定する有効期限、または "None"。
   "is_expired()" メソッドも参照してください。

Cookie.discard

   これがセッションクッキーであれば "True" です。

Cookie.comment

   このクッキーの役割を説明するサーバーからのコメント文字列、または
   "None"。

Cookie.comment_url

   このクッキーの役割を説明するサーバーからのコメントへのリンク URL、
   または "None"。

Cookie.rfc2109

   このクッキーを **RFC 2109** クッキーとして受信した場合は "True" で
   す (つまり、クッキーが *Set-Cookie* ヘッダーで届き、そのヘッダーの
   Version クッキー属性の値が 1 の場合です)。 "http.cookiejar" が RFC
   2109 クッキーを Netscape クッキーに「ダウングレード」すると
   "version" が 0 になるため、この属性が用意されています。

Cookie.port_specified

   サーバがポート、あるいはポートの集合を (*Set-Cookie* / *Set-
   Cookie2* ヘッダ内で) 明示的に指定していれば "True" です。

Cookie.domain_specified

   サーバにより明示的にドメインが指定されていれば "True" です。

Cookie.domain_initial_dot

   サーバが明示的に指定したドメインがドット ("'.'") で始まっていれば
   "True" です。

クッキーは、オプションとして標準的でないクッキー属性を持つこともできま
す。これらは以下のメソッドでアクセスできます:

Cookie.has_nonstandard_attr(name)

   そのクッキーが指定された名前のクッキー属性をもっている場合には
   "True" を返します。

Cookie.get_nonstandard_attr(name, default=None)

   クッキーが指定された名前のクッキー属性をもっていれば、その値を返し
   ます。そうでない場合は *default* を返します。

Cookie.set_nonstandard_attr(name, value)

   指定された名前のクッキー属性を設定します。

"Cookie" クラスは以下のメソッドも定義しています:

Cookie.is_expired(now=None)

   サーバが要求するクッキーの有効期限を過ぎていれば "True" を返します
   。 *now* が (エポックからの経過秒で) 指定されているときは、特定の時
   刻で期限切れかどうかを判定します。


使用例
======

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