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

**ソースコード:** 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 was made a subclass of "OSError"
   instead of "IOError".

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

class http.cookiejar.CookieJar(policy=None)

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

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

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

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

   "FileCookieJar" はディスク上のファイルからのクッキーの読み込み、も
   しくは書き込みをサポートします。実際には、 "load()" または
   "revert()" のどちらかのメソッドが呼ばれるまでクッキーは指定されたフ
   ァイルからはロード **されません** 。このクラスのサブクラスは
   FileCookieJar のサブクラスと web ブラウザとの連携 節で説明します。

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)

   コンストラクタはキーワード引数しか取りません。 *blocked_domains* は
   ドメイン名からなるシーケンスで、ここからは決してクッキーを受けとら
   ないし、このドメインにクッキーを返すこともありません。
   *allowed_domains* が "None" でない場合、これはこのドメインのみから
   クッキーを受けとり、返すという指定になります。これ以外の引数につい
   ては "CookiePolicy" および "DefaultCookiePolicy" オブジェクトの説明
   をごらんください。

   "DefaultCookiePolicy" implements the standard accept / reject rules
   for Netscape and **RFC 2965** cookies.  By default, **RFC 2109**
   cookies (ie. cookies received in a *Set-Cookie* header with a
   version cookie-attribute of 1) are treated according to the RFC
   2965 rules.  However, if RFC 2965 handling is turned off or
   "rfc2109_as_netscape" is "True", RFC 2109 cookies are 'downgraded'
   by the "CookieJar" instance to Netscape cookies, by setting the
   "version" attribute of the "Cookie" instance to 0.
   "DefaultCookiePolicy" also provides some parameters to allow some
   fine-tuning of policy.

class http.cookiejar.Cookie

   This class represents Netscape, **RFC 2109** and **RFC 2965**
   cookies.  It is not expected that users of "http.cookiejar"
   construct their own "Cookie" instances.  Instead, if necessary,
   call "make_cookies()" on a "CookieJar" instance.

参考:

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

  "http.cookies" モジュール
     HTTP のクッキークラスで、基本的にはサーバサイドのコードで有用です
     。 "http.cookiejar" および "http.cookies" モジュールは互いに依存
     してはいません。

  https://curl.haxx.se/rfc/cookie_spec.html
     元祖 Netscape のクッキープロトコルの仕様です。今でもこれが主流の
     プロトコルですが、現在のメジャーなブラウザ (と "http.cookiejar")
     が実装している「Netscape クッキープロトコル」は
     "cookie_spec.html" で述べられているものとおおまかにしか似ていませ
     ん。

  **RFC 2109** - HTTP State Management Mechanism
     Obsoleted by **RFC 2965**. Uses *Set-Cookie* with version=1.

  **RFC 2965** - HTTP State Management Mechanism
     Netscape プロトコルのバグを修正したものです。 *Set-Cookie* のかわ
     りに *Set-Cookie2* を使いますが、普及してはいません。

  http://kristol.org/cookie/errata.html
     Unfinished errata to **RFC 2965**.

  **RFC 2964** - Use of HTTP State Management


21.24.1. CookieJar および FileCookieJar オブジェクト
====================================================

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

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

CookieJar.add_cookie_header(request)

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

   ポリシーが許すようであれば ("CookieJar" の "CookiePolicy" インスタ
   ンスにある属性のうち、 "rfc2965" および "hide_cookie2" がそれぞれ真
   と偽であるような場合)、必要に応じて *Cookie2* ヘッダも追加されます
   。

   The *request* object (usually a "urllib.request..Request" instance)
   must support the methods "get_full_url()", "get_host()",
   "get_type()", "unverifiable()", "has_header()", "get_header()",
   "header_items()", "add_unredirected_header()" and "origin_req_host"
   attribute as documented by "urllib.request".

   バージョン 3.3 で変更: *request* object needs "origin_req_host"
   attribute. Dependency on a deprecated method
   "get_origin_req_host()" has been removed.

CookieJar.extract_cookies(response, request)

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

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

   The *response* object (usually the result of a call to
   "urllib.request.urlopen()", or similar) should support an "info()"
   method, which returns an "email.message.Message" instance.

   The *request* object (usually a "urllib.request.Request" instance)
   must support the methods "get_full_url()", "get_host()",
   "unverifiable()", and "origin_req_host" attribute, as documented by
   "urllib.request".  The request is used to set default values for
   cookie-attributes as well as for checking that the cookie is
   allowed to be set.

   バージョン 3.3 で変更: *request* object needs "origin_req_host"
   attribute. Dependency on a deprecated method
   "get_origin_req_host()" has been removed.

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

   The named file must be in the format understood by the class, or
   "LoadError" will be raised.  Also, "OSError" may be raised, for
   example if the file does not exist.

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

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

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

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

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

FileCookieJar.filename

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

FileCookieJar.delayload

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


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

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

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

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

   注釈:

     This loses information about **RFC 2965** cookies, and also about
     newer or non-standard cookie-attributes such as "port".

   警告:

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

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

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

   libwww-perl のライブラリである "Set-Cookie3" ファイル形式でディスク
   にクッキーを読み書きするための "FileCookieJar" です。これはクッキー
   を人間に可読な形式で保存するのに向いています。


21.24.3. 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

   Implement **RFC 2965** protocol.

CookiePolicy.hide_cookie2

   Don't add *Cookie2* header to requests (the presence of this header
   indicates to the server that we understand **RFC 2965** cookies).

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


21.24.4. DefaultCookiePolicy オブジェクト
=========================================

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

Both **RFC 2965** and Netscape cookies are covered.  RFC 2965 handling
is switched off by default.

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

   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* がクッキーを授受しないブラックリストに載っているかどうかを
   返します。

DefaultCookiePolicy.allowed_domains()

   "None" あるいは明示的に許可されているドメインを (タプルとして) 返し
   ます。

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

   許可するドメイン、あるいは "None" を設定します。

DefaultCookiePolicy.is_not_allowed(domain)

   *domain* がクッキーを授受するホワイトリストに載っているかどうかを返
   します。

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

DefaultCookiePolicy.rfc2109_as_netscape

   If true, request that the "CookieJar" instance downgrade **RFC
   2109** cookies (ie. cookies received in a *Set-Cookie* header with
   a version cookie-attribute of 1) to Netscape cookies by setting the
   version attribute of the "Cookie" instance to 0.  The default value
   is "None", in which case RFC 2109 cookies are downgraded if and
   only if **RFC 2965** handling is turned off.  Therefore, RFC 2109
   cookies are downgraded by default.

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

DefaultCookiePolicy.strict_domain

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

**RFC 2965** protocol strictness switches:

DefaultCookiePolicy.strict_rfc2965_unverifiable

   Follow **RFC 2965** rules on unverifiable transactions (usually, an
   unverifiable transaction is one resulting from a redirect or a
   request for an image hosted on another site).  If this is false,
   cookies are *never* blocked on the basis of verifiability

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

DefaultCookiePolicy.strict_ns_unverifiable

   Apply **RFC 2965** rules on unverifiable transactions even to
   Netscape cookies.

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

   When setting cookies, require a full **RFC 2965** domain-match.

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

DefaultCookiePolicy.DomainLiberal

   0 と同じです (つまり、上述の Netscape のドメイン厳密性フラグがすべ
   てオフにされます)。

DefaultCookiePolicy.DomainStrict

   "DomainStrictNoDots|DomainStrictNonDomain" と同じです。


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

"Cookie" instances have Python attributes roughly corresponding to the
standard cookie-attributes specified in the various cookie standards.
The correspondence is not one-to-one, because there are complicated
rules for assigning default values, because the "max-age" and
"expires" cookie-attributes contain equivalent information, and
because **RFC 2109** cookies may be 'downgraded' by "http.cookiejar"
from version 1 to version 0 (Netscape) cookies.

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

Cookie.version

   Integer or "None".  Netscape cookies have "version" 0. **RFC 2965**
   and **RFC 2109** cookies have a "version" cookie-attribute of 1.
   However, note that "http.cookiejar" may 'downgrade' RFC 2109
   cookies to Netscape cookies, in which case "version" is 0.

Cookie.name

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

Cookie.value

   クッキーの値 (文字列)、あるいは "None" 。

Cookie.port

   ポートあるいはポートの集合をあらわす文字列 (例: '80' または
   '80,8080')、あるいは "None" 。

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

   "True" if this cookie was received as an **RFC 2109** cookie (ie.
   the cookie arrived in a *Set-Cookie* header, and the value of the
   Version cookie-attribute in that header was 1).  This attribute is
   provided because "http.cookiejar" may 'downgrade' RFC 2109 cookies
   to Netscape cookies, in which case "version" is 0.

Cookie.port_specified

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

Cookie.domain_specified

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

Cookie.domain_initial_dot

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

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

Cookie.has_nonstandard_attr(name)

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

Cookie.get_nonstandard_attr(name, default=None)

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

Cookie.set_nonstandard_attr(name, value)

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

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

Cookie.is_expired(now=None)

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


21.24.6. 使用例
===============

The first example shows the most common usage of "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/")

The next example illustrates the use of "DefaultCookiePolicy". Turn on
**RFC 2965** cookies, be more strict about domains when setting and
returning Netscape cookies, and block some domains from setting
cookies or having them returned:

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