~dkuhlman/python-training-materials/Materials

<h1>21.24. <a class="reference internal" href="#module-http.cookiejar" title="http.cookiejar: Classes for automatic handling of HTTP cookies."><code class="xref py py-mod docutils literal">http.cookiejar</code></a> — Cookie handling for HTTP clients<a class="headerlink" href="#module-http.cookiejar" title="Permalink to this headline">¶</a></h1>

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/http/cookiejar.py">Lib/http/cookiejar.py</a>

The <a class="reference internal" href="#module-http.cookiejar" title="http.cookiejar: Classes for automatic handling of HTTP cookies."><code class="xref py py-mod docutils literal">http.cookiejar</code></a> module defines classes for automatic handling of HTTP

cookies. It is useful for accessing web sites that require small pieces of data

100

– cookies – to be set on the client machine by an HTTP response from a

101

web server, and then returned to the server in later HTTP requests.

102

Both the regular Netscape cookie protocol and the protocol defined by

103

<a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html">RFC 2965</a> are handled. RFC 2965 handling is switched off by default.

104

<a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html">RFC 2109</a> cookies are parsed as Netscape cookies and subsequently treated

105

either as Netscape or RFC 2965 cookies according to the ‘policy’ in effect.

106

Note that the great majority of cookies on the Internet are Netscape cookies.

107

108

differs substantially from that set out in the original Netscape specification),

109

including taking note of the <code class="docutils literal">max-age</code> and <code class="docutils literal">port</code> cookie-attributes

110

introduced with RFC 2965.

111

112

Note

113

The various named parameters found in Set-Cookie and

114

Set-Cookie2 headers (eg. <code class="docutils literal">domain</code> and <code class="docutils literal">expires</code>) are

115

conventionally referred to as attributes. To distinguish them from

116

Python attributes, the documentation for this module uses the term

117

cookie-attribute instead.

118

</div>

119

The module defines the following exception:

120

121

122

exception <code class="descclassname">http.cookiejar.</code><code class="descname">LoadError</code><a class="headerlink" href="#http.cookiejar.LoadError" title="Permalink to this definition">¶</a></dt>

123

<dd>Instances of <a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal">FileCookieJar</code></a> raise this exception on failure to load

124

cookies from a file. <a class="reference internal" href="#http.cookiejar.LoadError" title="http.cookiejar.LoadError"><code class="xref py py-exc docutils literal">LoadError</code></a> is a subclass of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a>.

125

126

Changed in version 3.3: LoadError was made a subclass of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> instead of

127

<a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal">IOError</code></a>.

128

</div>

129

</dd></dl>

130

131

The following classes are provided:

132

133

134

class <code class="descclassname">http.cookiejar.</code><code class="descname">CookieJar</code>(policy=None)<a class="headerlink" href="#http.cookiejar.CookieJar" title="Permalink to this definition">¶</a></dt>

135

<dd>policy is an object implementing the <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> interface.

136

The <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> class stores HTTP cookies. It extracts cookies from HTTP

137

requests, and returns them in HTTP responses. <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> instances

138

automatically expire contained cookies when necessary. Subclasses are also

139

responsible for storing and retrieving cookies from a file or database.

140

</dd></dl>

141

142

143

144

class <code class="descclassname">http.cookiejar.</code><code class="descname">FileCookieJar</code>(filename, delayload=None, policy=None)<a class="headerlink" href="#http.cookiejar.FileCookieJar" title="Permalink to this definition">¶</a></dt>

145

146

other arguments, see the documentation for the corresponding attributes.

147

A <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> which can load cookies from, and perhaps save cookies to, a

148

file on disk. Cookies are NOT loaded from the named file until either the

149

<a class="reference internal" href="#http.cookiejar.FileCookieJar.load" title="http.cookiejar.FileCookieJar.load"><code class="xref py py-meth docutils literal">load()</code></a> or <a class="reference internal" href="#http.cookiejar.FileCookieJar.revert" title="http.cookiejar.FileCookieJar.revert"><code class="xref py py-meth docutils literal">revert()</code></a> method is called. Subclasses of this class are

150

documented in section <a class="reference internal" href="#file-cookie-jar-classes">FileCookieJar subclasses and co-operation with web browsers</a>.

151

</dd></dl>

152

153

154

155

class <code class="descclassname">http.cookiejar.</code><code class="descname">CookiePolicy</code><a class="headerlink" href="#http.cookiejar.CookiePolicy" title="Permalink to this definition">¶</a></dt>

156

<dd>This class is responsible for deciding whether each cookie should be accepted

157

from / returned to the server.

158

</dd></dl>

159

160

161

162

class <code class="descclassname">http.cookiejar.</code><code class="descname">DefaultCookiePolicy</code>(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False)<a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy" title="Permalink to this definition">¶</a></dt>

163

<dd>Constructor arguments should be passed as keyword arguments only.

164

blocked_domains is a sequence of domain names that we never accept cookies

165

from, nor return cookies to. allowed_domains if not <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>, this is a

166

sequence of the only domains for which we accept and return cookies. For all

167

other arguments, see the documentation for <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> and

168

<a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal">DefaultCookiePolicy</code></a> objects.

169

<a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal">DefaultCookiePolicy</code></a> implements the standard accept / reject rules for

170

Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies

171

received in a Set-Cookie header with a version cookie-attribute of

172

1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling

173

is turned off or <a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy.rfc2109_as_netscape" title="http.cookiejar.DefaultCookiePolicy.rfc2109_as_netscape"><code class="xref py py-attr docutils literal">rfc2109_as_netscape</code></a> is <code class="docutils literal">True</code>, RFC 2109 cookies are

174

‘downgraded’ by the <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> instance to Netscape cookies, by

175

setting the <code class="xref py py-attr docutils literal">version</code> attribute of the <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> instance to 0.

176

177

fine-tuning of policy.

178

</dd></dl>

179

180

181

182

class <code class="descclassname">http.cookiejar.</code><code class="descname">Cookie</code><a class="headerlink" href="#http.cookiejar.Cookie" title="Permalink to this definition">¶</a></dt>

183

<dd>This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not

184

expected that users of <a class="reference internal" href="#module-http.cookiejar" title="http.cookiejar: Classes for automatic handling of HTTP cookies."><code class="xref py py-mod docutils literal">http.cookiejar</code></a> construct their own <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a>

185

instances. Instead, if necessary, call <code class="xref py py-meth docutils literal">make_cookies()</code> on a

186

<a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> instance.

187

</dd></dl>

188

189

190

See also

191

192

<dt>Module <a class="reference internal" href="urllib.request.html#module-urllib.request" title="urllib.request: Extensible library for opening URLs."><code class="xref py py-mod docutils literal">urllib.request</code></a></dt>

193

<dd>URL opening with automatic cookie handling.</dd>

194

<dt>Module <a class="reference internal" href="http.cookies.html#module-http.cookies" title="http.cookies: Support for HTTP state management (cookies)."><code class="xref py py-mod docutils literal">http.cookies</code></a></dt>

195

<dd>HTTP cookie classes, principally useful for server-side code. The

196

<a class="reference internal" href="#module-http.cookiejar" title="http.cookiejar: Classes for automatic handling of HTTP cookies."><code class="xref py py-mod docutils literal">http.cookiejar</code></a> and <a class="reference internal" href="http.cookies.html#module-http.cookies" title="http.cookies: Support for HTTP state management (cookies)."><code class="xref py py-mod docutils literal">http.cookies</code></a> modules do not depend on each

197

other.</dd>

198

<dt><a class="reference external" href="https://curl.haxx.se/rfc/cookie_spec.html">https://curl.haxx.se/rfc/cookie_spec.html</a></dt>

199

<dd>The specification of the original Netscape cookie protocol. Though this is

200

still the dominant protocol, the ‘Netscape cookie protocol’ implemented by all

201

the major browsers (and <a class="reference internal" href="#module-http.cookiejar" title="http.cookiejar: Classes for automatic handling of HTTP cookies."><code class="xref py py-mod docutils literal">http.cookiejar</code></a>) only bears a passing resemblance to

202

the one sketched out in <code class="docutils literal">cookie_spec.html</code>.</dd>

203

<dt><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html">RFC 2109</a> - HTTP State Management Mechanism</dt>

204

<dd>Obsoleted by RFC 2965. Uses Set-Cookie with version=1.</dd>

205

<dt><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html">RFC 2965</a> - HTTP State Management Mechanism</dt>

206

<dd>The Netscape protocol with the bugs fixed. Uses Set-Cookie2 in

207

place of Set-Cookie. Not widely used.</dd>

208

<dt><a class="reference external" href="http://kristol.org/cookie/errata.html">http://kristol.org/cookie/errata.html</a></dt>

209

<dd>Unfinished errata to RFC 2965.</dd>

210

</dl>

211

<a class="rfc reference external" href="https://tools.ietf.org/html/rfc2964.html">RFC 2964</a> - Use of HTTP State Management

212

</div>

213

214

<h2>21.24.1. CookieJar and FileCookieJar Objects<a class="headerlink" href="#cookiejar-and-filecookiejar-objects" title="Permalink to this headline">¶</a></h2>

215

<a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> objects support the <a class="reference internal" href="../glossary.html#term-iterator">iterator</a> protocol for iterating over

216

contained <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> objects.

217

218

219

220

<code class="descclassname">CookieJar.</code><code class="descname">add_cookie_header</code>(request)<a class="headerlink" href="#http.cookiejar.CookieJar.add_cookie_header" title="Permalink to this definition">¶</a></dt>

221

<dd>Add correct Cookie header to request.

222

If policy allows (ie. the <code class="xref py py-attr docutils literal">rfc2965</code> and <code class="xref py py-attr docutils literal">hide_cookie2</code> attributes of

223

the <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a>‘s <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> instance are true and false

224

respectively), the Cookie2 header is also added when appropriate.

225

The request object (usually a <code class="xref py py-class docutils literal">urllib.request..Request</code> instance)

226

must support the methods <code class="xref py py-meth docutils literal">get_full_url()</code>, <code class="xref py py-meth docutils literal">get_host()</code>,

227

<code class="xref py py-meth docutils literal">get_type()</code>, <code class="xref py py-meth docutils literal">unverifiable()</code>, <code class="xref py py-meth docutils literal">has_header()</code>,

228

<code class="xref py py-meth docutils literal">get_header()</code>, <code class="xref py py-meth docutils literal">header_items()</code>, <code class="xref py py-meth docutils literal">add_unredirected_header()</code>

229

and <code class="xref py py-attr docutils literal">origin_req_host</code> attribute as documented by

230

<a class="reference internal" href="urllib.request.html#module-urllib.request" title="urllib.request: Extensible library for opening URLs."><code class="xref py py-mod docutils literal">urllib.request</code></a>.

231

232

Changed in version 3.3: request object needs <code class="xref py py-attr docutils literal">origin_req_host</code> attribute. Dependency on a

233

deprecated method <code class="xref py py-meth docutils literal">get_origin_req_host()</code> has been removed.

234

</div>

235

</dd></dl>

236

237

238

239

<code class="descclassname">CookieJar.</code><code class="descname">extract_cookies</code>(response, request)<a class="headerlink" href="#http.cookiejar.CookieJar.extract_cookies" title="Permalink to this definition">¶</a></dt>

240

<dd>Extract cookies from HTTP response and store them in the <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a>,

241

where allowed by policy.

242

The <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> will look for allowable Set-Cookie and

243

Set-Cookie2 headers in the response argument, and store cookies

244

as appropriate (subject to the <a class="reference internal" href="#http.cookiejar.CookiePolicy.set_ok" title="http.cookiejar.CookiePolicy.set_ok"><code class="xref py py-meth docutils literal">CookiePolicy.set_ok()</code></a> method’s approval).

245

The response object (usually the result of a call to

246

<a class="reference internal" href="urllib.request.html#urllib.request.urlopen" title="urllib.request.urlopen"><code class="xref py py-meth docutils literal">urllib.request.urlopen()</code></a>, or similar) should support an <code class="xref py py-meth docutils literal">info()</code>

247

method, which returns an <a class="reference internal" href="email.message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal">email.message.Message</code></a> instance.

248

The request object (usually a <a class="reference internal" href="urllib.request.html#urllib.request.Request" title="urllib.request.Request"><code class="xref py py-class docutils literal">urllib.request.Request</code></a> instance)

249

250

<code class="xref py py-meth docutils literal">unverifiable()</code>, and <code class="xref py py-attr docutils literal">origin_req_host</code> attribute, as documented

251

by <a class="reference internal" href="urllib.request.html#module-urllib.request" title="urllib.request: Extensible library for opening URLs."><code class="xref py py-mod docutils literal">urllib.request</code></a>. The request is used to set default values for

252

cookie-attributes as well as for checking that the cookie is allowed to be

253

set.

254

255

256

deprecated method <code class="xref py py-meth docutils literal">get_origin_req_host()</code> has been removed.

257

</div>

258

</dd></dl>

259

260

261

262

<code class="descclassname">CookieJar.</code><code class="descname">set_policy</code>(policy)<a class="headerlink" href="#http.cookiejar.CookieJar.set_policy" title="Permalink to this definition">¶</a></dt>

263

<dd>Set the <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> instance to be used.

264

</dd></dl>

265

266

267

268

<code class="descclassname">CookieJar.</code><code class="descname">make_cookies</code>(response, request)<a class="headerlink" href="#http.cookiejar.CookieJar.make_cookies" title="Permalink to this definition">¶</a></dt>

269

<dd>Return sequence of <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> objects extracted from response object.

270

See the documentation for <a class="reference internal" href="#http.cookiejar.CookieJar.extract_cookies" title="http.cookiejar.CookieJar.extract_cookies"><code class="xref py py-meth docutils literal">extract_cookies()</code></a> for the interfaces required of

271

the response and request arguments.

272

</dd></dl>

273

274

275

276

<code class="descclassname">CookieJar.</code><code class="descname">set_cookie_if_ok</code>(cookie, request)<a class="headerlink" href="#http.cookiejar.CookieJar.set_cookie_if_ok" title="Permalink to this definition">¶</a></dt>

277

<dd>Set a <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> if policy says it’s OK to do so.

278

</dd></dl>

279

280

281

282

<code class="descclassname">CookieJar.</code><code class="descname">set_cookie</code>(cookie)<a class="headerlink" href="#http.cookiejar.CookieJar.set_cookie" title="Permalink to this definition">¶</a></dt>

283

284

should be set.

285

</dd></dl>

286

287

288

289

<code class="descclassname">CookieJar.</code><code class="descname">clear</code>([domain[, path[, name]]])<a class="headerlink" href="#http.cookiejar.CookieJar.clear" title="Permalink to this definition">¶</a></dt>

290

<dd>Clear some cookies.

291

If invoked without arguments, clear all cookies. If given a single argument,

292

only cookies belonging to that domain will be removed. If given two arguments,

293

cookies belonging to the specified domain and URL path are removed. If

294

given three arguments, then the cookie with the specified domain, path and

295

name is removed.

296

Raises <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal">KeyError</code></a> if no matching cookie exists.

297

</dd></dl>

298

299

300

301

<code class="descclassname">CookieJar.</code><code class="descname">clear_session_cookies</code>()<a class="headerlink" href="#http.cookiejar.CookieJar.clear_session_cookies" title="Permalink to this definition">¶</a></dt>

302

<dd>Discard all session cookies.

303

Discards all contained cookies that have a true <code class="xref py py-attr docutils literal">discard</code> attribute

304

(usually because they had either no <code class="docutils literal">max-age</code> or <code class="docutils literal">expires</code> cookie-attribute,

305

or an explicit <code class="docutils literal">discard</code> cookie-attribute). For interactive browsers, the end

306

of a session usually corresponds to closing the browser window.

307

Note that the <code class="xref py py-meth docutils literal">save()</code> method won’t save session cookies anyway, unless you

308

ask otherwise by passing a true ignore_discard argument.

309

</dd></dl>

310

311

<a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal">FileCookieJar</code></a> implements the following additional methods:

312

313

314

<code class="descclassname">FileCookieJar.</code><code class="descname">save</code>(filename=None, ignore_discard=False, ignore_expires=False)<a class="headerlink" href="#http.cookiejar.FileCookieJar.save" title="Permalink to this definition">¶</a></dt>

315

<dd>Save cookies to a file.

316

This base class raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a>. Subclasses may leave this

317

method unimplemented.

318

filename is the name of file in which to save cookies. If filename is not

319

specified, <code class="xref py py-attr docutils literal">self.filename</code> is used (whose default is the value passed to

320

the constructor, if any); if <code class="xref py py-attr docutils literal">self.filename</code> is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>,

321

<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised.

322

ignore_discard: save even cookies set to be discarded. ignore_expires: save

323

even cookies that have expired

324

The file is overwritten if it already exists, thus wiping all the cookies it

325

contains. Saved cookies can be restored later using the <a class="reference internal" href="#http.cookiejar.FileCookieJar.load" title="http.cookiejar.FileCookieJar.load"><code class="xref py py-meth docutils literal">load()</code></a> or

326

<a class="reference internal" href="#http.cookiejar.FileCookieJar.revert" title="http.cookiejar.FileCookieJar.revert"><code class="xref py py-meth docutils literal">revert()</code></a> methods.

327

</dd></dl>

328

329

330

331

<code class="descclassname">FileCookieJar.</code><code class="descname">load</code>(filename=None, ignore_discard=False, ignore_expires=False)<a class="headerlink" href="#http.cookiejar.FileCookieJar.load" title="Permalink to this definition">¶</a></dt>

332

<dd>Load cookies from a file.

333

Old cookies are kept unless overwritten by newly loaded ones.

334

Arguments are as for <a class="reference internal" href="#http.cookiejar.FileCookieJar.save" title="http.cookiejar.FileCookieJar.save"><code class="xref py py-meth docutils literal">save()</code></a>.

335

The named file must be in the format understood by the class, or

336

<a class="reference internal" href="#http.cookiejar.LoadError" title="http.cookiejar.LoadError"><code class="xref py py-exc docutils literal">LoadError</code></a> will be raised. Also, <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> may be raised, for

337

example if the file does not exist.

338

339

Changed in version 3.3: <a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal">IOError</code></a> used to be raised, it is now an alias of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a>.

340

</div>

341

</dd></dl>

342

343

344

345

<code class="descclassname">FileCookieJar.</code><code class="descname">revert</code>(filename=None, ignore_discard=False, ignore_expires=False)<a class="headerlink" href="#http.cookiejar.FileCookieJar.revert" title="Permalink to this definition">¶</a></dt>

346

<dd>Clear all cookies and reload cookies from a saved file.

347

<a class="reference internal" href="#http.cookiejar.FileCookieJar.revert" title="http.cookiejar.FileCookieJar.revert"><code class="xref py py-meth docutils literal">revert()</code></a> can raise the same exceptions as <a class="reference internal" href="#http.cookiejar.FileCookieJar.load" title="http.cookiejar.FileCookieJar.load"><code class="xref py py-meth docutils literal">load()</code></a>. If there is a

348

failure, the object’s state will not be altered.

349

</dd></dl>

350

351

352

353

354

<code class="descclassname">FileCookieJar.</code><code class="descname">filename</code><a class="headerlink" href="#http.cookiejar.FileCookieJar.filename" title="Permalink to this definition">¶</a></dt>

355

<dd>Filename of default file in which to keep cookies. This attribute may be

356

assigned to.

357

</dd></dl>

358

359

360

361

<code class="descclassname">FileCookieJar.</code><code class="descname">delayload</code><a class="headerlink" href="#http.cookiejar.FileCookieJar.delayload" title="Permalink to this definition">¶</a></dt>

362

<dd>If true, load cookies lazily from disk. This attribute should not be assigned

363

to. This is only a hint, since this only affects performance, not behaviour

364

(unless the cookies on disk are changing). A <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> object may

365

ignore it. None of the <a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal">FileCookieJar</code></a> classes included in the standard

366

library lazily loads cookies.

367

</dd></dl>

368

369

</div>

370

371

<h2>21.24.2. FileCookieJar subclasses and co-operation with web browsers<a class="headerlink" href="#filecookiejar-subclasses-and-co-operation-with-web-browsers" title="Permalink to this headline">¶</a></h2>

372

The following <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> subclasses are provided for reading and

373

writing.

374

375

376

class <code class="descclassname">http.cookiejar.</code><code class="descname">MozillaCookieJar</code>(filename, delayload=None, policy=None)<a class="headerlink" href="#http.cookiejar.MozillaCookieJar" title="Permalink to this definition">¶</a></dt>

377

<dd>A <a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal">FileCookieJar</code></a> that can load from and save cookies to disk in the

378

Mozilla <code class="docutils literal">cookies.txt</code> file format (which is also used by the Lynx and Netscape

379

browsers).

380

381

Note

382

This loses information about RFC 2965 cookies, and also about newer or

383

non-standard cookie-attributes such as <code class="docutils literal">port</code>.

384

</div>

385

386

Warning

387

Back up your cookies before saving if you have cookies whose loss / corruption

388

would be inconvenient (there are some subtleties which may lead to slight

389

changes in the file over a load / save round-trip).

390

</div>

391

Also note that cookies saved while Mozilla is running will get clobbered by

392

Mozilla.

393

</dd></dl>

394

395

396

397

class <code class="descclassname">http.cookiejar.</code><code class="descname">LWPCookieJar</code>(filename, delayload=None, policy=None)<a class="headerlink" href="#http.cookiejar.LWPCookieJar" title="Permalink to this definition">¶</a></dt>

398

399

compatible with the libwww-perl library’s <code class="docutils literal">Set-Cookie3</code> file format. This is

400

convenient if you want to store cookies in a human-readable file.

401

</dd></dl>

402

403

</div>

404

405

<h2>21.24.3. CookiePolicy Objects<a class="headerlink" href="#cookiepolicy-objects" title="Permalink to this headline">¶</a></h2>

406

Objects implementing the <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> interface have the following

407

methods:

408

409

410

<code class="descclassname">CookiePolicy.</code><code class="descname">set_ok</code>(cookie, request)<a class="headerlink" href="#http.cookiejar.CookiePolicy.set_ok" title="Permalink to this definition">¶</a></dt>

411

<dd>Return boolean value indicating whether cookie should be accepted from server.

412

cookie is a <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> instance. request is an object

413

implementing the interface defined by the documentation for

414

<a class="reference internal" href="#http.cookiejar.CookieJar.extract_cookies" title="http.cookiejar.CookieJar.extract_cookies"><code class="xref py py-meth docutils literal">CookieJar.extract_cookies()</code></a>.

415

</dd></dl>

416

417

418

419

<code class="descclassname">CookiePolicy.</code><code class="descname">return_ok</code>(cookie, request)<a class="headerlink" href="#http.cookiejar.CookiePolicy.return_ok" title="Permalink to this definition">¶</a></dt>

420

<dd>Return boolean value indicating whether cookie should be returned to server.

421

422

implementing the interface defined by the documentation for

423

<a class="reference internal" href="#http.cookiejar.CookieJar.add_cookie_header" title="http.cookiejar.CookieJar.add_cookie_header"><code class="xref py py-meth docutils literal">CookieJar.add_cookie_header()</code></a>.

424

</dd></dl>

425

426

427

428

<code class="descclassname">CookiePolicy.</code><code class="descname">domain_return_ok</code>(domain, request)<a class="headerlink" href="#http.cookiejar.CookiePolicy.domain_return_ok" title="Permalink to this definition">¶</a></dt>

429

<dd>Return false if cookies should not be returned, given cookie domain.

430

This method is an optimization. It removes the need for checking every cookie

431

with a particular domain (which might involve reading many files). Returning

432

true from <a class="reference internal" href="#http.cookiejar.CookiePolicy.domain_return_ok" title="http.cookiejar.CookiePolicy.domain_return_ok"><code class="xref py py-meth docutils literal">domain_return_ok()</code></a> and <a class="reference internal" href="#http.cookiejar.CookiePolicy.path_return_ok" title="http.cookiejar.CookiePolicy.path_return_ok"><code class="xref py py-meth docutils literal">path_return_ok()</code></a> leaves all the

433

work to <a class="reference internal" href="#http.cookiejar.CookiePolicy.return_ok" title="http.cookiejar.CookiePolicy.return_ok"><code class="xref py py-meth docutils literal">return_ok()</code></a>.

434

If <a class="reference internal" href="#http.cookiejar.CookiePolicy.domain_return_ok" title="http.cookiejar.CookiePolicy.domain_return_ok"><code class="xref py py-meth docutils literal">domain_return_ok()</code></a> returns true for the cookie domain,

435

436

<a class="reference internal" href="#http.cookiejar.CookiePolicy.path_return_ok" title="http.cookiejar.CookiePolicy.path_return_ok"><code class="xref py py-meth docutils literal">path_return_ok()</code></a> and <a class="reference internal" href="#http.cookiejar.CookiePolicy.return_ok" title="http.cookiejar.CookiePolicy.return_ok"><code class="xref py py-meth docutils literal">return_ok()</code></a> are never called for that cookie

437

domain. If <a class="reference internal" href="#http.cookiejar.CookiePolicy.path_return_ok" title="http.cookiejar.CookiePolicy.path_return_ok"><code class="xref py py-meth docutils literal">path_return_ok()</code></a> returns true, <a class="reference internal" href="#http.cookiejar.CookiePolicy.return_ok" title="http.cookiejar.CookiePolicy.return_ok"><code class="xref py py-meth docutils literal">return_ok()</code></a> is called

438

with the <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> object itself for a full check. Otherwise,

439

<a class="reference internal" href="#http.cookiejar.CookiePolicy.return_ok" title="http.cookiejar.CookiePolicy.return_ok"><code class="xref py py-meth docutils literal">return_ok()</code></a> is never called for that cookie path.

440

Note that <a class="reference internal" href="#http.cookiejar.CookiePolicy.domain_return_ok" title="http.cookiejar.CookiePolicy.domain_return_ok"><code class="xref py py-meth docutils literal">domain_return_ok()</code></a> is called for every cookie domain, not just

441

for the request domain. For example, the function might be called with both

442

<code class="docutils literal">".example.com"</code> and <code class="docutils literal">"www.example.com"</code> if the request domain is

443

<code class="docutils literal">"www.example.com"</code>. The same goes for <a class="reference internal" href="#http.cookiejar.CookiePolicy.path_return_ok" title="http.cookiejar.CookiePolicy.path_return_ok"><code class="xref py py-meth docutils literal">path_return_ok()</code></a>.

444

The request argument is as documented for <a class="reference internal" href="#http.cookiejar.CookiePolicy.return_ok" title="http.cookiejar.CookiePolicy.return_ok"><code class="xref py py-meth docutils literal">return_ok()</code></a>.

445

</dd></dl>

446

447

448

449

<code class="descclassname">CookiePolicy.</code><code class="descname">path_return_ok</code>(path, request)<a class="headerlink" href="#http.cookiejar.CookiePolicy.path_return_ok" title="Permalink to this definition">¶</a></dt>

450

<dd>Return false if cookies should not be returned, given cookie path.

451

See the documentation for <a class="reference internal" href="#http.cookiejar.CookiePolicy.domain_return_ok" title="http.cookiejar.CookiePolicy.domain_return_ok"><code class="xref py py-meth docutils literal">domain_return_ok()</code></a>.

452

</dd></dl>

453

454

In addition to implementing the methods above, implementations of the

455

<a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> interface must also supply the following attributes,

456

indicating which protocols should be used, and how. All of these attributes may

457

be assigned to.

458

459

460

<code class="descclassname">CookiePolicy.</code><code class="descname">netscape</code><a class="headerlink" href="#http.cookiejar.CookiePolicy.netscape" title="Permalink to this definition">¶</a></dt>

461

<dd>Implement Netscape protocol.

462

</dd></dl>

463

464

465

466

<code class="descclassname">CookiePolicy.</code><code class="descname">rfc2965</code><a class="headerlink" href="#http.cookiejar.CookiePolicy.rfc2965" title="Permalink to this definition">¶</a></dt>

467

<dd>Implement RFC 2965 protocol.

468

</dd></dl>

469

470

471

472

<code class="descclassname">CookiePolicy.</code><code class="descname">hide_cookie2</code><a class="headerlink" href="#http.cookiejar.CookiePolicy.hide_cookie2" title="Permalink to this definition">¶</a></dt>

473

<dd>Don’t add Cookie2 header to requests (the presence of this header

474

indicates to the server that we understand RFC 2965 cookies).

475

</dd></dl>

476

477

The most useful way to define a <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> class is by subclassing

478

from <a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal">DefaultCookiePolicy</code></a> and overriding some or all of the methods

479

above. <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> itself may be used as a ‘null policy’ to allow

480

setting and receiving any and all cookies (this is unlikely to be useful).

481

</div>

482

483

<h2>21.24.4. DefaultCookiePolicy Objects<a class="headerlink" href="#defaultcookiepolicy-objects" title="Permalink to this headline">¶</a></h2>

484

Implements the standard rules for accepting and returning cookies.

485

Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched

486

off by default.

487

The easiest way to provide your own policy is to override this class and call

488

its methods in your overridden implementations before adding your own additional

489

checks:

490

<div class="highlight-python3"><div class="highlight"><pre>import http.cookiejar

491

class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):

492

def set_ok(self, cookie, request):

493

if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):

494

return False

495

if i_dont_want_to_store_this_cookie(cookie):

496

return False

497

return True

498

</pre></div>

499

</div>

500

In addition to the features required to implement the <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a>

501

interface, this class allows you to block and allow domains from setting and

502

receiving cookies. There are also some strictness switches that allow you to

503

tighten up the rather loose Netscape protocol rules a little bit (at the cost of

504

blocking some benign cookies).

505

A domain blacklist and whitelist is provided (both off by default). Only domains

506

not in the blacklist and present in the whitelist (if the whitelist is active)

507

participate in cookie setting and returning. Use the blocked_domains

508

constructor argument, and <code class="xref py py-meth docutils literal">blocked_domains()</code> and

509

<code class="xref py py-meth docutils literal">set_blocked_domains()</code> methods (and the corresponding argument and methods

510

for allowed_domains). If you set a whitelist, you can turn it off again by

511

setting it to <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

512

Domains in block or allow lists that do not start with a dot must equal the

513

cookie domain to be matched. For example, <code class="docutils literal">"example.com"</code> matches a blacklist

514

entry of <code class="docutils literal">"example.com"</code>, but <code class="docutils literal">"www.example.com"</code> does not. Domains that do

515

start with a dot are matched by more specific domains too. For example, both

516

<code class="docutils literal">"www.example.com"</code> and <code class="docutils literal">"www.coyote.example.com"</code> match <code class="docutils literal">".example.com"</code>

517

(but <code class="docutils literal">"example.com"</code> itself does not). IP addresses are an exception, and

518

must match exactly. For example, if blocked_domains contains <code class="docutils literal">"192.168.1.2"</code>

519

and <code class="docutils literal">".168.1.2"</code>, 192.168.1.2 is blocked, but 193.168.1.2 is not.

520

521

522

523

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">blocked_domains</code>()<a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.blocked_domains" title="Permalink to this definition">¶</a></dt>

524

<dd>Return the sequence of blocked domains (as a tuple).

525

</dd></dl>

526

527

528

529

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">set_blocked_domains</code>(blocked_domains)<a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.set_blocked_domains" title="Permalink to this definition">¶</a></dt>

530

<dd>Set the sequence of blocked domains.

531

</dd></dl>

532

533

534

535

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">is_blocked</code>(domain)<a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.is_blocked" title="Permalink to this definition">¶</a></dt>

536

<dd>Return whether domain is on the blacklist for setting or receiving cookies.

537

</dd></dl>

538

539

540

541

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">allowed_domains</code>()<a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.allowed_domains" title="Permalink to this definition">¶</a></dt>

542

<dd>Return <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>, or the sequence of allowed domains (as a tuple).

543

</dd></dl>

544

545

546

547

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">set_allowed_domains</code>(allowed_domains)<a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.set_allowed_domains" title="Permalink to this definition">¶</a></dt>

548

<dd>Set the sequence of allowed domains, or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

549

</dd></dl>

550

551

552

553

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">is_not_allowed</code>(domain)<a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.is_not_allowed" title="Permalink to this definition">¶</a></dt>

554

<dd>Return whether domain is not on the whitelist for setting or receiving

555

cookies.

556

</dd></dl>

557

558

559

all initialised from the constructor arguments of the same name, and which may

560

all be assigned to.

561

562

563

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">rfc2109_as_netscape</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.rfc2109_as_netscape" title="Permalink to this definition">¶</a></dt>

564

<dd>If true, request that the <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal">CookieJar</code></a> instance downgrade RFC 2109 cookies

565

(ie. cookies received in a Set-Cookie header with a version

566

cookie-attribute of 1) to Netscape cookies by setting the version attribute of

567

the <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> instance to 0. The default value is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>, in which

568

case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned

569

off. Therefore, RFC 2109 cookies are downgraded by default.

570

</dd></dl>

571

572

General strictness switches:

573

574

575

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">strict_domain</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_domain" title="Permalink to this definition">¶</a></dt>

576

<dd>Don’t allow sites to set two-component domains with country-code top-level

577

domains like <code class="docutils literal">.co.uk</code>, <code class="docutils literal">.gov.uk</code>, <code class="docutils literal">.co.nz</code>.etc. This is far from perfect

578

and isn’t guaranteed to work!

579

</dd></dl>

580

581

RFC 2965 protocol strictness switches:

582

583

584

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">strict_rfc2965_unverifiable</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_rfc2965_unverifiable" title="Permalink to this definition">¶</a></dt>

585

<dd>Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable

586

transaction is one resulting from a redirect or a request for an image hosted on

587

another site). If this is false, cookies are never blocked on the basis of

588

verifiability

589

</dd></dl>

590

591

Netscape protocol strictness switches:

592

593

594

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">strict_ns_unverifiable</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_unverifiable" title="Permalink to this definition">¶</a></dt>

595

<dd>Apply RFC 2965 rules on unverifiable transactions even to Netscape cookies.

596

</dd></dl>

597

598

599

600

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">strict_ns_domain</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_domain" title="Permalink to this definition">¶</a></dt>

601

<dd>Flags indicating how strict to be with domain-matching rules for Netscape

602

cookies. See below for acceptable values.

603

</dd></dl>

604

605

606

607

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">strict_ns_set_initial_dollar</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_set_initial_dollar" title="Permalink to this definition">¶</a></dt>

608

<dd>Ignore cookies in Set-Cookie: headers that have names starting with <code class="docutils literal">'$'</code>.

609

</dd></dl>

610

611

612

613

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">strict_ns_set_path</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_set_path" title="Permalink to this definition">¶</a></dt>

614

<dd>Don’t allow setting cookies whose path doesn’t path-match request URI.

615

</dd></dl>

616

617

<code class="xref py py-attr docutils literal">strict_ns_domain</code> is a collection of flags. Its value is constructed by

618

or-ing together (for example, <code class="docutils literal">DomainStrictNoDots|DomainStrictNonDomain</code> means

619

both flags are set).

620

621

622

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">DomainStrictNoDots</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainStrictNoDots" title="Permalink to this definition">¶</a></dt>

623

<dd>When setting cookies, the ‘host prefix’ must not contain a dot (eg.

624

<code class="docutils literal">www.foo.bar.com</code> can’t set a cookie for <code class="docutils literal">.bar.com</code>, because <code class="docutils literal">www.foo</code>

625

contains a dot).

626

</dd></dl>

627

628

629

630

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">DomainStrictNonDomain</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainStrictNonDomain" title="Permalink to this definition">¶</a></dt>

631

<dd>Cookies that did not explicitly specify a <code class="docutils literal">domain</code> cookie-attribute can only

632

be returned to a domain equal to the domain that set the cookie (eg.

633

<code class="docutils literal">spam.example.com</code> won’t be returned cookies from <code class="docutils literal">example.com</code> that had no

634

<code class="docutils literal">domain</code> cookie-attribute).

635

</dd></dl>

636

637

638

639

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">DomainRFC2965Match</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainRFC2965Match" title="Permalink to this definition">¶</a></dt>

640

<dd>When setting cookies, require a full RFC 2965 domain-match.

641

</dd></dl>

642

643

The following attributes are provided for convenience, and are the most useful

644

combinations of the above flags:

645

646

647

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">DomainLiberal</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainLiberal" title="Permalink to this definition">¶</a></dt>

648

<dd>Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched

649

off).

650

</dd></dl>

651

652

653

654

<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">DomainStrict</code><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainStrict" title="Permalink to this definition">¶</a></dt>

655

<dd>Equivalent to <code class="docutils literal">DomainStrictNoDots|DomainStrictNonDomain</code>.

656

</dd></dl>

657

658

</div>

659

660

<h2>21.24.5. Cookie Objects<a class="headerlink" href="#cookie-objects" title="Permalink to this headline">¶</a></h2>

661

<a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> instances have Python attributes roughly corresponding to the

662

standard cookie-attributes specified in the various cookie standards. The

663

correspondence is not one-to-one, because there are complicated rules for

664

assigning default values, because the <code class="docutils literal">max-age</code> and <code class="docutils literal">expires</code>

665

cookie-attributes contain equivalent information, and because RFC 2109 cookies

666

may be ‘downgraded’ by <a class="reference internal" href="#module-http.cookiejar" title="http.cookiejar: Classes for automatic handling of HTTP cookies."><code class="xref py py-mod docutils literal">http.cookiejar</code></a> from version 1 to version 0 (Netscape)

667

cookies.

668

Assignment to these attributes should not be necessary other than in rare

669

circumstances in a <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal">CookiePolicy</code></a> method. The class does not enforce

670

internal consistency, so you should know what you’re doing if you do that.

671

672

673

<code class="descclassname">Cookie.</code><code class="descname">version</code><a class="headerlink" href="#http.cookiejar.Cookie.version" title="Permalink to this definition">¶</a></dt>

674

<dd>Integer or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>. Netscape cookies have <a class="reference internal" href="#http.cookiejar.Cookie.version" title="http.cookiejar.Cookie.version"><code class="xref py py-attr docutils literal">version</code></a> 0. RFC 2965 and

675

RFC 2109 cookies have a <code class="docutils literal">version</code> cookie-attribute of 1. However, note that

676

677

case <a class="reference internal" href="#http.cookiejar.Cookie.version" title="http.cookiejar.Cookie.version"><code class="xref py py-attr docutils literal">version</code></a> is 0.

678

</dd></dl>

679

680

681

682

<code class="descclassname">Cookie.</code><code class="descname">name</code><a class="headerlink" href="#http.cookiejar.Cookie.name" title="Permalink to this definition">¶</a></dt>

683

<dd>Cookie name (a string).

684

</dd></dl>

685

686

687

688

<code class="descclassname">Cookie.</code><code class="descname">value</code><a class="headerlink" href="#http.cookiejar.Cookie.value" title="Permalink to this definition">¶</a></dt>

689

<dd>Cookie value (a string), or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

690

</dd></dl>

691

692

693

694

<code class="descclassname">Cookie.</code><code class="descname">port</code><a class="headerlink" href="#http.cookiejar.Cookie.port" title="Permalink to this definition">¶</a></dt>

695

<dd>String representing a port or a set of ports (eg. ‘80’, or ‘80,8080’), or

696

<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

697

</dd></dl>

698

699

700

701

<code class="descclassname">Cookie.</code><code class="descname">path</code><a class="headerlink" href="#http.cookiejar.Cookie.path" title="Permalink to this definition">¶</a></dt>

702

<dd>Cookie path (a string, eg. <code class="docutils literal">'/acme/rocket_launchers'</code>).

703

</dd></dl>

704

705

706

707

<code class="descclassname">Cookie.</code><code class="descname">secure</code><a class="headerlink" href="#http.cookiejar.Cookie.secure" title="Permalink to this definition">¶</a></dt>

708

<dd><code class="docutils literal">True</code> if cookie should only be returned over a secure connection.

709

</dd></dl>

710

711

712

713

<code class="descclassname">Cookie.</code><code class="descname">expires</code><a class="headerlink" href="#http.cookiejar.Cookie.expires" title="Permalink to this definition">¶</a></dt>

714

<dd>Integer expiry date in seconds since epoch, or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>. See also the

715

<a class="reference internal" href="#http.cookiejar.Cookie.is_expired" title="http.cookiejar.Cookie.is_expired"><code class="xref py py-meth docutils literal">is_expired()</code></a> method.

716

</dd></dl>

717

718

719

720

<code class="descclassname">Cookie.</code><code class="descname">discard</code><a class="headerlink" href="#http.cookiejar.Cookie.discard" title="Permalink to this definition">¶</a></dt>

721

<dd><code class="docutils literal">True</code> if this is a session cookie.

722

</dd></dl>

723

724

725

726

<code class="descclassname">Cookie.</code><code class="descname">comment</code><a class="headerlink" href="#http.cookiejar.Cookie.comment" title="Permalink to this definition">¶</a></dt>

727

<dd>String comment from the server explaining the function of this cookie, or

728

<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

729

</dd></dl>

730

731

732

733

<code class="descclassname">Cookie.</code><code class="descname">comment_url</code><a class="headerlink" href="#http.cookiejar.Cookie.comment_url" title="Permalink to this definition">¶</a></dt>

734

<dd>URL linking to a comment from the server explaining the function of this cookie,

735

or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

736

</dd></dl>

737

738

739

740

<code class="descclassname">Cookie.</code><code class="descname">rfc2109</code><a class="headerlink" href="#http.cookiejar.Cookie.rfc2109" title="Permalink to this definition">¶</a></dt>

741

<dd><code class="docutils literal">True</code> if this cookie was received as an RFC 2109 cookie (ie. the cookie

742

arrived in a Set-Cookie header, and the value of the Version

743

cookie-attribute in that header was 1). This attribute is provided because

744

745

which case <a class="reference internal" href="#http.cookiejar.Cookie.version" title="http.cookiejar.Cookie.version"><code class="xref py py-attr docutils literal">version</code></a> is 0.

746

</dd></dl>

747

748

749

750

<code class="descclassname">Cookie.</code><code class="descname">port_specified</code><a class="headerlink" href="#http.cookiejar.Cookie.port_specified" title="Permalink to this definition">¶</a></dt>

751

<dd><code class="docutils literal">True</code> if a port or set of ports was explicitly specified by the server (in the

752

Set-Cookie / Set-Cookie2 header).

753

</dd></dl>

754

755

756

757

<code class="descclassname">Cookie.</code><code class="descname">domain_specified</code><a class="headerlink" href="#http.cookiejar.Cookie.domain_specified" title="Permalink to this definition">¶</a></dt>

758

<dd><code class="docutils literal">True</code> if a domain was explicitly specified by the server.

759

</dd></dl>

760

761

762

763

<code class="descclassname">Cookie.</code><code class="descname">domain_initial_dot</code><a class="headerlink" href="#http.cookiejar.Cookie.domain_initial_dot" title="Permalink to this definition">¶</a></dt>

764

<dd><code class="docutils literal">True</code> if the domain explicitly specified by the server began with a dot

765

(<code class="docutils literal">'.'</code>).

766

</dd></dl>

767

768

Cookies may have additional non-standard cookie-attributes. These may be

769

accessed using the following methods:

770

771

772

<code class="descclassname">Cookie.</code><code class="descname">has_nonstandard_attr</code>(name)<a class="headerlink" href="#http.cookiejar.Cookie.has_nonstandard_attr" title="Permalink to this definition">¶</a></dt>

773

<dd>Return true if cookie has the named cookie-attribute.

774

</dd></dl>

775

776

777

778

<code class="descclassname">Cookie.</code><code class="descname">get_nonstandard_attr</code>(name, default=None)<a class="headerlink" href="#http.cookiejar.Cookie.get_nonstandard_attr" title="Permalink to this definition">¶</a></dt>

779

<dd>If cookie has the named cookie-attribute, return its value. Otherwise, return

780

default.

781

</dd></dl>

782

783

784

785

<code class="descclassname">Cookie.</code><code class="descname">set_nonstandard_attr</code>(name, value)<a class="headerlink" href="#http.cookiejar.Cookie.set_nonstandard_attr" title="Permalink to this definition">¶</a></dt>

786

<dd>Set the value of the named cookie-attribute.

787

</dd></dl>

788

789

The <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal">Cookie</code></a> class also defines the following method:

790

791

792

<code class="descclassname">Cookie.</code><code class="descname">is_expired</code>(now=None)<a class="headerlink" href="#http.cookiejar.Cookie.is_expired" title="Permalink to this definition">¶</a></dt>

793

<dd><code class="docutils literal">True</code> if cookie has passed the time at which the server requested it should

794

expire. If now is given (in seconds since the epoch), return whether the

795

cookie has expired at the specified time.

796

</dd></dl>

797

798

</div>

799

800

<h2>21.24.6. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>

801

The first example shows the most common usage of <a class="reference internal" href="#module-http.cookiejar" title="http.cookiejar: Classes for automatic handling of HTTP cookies."><code class="xref py py-mod docutils literal">http.cookiejar</code></a>:

802

<div class="highlight-python3"><div class="highlight"><pre>import http.cookiejar, urllib.request

803

cj = http.cookiejar.CookieJar()

804

opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))

805

r = opener.open("http://example.com/")

806

</pre></div>

807

</div>

808

This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx

809

cookies (assumes Unix/Netscape convention for location of the cookies file):

810

<div class="highlight-python3"><div class="highlight"><pre>import os, http.cookiejar, urllib.request

811

812

cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))

813

814

815

</pre></div>

816

</div>

817

The next example illustrates the use of <a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal">DefaultCookiePolicy</code></a>. Turn on

818

RFC 2965 cookies, be more strict about domains when setting and returning

819

Netscape cookies, and block some domains from setting cookies or having them

820

returned:

821

<div class="highlight-python3"><div class="highlight"><pre>import urllib.request

822

from http.cookiejar import CookieJar, DefaultCookiePolicy

823

policy = DefaultCookiePolicy(

824

rfc2965=True, strict_ns_domain=Policy.DomainStrict,

825

blocked_domains=["ads.net", ".ads.net"])

826

cj = CookieJar(policy)

827

828

829

</pre></div>

830

</div>

831

</div>

832

</div>

833

834

835

</div>

836

</div>

837

</div>

838

839

840

<h3><a href="../contents.html">Table Of Contents</a></h3>

841

<ul>

842

<li><a class="reference internal" href="#">21.24. <code class="docutils literal">http.cookiejar</code> — Cookie handling for HTTP clients</a><ul>

843

<li><a class="reference internal" href="#cookiejar-and-filecookiejar-objects">21.24.1. CookieJar and FileCookieJar Objects</a></li>

844

<li><a class="reference internal" href="#filecookiejar-subclasses-and-co-operation-with-web-browsers">21.24.2. FileCookieJar subclasses and co-operation with web browsers</a></li>

845

<li><a class="reference internal" href="#cookiepolicy-objects">21.24.3. CookiePolicy Objects</a></li>

846

<li><a class="reference internal" href="#defaultcookiepolicy-objects">21.24.4. DefaultCookiePolicy Objects</a></li>

847

<li><a class="reference internal" href="#cookie-objects">21.24.5. Cookie Objects</a></li>

848

<li><a class="reference internal" href="#examples">21.24.6. Examples</a></li>

849

</ul>

850

</li>

851

</ul>

852

853

<h4>Previous topic</h4>

854

<a href="http.cookies.html"

855

title="previous chapter">21.23. <code class="docutils literal">http.cookies</code> — HTTP state management</a>

856

<h4>Next topic</h4>

857

<a href="xmlrpc.html"

858

title="next chapter">21.25. <code class="docutils literal">xmlrpc</code> — XMLRPC server and client modules</a>

859

860

861

862

<li><a href="../bugs.html">Report a Bug</a></li>

863

<li><a href="../_sources/library/http.cookiejar.txt"

864

rel="nofollow">Show Source</a></li>

865

</ul>

866

</div>

867

</div>

868

</div>

869

870

</div>

871

872

<h3>Navigation</h3>

873

<ul>

874

875

<a href="../genindex.html" title="General Index"

876

>index</a></li>

877

878

<a href="../py-modindex.html" title="Python Module Index"

879

>modules</a> |</li>

880

881

<a href="xmlrpc.html" title="21.25. xmlrpc — XMLRPC server and client modules"

882

>next</a> |</li>

883

884

<a href="http.cookies.html" title="21.23. http.cookies — HTTP state management"

885

>previous</a> |</li>

886

<li><img src="../_static/py.png" alt=""

887

style="vertical-align: middle; margin-top: -1px"/></li>

888

<li><a href="https://www.python.org/">Python</a> »</li>

889

<li>

890

3.5.2

891

<a href="../index.html">Documentation </a> »

892

</li>

893

894

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

895

<li class="nav-item nav-item-2"><a href="internet.html" >21. Internet Protocols and Support</a> »</li>

896

897

898

899

900

901

902

903

904

905

</form>

906

</div>

907

908

909

</li>

910

911

</ul>

912

</div>

913

914

915

916

The Python Software Foundation is a non-profit corporation.

917

<a href="https://www.python.org/psf/donations/">Please donate.</a>

918

919

Last updated on Sep 23, 2016.

920

<a href="../bugs.html">Found a bug</a>?

921

922

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

923

</div>

924

925

</body>

926

</html>

b'\\ No newline at end of file'

Older »