<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <meta name="author" content="John J. Lee <jjl@pobox.com>"> <meta name="date" content="2006-04-08"> <meta name="keywords" content="cookie,HTTP,Python,web,client,client-side,HTML,META,HTTP-EQUIV,Refresh"> <title>ClientCookie</title> <style type="text/css" media="screen">@import "../styles/style.css";</style> <style type="text/css" media="screen">@import "../styles/cookie_style.css";</style> <base href="http://wwwsearch.sourceforge.net/ClientCookie/"> </head> <body> <div id="sf"><a href="http://sourceforge.net"> <img src="http://sourceforge.net/sflogo.php?group_id=48205&type=2" width="125" height="37" alt="SourceForge.net Logo"></a></div> <!--<img src="../images/sflogo.png"--> <h1>ClientCookie</h1> <div id="Content"> <p>Please read <a href="./#compatnotes">this note</a> explaining the relationship between ClientCookie, <code>cookielib</code> and <code>urllib2</code>, and which to use when. <p>ClientCookie is a <a href="http://www.python.org/">Python</a> module for handling HTTP cookies on the client side, useful for accessing web sites that require cookies to be set and then returned later. It also provides some other (optional) useful stuff: <code>HTTP-EQUIV</code> and <code>Refresh</code> handling, automatic adding of the <code>Referer</code> [<em><a href="http://www.ietf.org/rfc/rfc2616.txt">sic</a></em>] header, automatic observance of <code>robots.txt</code> and lazily-<code>seek()</code>able responses. These extras are implemented using an extension that makes it easier to add new functionality to <code>urllib2</code>. It has developed from a port of Gisle Aas' Perl module <code>HTTP::Cookies</code>, from the <a href="http://www.linpro.no/lwp/">libwww-perl</a> library. <pre> <span class="pykw">import</span> ClientCookie response = ClientCookie.urlopen(<span class="pystr">"http://foo.bar.com/"</span>)</pre> <p>This function behaves identically to <code>urllib2.urlopen</code>, except that it deals with cookies automatically. That's probably all you need to know. <p>Python 2.0 or above is required, and <code>urllib2</code> is recommended. If you have 2.1 or above, you've already got a recent enough version of <code>urllib2</code>. For Python 2.0, you need the newer versions from Python 2.1 (available from the source distribution or Python CVS: <a href="http://cvs.sourceforge.net/viewcvs.py/*checkout*/python/python/dist/src/Lib/urllib2.py?rev=1.13.2.2">urllib2.py</a>). Note that you don't need to replace the original <code>urllib2</code> / <code>urllib</code> - you can just make sure they're in <code>sys.path</code> ahead of the copies from 2.0's standard library. <p>For full documentation, see <a href="./doc.html">here</a> and the docstrings in the module source code. <p>Other than Gisle, particular thanks to Johnny Lee (MSIE Perl code) and Ronald Tschalar (advice on Netscape cookies). <a name="compatnotes"></a> <h2>Notes about ClientCookie, <code>urllib2</code> and <code>cookielib</code></h2> <p>Even if you're not using Python 2.4, please note the last of these points. <ol> <li>The cookie handling parts of ClientCookie are in Python 2.4 standard library as module <code>cookielib</code> and extensions to module <code>urllib2</code>. <li>ClientCookie works with Python 2.4. <li>For new code to run on Python 2.4, I recommend use of standard library modules <code>urllib2</code> and <code>cookielib</code> instead of ClientCookie. I recommend <a href="http://docs.python.org/lib/cookielib-examples.html">turning on RFC 2965 support</a> to work around a bug in <code>cookielib</code> in Python 2.4.0. <li>Handler classes thst are missing from 2.4's <code>urllib2</code> (eg. <code>HTTPRefreshProcessor</code>) may be used with 2.4's <code>urllib2</code> (however, note the paragraph below). With any version of Python, parts of <code>urllib2</code> that are missing from ClientCookie (eg. <code>ProxyHandler</code>) may be used with ClientCookie, and <code>urllib2.Request</code> objects may be used with ClientCookie. <strong>IMPORTANT:</strong> For all other code, use ClientCookie <em><strong>exclusively</strong></em>: do NOT mix use of ClientCookie and <code>urllib2</code>! </ol> <p><strong>Finally, note</strong> that, if you want to use <code>ClientCookie.RefreshProcessor</code> with Python 2.4's <code>urllib2</code>, you must also use <code>ClientCookie.HTTPRedirectHandler</code>. <a name="download"></a> <h2>Download</h2> <p>All documentation (including these web pages) is included in the distribution. <p>To port your code from 0.4.x to 1.0.x, see <a href="./porting-0.4-1.0.txt">here</a>. <p><em>Stable release.</em> <ul> <li><a href="./src/ClientCookie-1.3.0.tar.gz">ClientCookie-1.3.0.tar.gz</a> <li><a href="./src/ClientCookie-1.3.0.zip">ClientCookie-1.3.0.zip</a> <li><a href="./src/ChangeLog.txt">Change Log</a> (included in distribution) <li><a href="./src/">Older versions.</a> </ul> <br> <p><em>Old release.</em> <ul> <li><a href="./src/ClientCookie-0.4.19.tar.gz">ClientCookie-0.4.19.tar.gz</a> <li><a href="./src/ClientCookie-0_4_19.zip">ClientCookie-0_4_19.zip</a> <li><a href="./src/ChangeLog.txt">Change Log</a> (included in distribution) <li><a href="./src/">Older versions.</a> </ul> <p>For installation instructions, see the INSTALL file included in the distribution. <h2>Subversion</h2> <p>The <a href="http://subversion.tigris.org/">Subversion (SVN)</a> trunk is <a href="http://codespeak.net/svn/wwwsearch/ClientCookie/trunk#egg=ClientCookie-dev">http://codespeak.net/svn/wwwsearch/ClientCookie/trunk</a>, so to check out the source: <pre> svn co http://codespeak.net/svn/wwwsearch/ClientCookie/trunk ClientCookie </pre> <a name="faq_pre"></a> <h2>FAQs - pre-install</h2> <ul> <li>Doesn't the standard Python library module, <code>Cookie</code>, do this? <p>No: Cookie.py does the server end of the job. It doesn't know when to accept cookies from a server or when to pass them back. <li>Which version of Python do I need? <p>2.0 or above. <li>Is urllib2.py required? <p>No. You probably want it, though. <li>Which urllib2.py do I need? <p>You don't, but if you want to use the extended <code>urllib2</code> callables from ClientCookie, and you have Python 2.0, you need to upgrade to the version from Python 2.1. Otherwise, you're OK. <li>Which license? <p>ClientCookie is dual-licensed: you may pick either the <a href="http://www.opensource.org/licenses/bsd-license.php">BSD license</a>, or the <a href="http://www.zope.org/Resources/ZPL">ZPL 2.1</a> (both are included in the distribution). <li>Where can I find out more about the HTTP cookie protocol? <p>There is more than one protocol, in fact (see the <a href="./doc.html">docs</a> for a brief explanation of the history): <ul> <li>The original <a href="http://www.netscape.com/newsref/std/cookie_spec.html"> Netscape cookie protocol</a> - the standard still in use today, in theory (in reality, the protocol implemented by all the major browsers only bears a passing resemblance to the protocol sketched out in this document). <li><a href="http://www.ietf.org/rfcs/rfc2109.txt">RFC 2109</a> - obsoleted by RFC 2965. <li><a href="http://www.ietf.org/rfcs/rfc2965.txt">RFC 2965</a> - the Netscape protocol with the bugs fixed (not widely used - the Netscape protocol still dominates, and seems likely to remain dominant indefinitely, at least on the Internet). <a href="http://www.ietf.org/rfcs/rfc2964.txt">RFC 2964</a> discusses use of the protocol. <a href="http://kristol.org/cookie/errata.html">Errata</a> to RFC 2965 are currently being discussed on the <a href="http://lists.bell-labs.com/mailman/listinfo/http-state"> http-state mailing list</a> (update: list traffic died months ago and hasn't revived). <li>A <a href="http://doi.acm.org/10.1145/502152.502153">paper</a> by David Kristol setting out the history of the cookie standards in exhausting detail. <li>HTTP cookies <a href="http://www.cookiecentral.com/">FAQ</a>. </ul> <li>Which protocols does ClientCookie support? <p>Netscape and RFC 2965. RFC 2965 handling is switched off by default. <li>What about RFC 2109? <p>RFC 2109 cookies are currently parsed as Netscape cookies, and treated by default as RFC 2965 cookies thereafter if RFC 2965 handling is enabled, or as Netscape cookies otherwise. RFC 2109 is officially obsoleted by RFC 2965. Browsers do use a few RFC 2109 features in their Netscape cookie implementations (<code>port</code> and <code>max-age</code>), and ClientCookie knows about that, too. </ul> <p>I prefer questions and comments to be sent to the <a href="http://lists.sourceforge.net/lists/listinfo/wwwsearch-general"> mailing list</a> rather than direct to me. <p><a href="mailto:jjl@pobox.com">John J. Lee</a>, April 2006. <hr> </div> <div id="Menu"> <a href="..">Home</a><br> <br> <a href="../bits/GeneralFAQ.html">General FAQs</a><br> <br> <a href="../mechanize/">mechanize</a><br> <a href="../pullparser/">pullparser</a><br> <span class="thispage">ClientCookie</span><br> <a href="../ClientCookie/doc.html"><span class="subpage">ClientCookie docs</span></a><br> <a href="../ClientForm/">ClientForm</a><br> <br> <a href="../DOMForm/">DOMForm</a><br> <a href="../python-spidermonkey/">python-spidermonkey</a><br> <a href="../ClientTable/">ClientTable</a><br> <a href="../bits/urllib2_152.py">1.5.2 urllib2.py</a><br> <a href="../bits/urllib_152.py">1.5.2 urllib.py</a><br> <br> <a href="./#download">Download</a><br> <a href="./#faq_pre">FAQs - pre-install</a><br> </div> </body> </html>