11.19 Cookie -- HTTP state management
Keywords: lib

# 11.19 `Cookie` -- HTTP state management

The `Cookie` module defines classes for abstracting the concept of cookies, an HTTP state management mechanism. It supports both simple string-only cookies, and provides an abstraction for having any serializable data-type as cookie value.

The module formerly strictly applied the parsing rules described in in the RFC 2109 and RFC 2068 specifications. It has since been discovered that MSIE 3.0x doesn't follow the character rules outlined in those specs. As a result, the parsing rules used are a bit less strict.

exception `CookieError`
  Exception failing because of RFC 2109 invalidity: incorrect attributes, incorrect `Set-Cookie` header, etc.

class `BaseCookie`([input])
  This class is a dictionary-like object whose keys are strings and whose values are `Morsel`s. Note that upon setting a key to a value, the value is first converted to a `Morsel` containing the key and the value.

  If input is given, it is passed to the `load()` method.

class `SimpleCookie`([input])
  This class derives from `BaseCookie` and overrides `value_decode()` and `value_encode()` to be the identity and `str()` respectively.

class `SerialCookie`([input])
  This class derives from `BaseCookie` and overrides `value_decode()` and `value_encode()` to be the `pickle.loads()` and `pickle.dumps()`.

  Do not use this class! Reading pickled values from untrusted cookie data is a huge security hole, as pickle strings can be crafted to cause arbitrary code to execute on your server. It is supported for backwards compatibility only, and may eventually go away.

class `SmartCookie`([input])
  This class derives from `BaseCookie`. It overrides `value_decode()` to be `pickle.loads()` if it is a valid pickle, and otherwise the value itself. It overrides `value_encode()` to be `pickle.dumps()` unless it is a string, in which case it returns the value itself.

  Note: The same security warning from `SerialCookie` applies here.

A further security note is warranted. For backwards compatibility, the `Cookie` module exports a class named `Cookie` which is just an alias for `SmartCookie`. This is probably a mistake and will likely be removed in a future version. You should not use the `Cookie` class in your applications, for the same reason why you should not use the `SerialCookie` class.

See Also:

RFC 2109, HTTP State Management Mechanism
  This is the state management specification implemented by this module.

Subsections

- 11.19.1 Cookie Objects
- 11.19.2 Morsel Objects
- 11.19.3 Example