README
1What is this and what is it for?
2--------------------------------
3
4cookies.py is a Python module for working with HTTP cookies: parsing and
5rendering 'Cookie:' request headers and 'Set-Cookie:' response headers,
6and exposing a convenient API for creating and modifying cookies. It can be
7used as a replacement of Python's Cookie.py (aka http.cookies).
8
9Features
10--------
11
12* Rendering according to the excellent new RFC 6265
13 (rather than using a unique ad hoc format inconsistently relating to
14 unrealistic, very old RFCs which everyone ignored). Uses URL encoding to
15 represent non-ASCII by default, like many other languages' libraries
16* Liberal parsing, incorporating many complaints about Cookie.py barfing
17 on common cookie formats which can be reliably parsed (e.g. search 'cookie'
18 on the Python issue tracker)
19* Well-documented code, with chapter and verse from RFCs
20 (rather than arbitrary, undocumented decisions and huge tables of magic
21 values, as you see in Cookie.py).
22* Test coverage at 100%, with a much more comprehensive test suite
23 than Cookie.py
24* Single-source compatible with the following Python versions:
25 2.6, 2.7, 3.2, 3.3 and PyPy (2.7).
26* Cleaner, less surprising API::
27
28 # old Cookie.py - this code is all directly from its docstring
29 >>> from Cookie import SmartCookie
30 >>> C = SmartCookie()
31 >>> # n.b. it's "smart" because it automatically pickles Python objects,
32 >>> # which is actually quite stupid for security reasons!
33 >>> C["rocky"] = "road"
34 >>> C["rocky"]["path"] = "/cookie"
35 >>> # So C["rocky"] is a string, except when it's a dict...
36 >>> # and why do I have to write [""] to access a fixed set of attrs?
37 >>> # Look at the atrocious way I render out a request header:
38 >>> C.output(attrs=[], header="Cookie:")
39 'Cookie: rocky=road'
40
41 # new cookies.py
42 >>> from cookies import Cookies, Cookie
43 >>> cookies = Cookies(rocky='road')
44 >>> # Can also write explicitly: cookies['rocky'] = Cookie['road']
45 >>> cookies['rocky'].path = "/cookie"
46 >>> cookies.render_request()
47 'rocky=road'
48* Friendly to customization, extension, and reuse of its parts.
49 Unlike Cookie.py, it doesn't lock all implementation inside its own classes
50 (forcing you to write ugly wrappers as Django, Trac, Werkzeug/Flask, web.py
51 and Tornado had to do). You can suppress minor parse exceptions with
52 parameters rather than subclass wrappers. You can plug in your own parsers,
53 renderers and validators for new or existing cookie attributes. You can
54 render the data out in a dict. You can easily use the underlying imperative
55 API or even lift the parser's regexps for your own parser or project. They
56 are very well documented and relate directly to RFCs, so you know exactly
57 what you are getting and why. It's MIT-licensed so do
58 what you want (but I'd love to know what use you are getting from it!)
59* One file, so you can just drop cookies.py into your project if you like
60* MIT license, so you can use it in whatever you want with no strings
61
62Things this is not meant to do
63------------------------------
64While this is intended to be a good module for handling cookies, it does not
65even try to do any of the following:
66
67* Maintain backward compatibility with Cookie.py, which would mean
68 inheriting its confusions and bugs
69* Implement RFCs 2109 or 2965, which have always been ignored by almost
70 everyone and are now obsolete as well
71* Handle every conceivable output from terrible legacy apps, which is not
72 possible to do without lots of silent data loss and corruption (the
73 parser does try to be liberal as possible otherwise, though)
74* Provide a means to store pickled Python objects in cookie values
75 (that's a big security hole)
76
77This doesn't compete with the cookielib (http.cookiejar) module in the Python
78standard library, which is specifically for implementing cookie storage and
79similar behavior in an HTTP client such as a browser. Things cookielib does
80that this doesn't:
81
82* Write to or read from browsers' cookie stores or other proprietary
83 formats for storing cookie data in files
84* Handle the browser/client logic like deciding which cookies to send or
85 discard, etc.
86
87If you are looking for a cookie library but neither this one nor cookielib
88will help, you might also consider the implementations in WebOb or Bottle.
89