11.20.4 DefaultCookiePolicy Objects

##
11.20.4 DefaultCookiePolicy Objects

Implements the standard rules for accepting and returning cookies.

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

The easiest way to provide your own policy is to override this class and call its methods in your overridden implementations before adding your own additional checks:

    import cookielib
    class MyCookiePolicy(cookielib.DefaultCookiePolicy):
        def set_ok(self, cookie, request):
            if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
                return False
            if i_dont_want_to_store_this_cookie(cookie):
                return False
            return True

In addition to the features required to implement the `CookiePolicy` interface, this class allows you to block and allow domains from setting and receiving cookies. There are also some strictness switches that allow you to tighten up the rather loose Netscape protocol rules a little bit (at the cost of blocking some benign cookies).

A domain blacklist and whitelist is provided (both off by default). Only domains not in the blacklist and present in the whitelist (if the whitelist is active) participate in cookie setting and returning. Use the blocked_domains constructor argument, and `blocked_domains()` and `set_blocked_domains()` methods (and the corresponding argument and methods for allowed_domains). If you set a whitelist, you can turn it off again by setting it to `None`.

Domains in block or allow lists that do not start with a dot must equal the cookie domain to be matched. For example, `"example.com"` matches a blacklist entry of `"example.com"`, but `"www.example.com"` does not. Domains that do start with a dot are matched by more specific domains too. For example, both `"www.example.com"` and `"www.coyote.example.com"` match `".example.com"` (but `"example.com"` itself does not). IP addresses are an exception, and must match exactly. For example, if blocked_domains contains `"192.168.1.2"` and `".168.1.2"`, 192.168.1.2 is blocked, but 193.168.1.2 is not.

`DefaultCookiePolicy` implements the following additional methods:

`blocked_domains`( | )

  Return the sequence of blocked domains (as a tuple).

`set_blocked_domains`( | blocked_domains)

  Set the sequence of blocked domains.

`is_blocked`( | domain)

  Return whether domain is on the blacklist for setting or receiving cookies.

`allowed_domains`( | )

  Return `None`, or the sequence of allowed domains (as a tuple).

`set_allowed_domains`( | allowed_domains)

  Set the sequence of allowed domains, or `None`.

`is_not_allowed`( | domain)

  Return whether domain is not on the whitelist for setting or receiving cookies.

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

General strictness switches:

`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:

`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:

`strict_ns_unverifiable`
  apply RFC 2965 rules on unverifiable transactions even to Netscape cookies

`strict_ns_domain`
  Flags indicating how strict to be with domain-matching rules for Netscape cookies. See below for acceptable values.

`strict_ns_set_initial_dollar`
  Ignore cookies in Set-Cookie: headers that have names starting with `'$'`.

`strict_ns_set_path`
  Don't allow setting cookies whose path doesn't path-match request URI.

`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).

`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).

`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).

`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:

`DomainLiberal`
  Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched off).

`DomainStrict`
  Equivalent to `DomainStrictNoDots|DomainStrictNonDomain`.