~vcs-imports/clientcookie/trunk : revision 2

1

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"

2

"http://www.w3.org/TR/html4/strict.dtd">

3

<html>

4

<head>

5

6

7

8

9

<title>ClientCookie</title>

10

11

12

13

</head>

14

<body>

15

16

@# This file is processed by EmPy to colorize Python source code

17

@# http://wwwsearch.sf.net/bits/colorize.py

18

@{from colorize import colorize}

19

20

21

<img src="http://sourceforge.net/sflogo.php?group_id=48205&type=2"

22

width="125" height="37" alt="SourceForge.net Logo"></a></div>

23

24

25

<h1>ClientCookie</h1>

26

27

28

29

<p>ClientCookie is a <a href="http://www.python.org/">Python</a> module for

30

handling HTTP cookies on the client side, useful for accessing web sites that

31

require cookies to be set and then returned later. It also provides some other

32

(optional) useful stuff: <code>HTTP-EQUIV</code> and <code>Refresh</code>

33

handling, automatic adding of the <code>Referer</code> [<em><a

34

href="http://www.ietf.org/rfc/rfc2616.txt">sic</a></em>] header, automatic

35

observance of <code>robots.txt</code> and lazily-<code>seek()</code>able

36

responses. These extras are implemented using an extension that makes it

37

easier to add new functionality to <code>urllib2</code>. It has developed from

38

a port of Gisle Aas' Perl module <code>HTTP::Cookies</code>, from the <a

39

href="http://www.linpro.no/lwp/">libwww-perl</a> library.

40

41

@{colorize(r"""

42

import ClientCookie

43

response = ClientCookie.urlopen("http://foo.bar.com/")

44

""")}

45

46

<p>This function behaves identically to <code>urllib2.urlopen</code>, except

47

that it deals with cookies automatically. That's probably all you need to

48

know.

49

50

<p>Python 1.5.2 or above is required, and <code>urllib2</code> is recommended.

51

If you have 2.1 or above, you've already got a recent enough version of

52

<code>urllib2</code>. For Python 1.5.2, use this <a href="../bits/urllib2.py">

53

<code>urllib2</code></a> and this <a href="../bits/urllib.py">

54

<code>urllib</code></a>. For Python 2.0, you need the newer versions from

55

Python 2.1 (available from the source distribution or CVS from <a

56

href="http://www.python.org/">http://www.python.org/</a>), or use the

57

1.5.2-compatible versions. Note that you don't need to replace the original

58

<code>urllib2</code> / <code>urllib</code> - you can just make sure they're in

59

<code>sys.path</code> ahead of the copies from 2.0's standard library.

60

61

<p>For full documentation, see <a href="./doc.html">here</a> and the docstrings

62

in the module source code.

63

64

<p>Other than Gisle, particular thanks to Johnny Lee (MSIE Perl code) and

65

Ronald Tschalar (advice on Netscape cookies).

66

67

68

<h2>Download</h2>

69

70

<p>All documentation (including these web pages) is included in the

71

distribution.

72

73

<p><em>Development release.</em>

74

75

<ul>

76

<li><a href="./src/ClientCookie-0.9.4a.tar.gz">ClientCookie-0.9.4a.tar.gz</a>

77

<li><a href="./src/ClientCookie-0_9_4a.zip">ClientCookie-0_9_4a.zip</a>

78

<li><a href="./src/ChangeLog.txt">Change Log</a> (included in distribution)

79

<li><a href="./src/">Older versions.</a>

80

</ul>

81

82

<br>

83

84

<p><em>Stable release.</em>

85

86

<ul>

87

<li><a href="./src/ClientCookie-0.4.19.tar.gz">ClientCookie-0.4.19.tar.gz</a>

88

<li><a href="./src/ClientCookie-0_4_19.zip">ClientCookie-0_4_19.zip</a>

89

<li><a href="./src/ChangeLog.txt">Change Log</a> (included in distribution)

90

<li><a href="./src/">Older versions.</a>

91

</ul>

92

93

<p>For installation instructions, see the INSTALL file included in the

94

distribution.

95

96

97

<h2>FAQs - pre-install</h2>

98

<ul>

99

<li>Doesn't the standard Python library module, <code>Cookie</code>, do

100

this?

101

<p>No: Cookie.py does the server end of the job. It doesn't know when to

102

accept cookies from a server or when to pass them back.

103

<li>Which version of Python do I need?

104

<p>1.5.2 or above.

105

<li>Is urllib2.py required?

106

<p>No. You probably want it, though.

107

<li>Which urllib2.py do I need?

108

<p>You don't, but if you want to use the extended <code>urllib2</code>

109

callables from ClientCookie, and you have Python 2.0, you need to

110

upgrade to the version from Python 2.1 (or use the 1.5.2-compatible

111

version). If you have Python 1.5.2, use this

112

<a href="../bits/urllib2.py"><code>urllib2</code></a> and

113

<a href="../bits/urllib.py"><code>urllib</code></a>. Otherwise, you're OK.

114

<li>Which license?

115

116

BSD license</a> (included in distribution).

117

<li>Where can I find out more about the HTTP cookie protocol?

118

<p>There is more than one protocol, in fact (see the <a href="./doc.html">docs</a>

119

for a brief explanation of the history):

120

<ul>

121

<li>The original <a href="http://www.netscape.com/newsref/std/cookie_spec.html">

122

Netscape cookie protocol</a> - the standard still in use today, in

123

theory (in reality, the protocol implemented by all the major browsers

124

only bears a passing resemblance to the protocol sketched out in this

125

document).

126

<li><a href="http://www.ietf.org/rfcs/rfc2109.txt">RFC 2109</a> - obsoleted

127

by RFC 2965.

128

<li><a href="http://www.ietf.org/rfcs/rfc2965.txt">RFC 2965</a> - the

129

Netscape protocol with the bugs fixed (not widely used - the Netscape

130

protocol still dominates, and seems likely to remain dominant

131

indefinitely, at least on the Internet).

132

<a href="http://www.ietf.org/rfcs/rfc2964.txt">RFC 2964</a> discusses use

133

of the protocol.

134

<a href="http://kristol.org/cookie/errata.html">Errata</a> to RFC 2965

135

are currently being discussed on the

136

137

http-state mailing list</a> (update: list traffic died months ago and

138

hasn't revived).

139

<li>A <a href="http://doi.acm.org/10.1145/502152.502153">paper</a> by David

140

Kristol setting out the history of the cookie standards in exhausting

141

detail.

142

<li>HTTP cookies <a href="http://www.cookiecentral.com/">FAQ</a>.

143

</ul>

144

<li>Which protocols does ClientCookie support?

145

<p>Netscape and RFC 2965. RFC 2965 handling is switched off by default.

146

<li>What about RFC 2109?

147

<p>RFC 2109 cookies are currently parsed as Netscape cookies, and treated

148

as RFC 2965 cookies thereafter. RFC 2109 is officially obsoleted by RFC

149

2965. Browsers do use a few RFC 2109 features in their Netscape cookie

150

implementations (<code>port</code> and <code>max-age</code>), and

151

ClientCookie knows about that, too.

152

</ul>

153

154

<p><a href="mailto:jjl@@pobox.com">John J. Lee</a>, January 2004.

155

156

<hr>

157

158

</div>

159

160

161

162

163

164

165

<br>

166

167

<span class="thispage">ClientCookie</span><br>

168

<a href="../ClientCookie/doc.html"><span class="subpage">ClientCookie docs</span></a><br>

169

<a href="../ClientForm/">ClientForm</a><br>

170

<a href="../DOMForm/">DOMForm</a><br>

171

<a href="../python-spidermonkey/">python-spidermonkey</a><br>

172

<a href="../ClientTable/">ClientTable</a><br>

173

<a href="../mechanize/">mechanize</a><br>

174

<a href="../pullparser/">pullparser</a><br>

175

<a href="../bits/GeneralFAQ.html">General FAQs</a><br>

176

<a href="../bits/urllib2_152.py">1.5.2 urllib2.py</a><br>

177

<a href="../bits/urllib_152.py">1.5.2 urllib.py</a><br>

178

179

<br>

180

181

<a href="./#download">Download</a><br>

182

<a href="./#faq_pre">FAQs - pre-install</a><br>

183

184

</div>

185

186

187

</body>

188

</html>