| 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 |
n | 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by setting |
n | '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. |
| 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: |
| |
| |
n | .. attribute:: XXX Class.filename |
n | .. attribute:: FileCookieJar.filename |
| |
| Filename of default file in which to keep cookies. This attribute may be |
| assigned to. |
| |
| |
n | .. attribute:: XXX Class.delayload |
n | .. 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 |
n | `<http://wwwsearch.sf.net/ClientCookie/>`_. |
n | 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:: |
| |
n | 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- |
| This loses information about RFC 2965 cookies, and also about newer or |
| standard cookie-attributes such as ``port``. |
| 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 |
| 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. |
| |
| |
n | .. attribute:: XXX Class.netscape |
n | .. attribute:: CookiePolicy.netscape |
| |
| Implement Netscape protocol. |
| |
| |
n | .. attribute:: XXX Class.rfc2965 |
n | .. attribute:: CookiePolicy.rfc2965 |
| |
| Implement RFC 2965 protocol. |
| |
| |
n | .. attribute:: XXX Class.hide_cookie2 |
n | .. 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). |
| 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. |
| |
| |
n | .. attribute:: XXX Class.rfc2109_as_netscape |
n | .. 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: |
| |
| |
n | .. attribute:: XXX Class.strict_domain |
n | .. 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: |
| |
| |
n | .. attribute:: XXX Class.strict_rfc2965_unverifiable |
n | .. 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: |
| |
| |
n | .. attribute:: XXX Class.strict_ns_unverifiable |
n | .. attribute:: DefaultCookiePolicy.strict_ns_unverifiable |
| |
| apply RFC 2965 rules on unverifiable transactions even to Netscape cookies |
| |
| |
n | .. attribute:: XXX Class.strict_ns_domain |
n | .. attribute:: DefaultCookiePolicy.strict_ns_domain |
| |
| Flags indicating how strict to be with domain-matching rules for Netscape |
| cookies. See below for acceptable values. |
| |
| |
n | .. attribute:: XXX Class.strict_ns_set_initial_dollar |
n | .. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar |
| |
| Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``. |
| |
| |
n | .. attribute:: XXX Class.strict_ns_set_path |
n | .. 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). |
| |
| |
n | .. attribute:: XXX Class.DomainStrictNoDots |
n | .. 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). |
| |
| |
n | .. attribute:: XXX Class.DomainStrictNonDomain |
n | .. 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). |
| |
| |
n | .. attribute:: XXX Class.DomainRFC2965Match |
n | .. 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: |
| |
| |
n | .. attribute:: XXX Class.DomainLiberal |
n | .. attribute:: DefaultCookiePolicy.DomainLiberal |
| |
| Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched |
| off). |
| |
| |
n | .. attribute:: XXX Class.DomainStrict |
n | .. attribute:: DefaultCookiePolicy.DomainStrict |
| |
| Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``. |
| |
| |
n | .. _cookie-objects: |
n | .. _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 |
n | assigning default values, because the ``max-age`` and ``expires`` cookie- |
n | assigning default values, because the ``max-age`` and ``expires`` |
| attributes contain equivalent information, and because RFC 2109 cookies may be |
| cookie-attributes contain equivalent information, and because RFC 2109 cookies |
| 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape) 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 |
| |
| .. attribute:: Cookie.comment_url |
| |
| URL linking to a comment from the server explaining the function of this cookie, |
| or :const:`None`. |
| |
| |
| .. attribute:: Cookie.rfc2109 |
| |
n | True if this cookie was received as an RFC 2109 cookie (ie. the cookie arrived |
n | True if this cookie was received as an RFC 2109 cookie (ie. the cookie |
| in a :mailheader:`Set-Cookie` header, and the value of the Version cookie- |
| arrived in a :mailheader:`Set-Cookie` header, and the value of the Version |
| attribute in that header was 1). This attribute is provided because |
| cookie-attribute in that header was 1). This attribute is provided because |
| :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which |
| :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in |
| case :attr:`version` is 0. |
| 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). |