n | |
| :mod:`Cookie` --- HTTP state management |
| ======================================= |
| |
| .. module:: Cookie |
| :synopsis: Support for HTTP state management (cookies). |
| .. moduleauthor:: Timothy O'Malley <timo@alum.mit.edu> |
| .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| |
n | .. note:: |
| The :mod:`Cookie` module has been renamed to :mod:`http.cookies` in Python |
| 3.0. The :term:`2to3` tool will automatically adapt imports when converting |
| your sources to 3.0. |
| |
| |
| The :mod:`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 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. |
n | |
| .. note:: |
| |
| On encountering an invalid cookie, :exc:`CookieError` is raised, so if your |
| cookie data comes from a browser you should always prepare for invalid data |
| and catch :exc:`CookieError` on parsing. |
| |
| |
| .. exception:: CookieError |
| |
| Exception failing because of :rfc:`2109` invalidity: incorrect attributes, |
| incorrect :mailheader:`Set-Cookie` header, etc. |
| |
| |
| |
| |
| .. _morsel-objects: |
| |
| Morsel Objects |
| -------------- |
| |
| |
n | .. class:: Morsel() |
n | .. class:: Morsel |
| |
| Abstract a key/value pair, which has some :rfc:`2109` attributes. |
| |
| Morsels are dictionary-like objects, whose set of keys is constant --- the valid |
| :rfc:`2109` attributes, which are |
| |
n | * ``expires`` |
n | * ``expires`` |
| |
| * ``path`` |
| * ``path`` |
| |
| * ``comment`` |
| * ``comment`` |
| |
| * ``domain`` |
| * ``domain`` |
| |
| * ``max-age`` |
| * ``max-age`` |
| |
| * ``secure`` |
| * ``secure`` |
| |
| * ``version`` |
| * ``version`` |
| * ``httponly`` |
| |
| The attribute :attr:`httponly` specifies that the cookie is only transfered |
| in HTTP requests, and is not accessible through JavaScript. This is intended |
| to mitigate some forms of cross-site scripting. |
| |
| The keys are case-insensitive. |
n | |
| .. versionadded:: 2.6 |
| The :attr:`httponly` attribute was added. |
| |
| |
| .. attribute:: Morsel.value |
| |
| The value of the cookie. |
| |
| |
| .. attribute:: Morsel.coded_value |
| The meaning for *attrs* is the same as in :meth:`output`. |
| |
| |
| .. _cookie-example: |
| |
| Example |
| ------- |
| |
n | The following example demonstrates how to use the :mod:`Cookie` module. :: |
n | The following example demonstrates how to use the :mod:`Cookie` module. |
| |
| .. doctest:: |
| :options: +NORMALIZE_WHITESPACE |
| |
| >>> import Cookie |
| >>> C = Cookie.SimpleCookie() |
| >>> C = Cookie.SerialCookie() |
| >>> C = Cookie.SmartCookie() |
| >>> C["fig"] = "newton" |
| >>> C["sugar"] = "wafer" |
| >>> print C # generate HTTP headers |
n | Set-Cookie: fig=newton |
| Set-Cookie: sugar=wafer |
n | >>> print C.output() # same thing |
| Set-Cookie: fig=newton |
n | >>> print C.output() # same thing |
| Set-Cookie: sugar=wafer |
n | Set-Cookie: fig=newton |
| >>> C = Cookie.SmartCookie() |
| >>> C["rocky"] = "road" |
| >>> C["rocky"]["path"] = "/cookie" |
| >>> print C.output(header="Cookie:") |
| Cookie: rocky=road; Path=/cookie |
| >>> print C.output(attrs=[], header="Cookie:") |
| Cookie: rocky=road |
| >>> C = Cookie.SmartCookie() |
| >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header) |
| >>> print C |
n | Set-Cookie: chips=ahoy |
| Set-Cookie: vienna=finger |
t | Set-Cookie: chips=ahoy |
| >>> C = Cookie.SmartCookie() |
| >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";') |
| >>> print C |
| Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;" |
| >>> C = Cookie.SmartCookie() |
| >>> C["oreo"] = "doublestuff" |
| >>> C["oreo"]["path"] = "/" |
| >>> print C |