--- rest25/library/cookielib.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/cookielib.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,20 +1,25 @@
-
 :mod:`cookielib` --- Cookie handling for HTTP clients
 =====================================================
 
 .. module:: cookielib
+   :synopsis: Classes for automatic handling of HTTP cookies.
 .. moduleauthor:: John J. Lee <jjl@pobox.com>
 .. sectionauthor:: John J. Lee <jjl@pobox.com>
 
+.. note::
+   The :mod:`cookielib` module has been renamed to :mod:`http.cookiejar` in
+   Python 3.0.  The :term:`2to3` tool will automatically adapt imports when
+   converting your sources to 3.0.
+
 
 .. versionadded:: 2.4
 
 
 
 The :mod:`cookielib` module defines classes for automatic handling of HTTP
 cookies.  It is useful for accessing web sites that require small pieces of data
 -- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
 web server, and then returned to the server in later HTTP requests.
 
 Both the regular Netscape cookie protocol and the protocol defined by
 :rfc:`2965` are handled.  RFC 2965 handling is switched off by default.
@@ -23,42 +28,40 @@
 Note that the great majority of cookies on the Internet are Netscape cookies.
 :mod:`cookielib` attempts to follow the de-facto Netscape cookie protocol (which
 differs substantially from that set out in the original Netscape specification),
 including taking note of the ``max-age`` and ``port`` cookie-attributes
 introduced with RFC 2965.
 
 .. note::
 
    The various named parameters found in :mailheader:`Set-Cookie` and
    :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are
    conventionally referred to as :dfn:`attributes`.  To distinguish them from
    Python attributes, the documentation for this module uses the term
-   :dfn:`cookie-attribute` instead
+   :dfn:`cookie-attribute` instead.
 
-.
 
 The module defines the following exception:
 
 
 .. exception:: LoadError
 
    Instances of :class:`FileCookieJar` raise this exception on failure to load
    cookies from a file.
 
    .. note::
 
       For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
-      :exc:`LoadError` is a subclass of :exc:`IOError`
+      :exc:`LoadError` is a subclass of :exc:`IOError`.
 
-   .
 
 The following classes are provided:
 
 
 .. class:: CookieJar(policy=None)
 
    *policy* is an object implementing the :class:`CookiePolicy` interface.
 
    The :class:`CookieJar` class stores HTTP cookies.  It extracts cookies from HTTP
    requests, and returns them in HTTP responses. :class:`CookieJar` instances
    automatically expire contained cookies when necessary.  Subclasses are also
    responsible for storing and retrieving cookies from a file or database.
@@ -86,75 +89,75 @@
    Constructor arguments should be passed as keyword arguments only.
    *blocked_domains* is a sequence of domain names that we never accept cookies
    from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a
    sequence of the only domains for which we accept and return cookies.  For all
    other arguments, see the documentation for :class:`CookiePolicy` and
    :class:`DefaultCookiePolicy` objects.
 
    :class:`DefaultCookiePolicy` implements the standard accept / reject rules for
    Netscape and RFC 2965 cookies.  By default, RFC 2109 cookies (ie. cookies
    received in a :mailheader:`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 :attr:`rfc2109_as_netscape` is True, RFC 2109 cookies are
-   'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by setting
+   'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by
-   the :attr:`version` attribute of the :class:`Cookie` instance to 0.
+   setting the :attr:`version` attribute of the :class:`Cookie` instance to 0.
-   :class:`DefaultCookiePolicy` also provides some parameters to allow some fine-
+   :class:`DefaultCookiePolicy` also provides some parameters to allow some
-   tuning of policy.
+   fine-tuning of policy.
 
 
 .. class:: Cookie()
 
    This class represents Netscape, RFC 2109 and RFC 2965 cookies.  It is not
    expected that users of :mod:`cookielib` construct their own :class:`Cookie`
    instances.  Instead, if necessary, call :meth:`make_cookies` on a
    :class:`CookieJar` instance.
 
 
 .. seealso::
 
    Module :mod:`urllib2`
       URL opening with automatic cookie handling.
 
    Module :mod:`Cookie`
       HTTP cookie classes, principally useful for server-side code.  The
       :mod:`cookielib` and :mod:`Cookie` modules do not depend on each other.
 
    http://wwwsearch.sf.net/ClientCookie/
       Extensions to this module, including a class for reading Microsoft Internet
       Explorer cookies on Windows.
 
-   http://www.netscape.com/newsref/std/cookie_spec.html
+   http://wp.netscape.com/newsref/std/cookie_spec.html
       The specification of the original Netscape cookie protocol.  Though this is
       still the dominant protocol, the 'Netscape cookie protocol' implemented by all
       the major browsers (and :mod:`cookielib`) only bears a passing resemblance to
       the one sketched out in ``cookie_spec.html``.
 
    :rfc:`2109` - HTTP State Management Mechanism
       Obsoleted by RFC 2965. Uses :mailheader:`Set-Cookie` with version=1.
 
    :rfc:`2965` - HTTP State Management Mechanism
       The Netscape protocol with the bugs fixed.  Uses :mailheader:`Set-Cookie2` in
       place of :mailheader:`Set-Cookie`.  Not widely used.
 
    http://kristol.org/cookie/errata.html
       Unfinished errata to RFC 2965.
 
    :rfc:`2964` - Use of HTTP State Management
 
 .. _cookie-jar-objects:
 
 CookieJar and FileCookieJar Objects
 -----------------------------------
 
-:class:`CookieJar` objects support the iterator protocol for iterating over
+:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over
 contained :class:`Cookie` objects.
 
 :class:`CookieJar` has the following methods:
 
 
 .. method:: CookieJar.add_cookie_header(request)
 
    Add correct :mailheader:`Cookie` header to *request*.
 
    If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of
    the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
    respectively), the :mailheader:`Cookie2` header is also added when appropriate.
@@ -278,60 +281,65 @@
 
 
 .. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)
 
    Clear all cookies and reload cookies from a saved file.
 
    :meth:`revert` can raise the same exceptions as :meth:`load`. If there is a
    failure, the object's state will not be altered.
 
 :class:`FileCookieJar` instances have the following public attributes:
 
 
-.. attribute:: XXX Class.filename
+.. attribute:: FileCookieJar.filename
 
    Filename of default file in which to keep cookies.  This attribute may be
    assigned to.
 
 
-.. attribute:: XXX Class.delayload
+.. attribute:: FileCookieJar.delayload
 
    If true, load cookies lazily from disk.  This attribute should not be assigned
    to.  This is only a hint, since this only affects performance, not behaviour
    (unless the cookies on disk are changing). A :class:`CookieJar` object may
    ignore it.  None of the :class:`FileCookieJar` classes included in the standard
    library lazily loads cookies.
 
 
 .. _file-cookie-jar-classes:
 
 FileCookieJar subclasses and co-operation with web browsers
 -----------------------------------------------------------
 
 The following :class:`CookieJar` subclasses are provided for reading and writing
 .  Further :class:`CookieJar` subclasses, including one that reads Microsoft
 Internet Explorer cookies, are available at
-`<http://wwwsearch.sf.net/ClientCookie/>`_.
+http://wwwsearch.sf.net/ClientCookie/.
 
 
 .. class:: MozillaCookieJar(filename, delayload=None, policy=None)
 
    A :class:`FileCookieJar` that can load from and save cookies to disk in the
    Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape
    browsers).
 
    .. note::
 
+      Version 3 of the Firefox web browser no longer writes cookies in the
+      ``cookies.txt`` file format.
+
+   .. note::
+
-      This loses information about RFC 2965 cookies, and also about newer or non-
-      standard cookie-attributes such as ``port``.
+      This loses information about RFC 2965 cookies, and also about newer or
+      non-standard cookie-attributes such as ``port``.
 
    .. warning::
 
       Back up your cookies before saving if you have cookies whose loss / corruption
       would be inconvenient (there are some subtleties which may lead to slight
       changes in the file over a load / save round-trip).
 
    Also note that cookies saved while Mozilla is running will get clobbered by
    Mozilla.
 
 
 .. class:: LWPCookieJar(filename, delayload=None, policy=None)
@@ -395,35 +403,35 @@
 .. method:: CookiePolicy.path_return_ok(path, request)
 
    Return false if cookies should not be returned, given cookie path.
 
    See the documentation for :meth:`domain_return_ok`.
 
 In addition to implementing the methods above, implementations of the
 :class:`CookiePolicy` interface must also supply the following attributes,
 indicating which protocols should be used, and how.  All of these attributes may
 be assigned to.
 
 
-.. attribute:: XXX Class.netscape
+.. attribute:: CookiePolicy.netscape
 
    Implement Netscape protocol.
 
 
-.. attribute:: XXX Class.rfc2965
+.. attribute:: CookiePolicy.rfc2965
 
    Implement RFC 2965 protocol.
 
 
-.. attribute:: XXX Class.hide_cookie2
+.. attribute:: CookiePolicy.hide_cookie2
 
    Don't add :mailheader:`Cookie2` header to requests (the presence of this header
    indicates to the server that we understand RFC 2965 cookies).
 
 The most useful way to define a :class:`CookiePolicy` class is by subclassing
 from :class:`DefaultCookiePolicy` and overriding some or all of the methods
 above.  :class:`CookiePolicy` itself may be used as a 'null policy' to allow
 setting and receiving any and all cookies (this is unlikely to be useful).
 
 
 .. _default-cookie-policy-objects:
 
@@ -500,127 +508,128 @@
 
 
 .. method:: DefaultCookiePolicy.is_not_allowed(domain)
 
    Return whether *domain* is not on the whitelist for setting or receiving
    cookies.
 
 :class:`DefaultCookiePolicy` instances have the following attributes, which are
 all initialised from the constructor arguments of the same name, and which may
 all be assigned to.
 
 
-.. attribute:: XXX Class.rfc2109_as_netscape
+.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape
 
    If true, request that the :class:`CookieJar` instance downgrade RFC 2109 cookies
    (ie. cookies received in a :mailheader:`Set-Cookie` header with a version
    cookie-attribute of 1) to Netscape cookies by setting the version attribute of
    the :class:`Cookie` instance to 0.  The default value is :const:`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.
 
    .. versionadded:: 2.5
 
 General strictness switches:
 
 
-.. attribute:: XXX Class.strict_domain
+.. attribute:: DefaultCookiePolicy.strict_domain
 
    Don't allow sites to set two-component domains with country-code top-level
    domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc.  This is far from perfect
    and isn't guaranteed to work!
 
 RFC 2965 protocol strictness switches:
 
 
-.. attribute:: XXX Class.strict_rfc2965_unverifiable
+.. attribute:: 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 protocol strictness switches:
 
 
-.. attribute:: XXX Class.strict_ns_unverifiable
+.. attribute:: DefaultCookiePolicy.strict_ns_unverifiable
 
    apply RFC 2965 rules on unverifiable transactions even to Netscape cookies
 
 
-.. attribute:: XXX Class.strict_ns_domain
+.. attribute:: DefaultCookiePolicy.strict_ns_domain
 
    Flags indicating how strict to be with domain-matching rules for Netscape
    cookies.  See below for acceptable values.
 
 
-.. attribute:: XXX Class.strict_ns_set_initial_dollar
+.. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar
 
    Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``.
 
 
-.. attribute:: XXX Class.strict_ns_set_path
+.. attribute:: DefaultCookiePolicy.strict_ns_set_path
 
    Don't allow setting cookies whose path doesn't path-match request URI.
 
 :attr:`strict_ns_domain` is a collection of flags.  Its value is constructed by
 or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means
 both flags are set).
 
 
-.. attribute:: XXX Class.DomainStrictNoDots
+.. attribute:: DefaultCookiePolicy.DomainStrictNoDots
 
    When setting cookies, the 'host prefix' must not contain a dot (eg.
    ``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo``
    contains a dot).
 
 
-.. attribute:: XXX Class.DomainStrictNonDomain
+.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain
 
    Cookies that did not explicitly specify a ``domain`` cookie-attribute can only
    be returned to a domain equal to the domain that set the cookie (eg.
    ``spam.example.com`` won't be returned cookies from ``example.com`` that had no
    ``domain`` cookie-attribute).
 
 
-.. attribute:: XXX Class.DomainRFC2965Match
+.. attribute:: DefaultCookiePolicy.DomainRFC2965Match
 
    When setting cookies, require a full RFC 2965 domain-match.
 
 The following attributes are provided for convenience, and are the most useful
 combinations of the above flags:
 
 
-.. attribute:: XXX Class.DomainLiberal
+.. attribute:: DefaultCookiePolicy.DomainLiberal
 
    Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
    off).
 
 
-.. attribute:: XXX Class.DomainStrict
+.. attribute:: DefaultCookiePolicy.DomainStrict
 
    Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.
 
 
-.. _cookie-objects:
+.. _cookielib-cookie-objects:
 
 Cookie Objects
 --------------
 
 :class:`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 :mod:`cookielib` from version 1 to version 0 (Netscape) cookies.
+assigning default values, because the ``max-age`` and ``expires``
+cookie-attributes contain equivalent information, and because RFC 2109 cookies
+may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape)
+cookies.
 
 Assignment to these attributes should not be necessary other than in rare
 circumstances in a :class:`CookiePolicy` method.  The class does not enforce
 internal consistency, so you should know what you're doing if you do that.
 
 
 .. attribute:: Cookie.version
 
    Integer or :const:`None`.  Netscape cookies have :attr:`version` 0. RFC 2965 and
    RFC 2109 cookies have a ``version`` cookie-attribute of 1.  However, note that
    :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
    case :attr:`version` is 0.
@@ -668,29 +677,29 @@
    String comment from the server explaining the function of this cookie, or
    :const:`None`.
 
 
 .. attribute:: Cookie.comment_url
 
    URL linking to a comment from the server explaining the function of this cookie,
    or :const:`None`.
 
 
 .. attribute:: Cookie.rfc2109
 
-   True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived
-   in a :mailheader:`Set-Cookie` header, and the value of the Version cookie-
-   attribute in that header was 1).  This attribute is provided because
-   :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
-   case :attr:`version` is 0.
+   True if this cookie was received as an RFC 2109 cookie (ie. the cookie
+   arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
+   cookie-attribute in that header was 1).  This attribute is provided because
+   :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
+   which case :attr:`version` is 0.
 
    .. versionadded:: 2.5
 
 
 .. attribute:: Cookie.port_specified
 
    True if a port or set of ports was explicitly specified by the server (in the
    :mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header).
 
 
 .. attribute:: Cookie.domain_specified
 
@@ -715,25 +724,25 @@
 
    If cookie has the named cookie-attribute, return its value. Otherwise, return
    *default*.
 
 
 .. method:: Cookie.set_nonstandard_attr(name, value)
 
    Set the value of the named cookie-attribute.
 
 The :class:`Cookie` class also defines the following method:
 
 
-.. method:: Cookie.is_expired([now=:const:`None`])
+.. method:: Cookie.is_expired([now=None])
 
    True if cookie has passed the time at which the server requested it should
    expire.  If *now* is given (in seconds since the epoch), return whether the
    cookie has expired at the specified time.
 
 
 .. _cookielib-examples:
 
 Examples
 --------
 
 The first example shows the most common usage of :mod:`cookielib`::
@@ -751,18 +760,18 @@
    cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
    opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
    r = opener.open("http://example.com/")
 
 The next example illustrates the use of :class:`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 urllib2
    from cookielib import CookieJar, DefaultCookiePolicy
    policy = DefaultCookiePolicy(
-       rfc2965=True, strict_ns_domain=Policy.DomainStrict,
+       rfc2965=True, strict_ns_domain=DefaultCookiePolicy.DomainStrict,
        blocked_domains=["ads.net", ".ads.net"])
    cj = CookieJar(policy)
    opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
    r = opener.open("http://example.com/")
 
