"http.cookiejar" --- Cookie handling for HTTP clients
*****************************************************

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

======================================================================

"http.cookiejar" モジュールは HTTP クッキーの自動処理をおこなうクラス
を定義します。これは小さなデータの断片 -- *クッキー* --  を要求する
web サイトにアクセスする際に有用です。クッキーとは web サーバの HTTP
レスポンスによってクライアントのマシンに設定され、のちの HTTP リクエス
トをおこなうさいにサーバに返されるものです。

標準的な Netscape クッキープロトコルおよび **RFC 2965** で定義されてい
るプロトコルの両方を処理できます。RFC 2965 の処理はデフォルトではオフ
になっています。 **RFC 2109** のクッキーは Netscape クッキーとして解析
され、のちに有効な 'ポリシー' に従って Netscapeまたは RFC 2965 クッキ
ーとして処理されます。但し、インターネット上の大多数のクッキーは
Netscapeクッキーです。 "http.cookiejar" はデファクトスタンダードの
Netscape クッキープロトコル  (これは元々 Netscape が策定した仕様とはか
なり異なっています) に従うようになっており、RFC 2109 で導入された
"max-age" や "port" などのクッキー属性にも注意を払います。

注釈:

  *Set-Cookie* や *Set-Cookie2* ヘッダに現れる多種多様なパラメータの名
  前 ("domain" や "expires" など) は便宜上 *属性* と呼ばれますが、ここ
  では Python の属性と区別するため、かわりに *クッキー属性* と呼ぶこと
  にします。

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

exception http.cookiejar.LoadError

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

   バージョン 3.3 で変更: "LoadError" は以前は "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" インターフェイスを実装するオブジェクトで
   す。これ以外の引数については、該当する属性の説明を参照してください
   。

   "FileCookieJar" はディスク上のファイルからのクッキーの読み込み、も
   しくは書き込みをサポートします。実際には、 "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* (secure websocket) が安全なプロトコルとみなさ
   れます。これ以外の引数については "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" にはいくつかの
   細かいポリシー設定をおこなうパラメータが用意されています。

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* を使いますが、普及してはいません。

  http://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()" あるいは
   それに類似する呼び出しによって得られます) は "info()" メソッドをサ
   ポートしている必要があります。これは "email.message.Message" メソッ
   ドのあるオブジェクトを返すものです。

   *request* オブジェクト (通常は "urllib.request.Request" インスタン
   ス) は "urllib.request" のドキュメントに記されているように、メソッ
   ド "get_full_url()", および属性 "host", "unverifiable",
   "origin_req_host" をサポートしている必要があります。この request は
   そのクッキーの保存が許可されているかを検査するとともに、クッキー属
   性のデフォルト値を設定するのに使われます。

   バージョン 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" クッキー属性が指定
   されているものです)。対話的なブラウザの場合、セッションの終了はふつ
   うブラウザのウィンドウを閉じることに相当します。

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

さらに "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** クッキー (即ち
   *Set-Cookie* ヘッダのクッキー属性 Version の値が 1 のクッキー) を
   Netscapeクッキーへ、 "Cookie" インスタンスの version 属性を 0 に設
   定する事でダウングレードするように要求します。デフォルトの値は
   "None" であり、この場合 RFC 2109 クッキーは **RFC 2965** 処理が無効
   に設定されている場合に限りダウングレードされます。それ故に 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" は ".bar.com" のクッキーを設定
   することはできません、なぜなら "www.foo" はドットを含んでいるからで
   す)。

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" クッキー属性は同じ値をもつことになっているので、また **RFC
2109** クッキーは "http.cookiejar" によって version 1 から version 0
(Netscape) クッキーへ 'ダウングレード' される場合があるため、この対応
は 1 対 1 ではありません。

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

Cookie.version

   整数または "None" 。 Netscape クッキーはバージョン 0 であり、 **RFC
   2965** および **RFC 2109** クッキーはバージョン 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** クッキー (即ち *Set-Cookie* ヘッダにあり、かつクッキー
   属性 Version の値が 1 のクッキー) の場合、 "True" を返します。
   "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/")
