932 lines
94 KiB
HTML
932 lines
94 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>http.cookiejar — Cookie handling for HTTP clients — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 documentation"
|
|||
|
|
href="../_static/opensearch.xml"/>
|
|||
|
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
|
<link rel="next" title="xmlrpc — XMLRPC server and client modules" href="xmlrpc.html" />
|
|||
|
|
<link rel="prev" title="http.cookies — HTTP state management" href="http.cookies.html" />
|
|||
|
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/library/http.cookiejar.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="xmlrpc.html" title="xmlrpc — XMLRPC server and client modules"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="http.cookies.html" title="http.cookies — HTTP state management"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="internet.html" accesskey="U">Internet Protocols and Support</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="module-http.cookiejar">
|
|||
|
|
<span id="http-cookiejar-cookie-handling-for-http-clients"></span><h1><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 notranslate"><span class="pre">http.cookiejar</span></code></a> — Cookie handling for HTTP clients<a class="headerlink" href="#module-http.cookiejar" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/http/cookiejar.py">Lib/http/cookiejar.py</a></p>
|
|||
|
|
<hr class="docutils" />
|
|||
|
|
<p>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 notranslate"><span class="pre">http.cookiejar</span></code></a> module defines classes for automatic handling of HTTP
|
|||
|
|
cookies. It is useful for accessing web sites that require small pieces of data
|
|||
|
|
– <em class="dfn">cookies</em> – to be set on the client machine by an HTTP response from a
|
|||
|
|
web server, and then returned to the server in later HTTP requests.</p>
|
|||
|
|
<p>Both the regular Netscape cookie protocol and the protocol defined by
|
|||
|
|
<span class="target" id="index-0"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> are handled. RFC 2965 handling is switched off by default.
|
|||
|
|
<span class="target" id="index-1"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies are parsed as Netscape cookies and subsequently treated
|
|||
|
|
either as Netscape or RFC 2965 cookies according to the ‘policy’ in effect.
|
|||
|
|
Note that the great majority of cookies on the Internet are Netscape cookies.
|
|||
|
|
<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 notranslate"><span class="pre">http.cookiejar</span></code></a> attempts to follow the de-facto Netscape cookie protocol (which
|
|||
|
|
differs substantially from that set out in the original Netscape specification),
|
|||
|
|
including taking note of the <code class="docutils literal notranslate"><span class="pre">max-age</span></code> and <code class="docutils literal notranslate"><span class="pre">port</span></code> cookie-attributes
|
|||
|
|
introduced with RFC 2965.</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>The various named parameters found in <em class="mailheader">Set-Cookie</em> and
|
|||
|
|
<em class="mailheader">Set-Cookie2</em> headers (eg. <code class="docutils literal notranslate"><span class="pre">domain</span></code> and <code class="docutils literal notranslate"><span class="pre">expires</span></code>) are
|
|||
|
|
conventionally referred to as <em class="dfn">attributes</em>. To distinguish them from
|
|||
|
|
Python attributes, the documentation for this module uses the term
|
|||
|
|
<em class="dfn">cookie-attribute</em> instead.</p>
|
|||
|
|
</div>
|
|||
|
|
<p>The module defines the following exception:</p>
|
|||
|
|
<dl class="exception">
|
|||
|
|
<dt id="http.cookiejar.LoadError">
|
|||
|
|
<em class="property">exception </em><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>
|
|||
|
|
<dd><p>Instances of <a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileCookieJar</span></code></a> raise this exception on failure to load
|
|||
|
|
cookies from a file. <a class="reference internal" href="#http.cookiejar.LoadError" title="http.cookiejar.LoadError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LoadError</span></code></a> is a subclass of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>LoadError was made a subclass of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> instead of
|
|||
|
|
<a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>The following classes are provided:</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="http.cookiejar.CookieJar">
|
|||
|
|
<em class="property">class </em><code class="descclassname">http.cookiejar.</code><code class="descname">CookieJar</code><span class="sig-paren">(</span><em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p><em>policy</em> 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 notranslate"><span class="pre">CookiePolicy</span></code></a> interface.</p>
|
|||
|
|
<p>The <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> class stores HTTP cookies. It extracts cookies from HTTP
|
|||
|
|
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 notranslate"><span class="pre">CookieJar</span></code></a> instances
|
|||
|
|
automatically expire contained cookies when necessary. Subclasses are also
|
|||
|
|
responsible for storing and retrieving cookies from a file or database.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="http.cookiejar.FileCookieJar">
|
|||
|
|
<em class="property">class </em><code class="descclassname">http.cookiejar.</code><code class="descname">FileCookieJar</code><span class="sig-paren">(</span><em>filename</em>, <em>delayload=None</em>, <em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p><em>policy</em> 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 notranslate"><span class="pre">CookiePolicy</span></code></a> interface. For the
|
|||
|
|
other arguments, see the documentation for the corresponding attributes.</p>
|
|||
|
|
<p>A <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> which can load cookies from, and perhaps save cookies to, a
|
|||
|
|
file on disk. Cookies are <strong>NOT</strong> loaded from the named file until either the
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.FileCookieJar.load" title="http.cookiejar.FileCookieJar.load"><code class="xref py py-meth docutils literal notranslate"><span class="pre">load()</span></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 notranslate"><span class="pre">revert()</span></code></a> method is called. Subclasses of this class are
|
|||
|
|
documented in section <a class="reference internal" href="#file-cookie-jar-classes"><span class="std std-ref">FileCookieJar subclasses and co-operation with web browsers</span></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy">
|
|||
|
|
<em class="property">class </em><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>
|
|||
|
|
<dd><p>This class is responsible for deciding whether each cookie should be accepted
|
|||
|
|
from / returned to the server.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy">
|
|||
|
|
<em class="property">class </em><code class="descclassname">http.cookiejar.</code><code class="descname">DefaultCookiePolicy</code><span class="sig-paren">(</span><em>blocked_domains=None</em>, <em>allowed_domains=None</em>, <em>netscape=True</em>, <em>rfc2965=False</em>, <em>rfc2109_as_netscape=None</em>, <em>hide_cookie2=False</em>, <em>strict_domain=False</em>, <em>strict_rfc2965_unverifiable=True</em>, <em>strict_ns_unverifiable=False</em>, <em>strict_ns_domain=DefaultCookiePolicy.DomainLiberal</em>, <em>strict_ns_set_initial_dollar=False</em>, <em>strict_ns_set_path=False</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Constructor arguments should be passed as keyword arguments only.
|
|||
|
|
<em>blocked_domains</em> is a sequence of domain names that we never accept cookies
|
|||
|
|
from, nor return cookies to. <em>allowed_domains</em> if not <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>, this is a
|
|||
|
|
sequence of the only domains for which we accept and return cookies. For all
|
|||
|
|
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 notranslate"><span class="pre">CookiePolicy</span></code></a> and
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code></a> objects.</p>
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code></a> implements the standard accept / reject rules for
|
|||
|
|
Netscape and <span class="target" id="index-2"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies. By default, <span class="target" id="index-3"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies (ie. cookies
|
|||
|
|
received in a <em class="mailheader">Set-Cookie</em> header with a version cookie-attribute of
|
|||
|
|
1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
|
|||
|
|
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 notranslate"><span class="pre">rfc2109_as_netscape</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, RFC 2109 cookies are
|
|||
|
|
‘downgraded’ by the <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> instance to Netscape cookies, by
|
|||
|
|
setting the <code class="xref py py-attr docutils literal notranslate"><span class="pre">version</span></code> attribute of the <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> instance to 0.
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code></a> also provides some parameters to allow some
|
|||
|
|
fine-tuning of policy.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="http.cookiejar.Cookie">
|
|||
|
|
<em class="property">class </em><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>
|
|||
|
|
<dd><p>This class represents Netscape, <span class="target" id="index-4"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> and <span class="target" id="index-5"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies. It is not
|
|||
|
|
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 notranslate"><span class="pre">http.cookiejar</span></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 notranslate"><span class="pre">Cookie</span></code></a>
|
|||
|
|
instances. Instead, if necessary, call <code class="xref py py-meth docutils literal notranslate"><span class="pre">make_cookies()</span></code> on a
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> instance.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<div class="admonition seealso">
|
|||
|
|
<p class="admonition-title">See also</p>
|
|||
|
|
<dl class="simple">
|
|||
|
|
<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 notranslate"><span class="pre">urllib.request</span></code></a></dt><dd><p>URL opening with automatic cookie handling.</p>
|
|||
|
|
</dd>
|
|||
|
|
<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 notranslate"><span class="pre">http.cookies</span></code></a></dt><dd><p>HTTP cookie classes, principally useful for server-side code. 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 notranslate"><span class="pre">http.cookiejar</span></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 notranslate"><span class="pre">http.cookies</span></code></a> modules do not depend on each
|
|||
|
|
other.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><a class="reference external" href="https://curl.haxx.se/rfc/cookie_spec.html">https://curl.haxx.se/rfc/cookie_spec.html</a></dt><dd><p>The specification of the original Netscape cookie protocol. Though this is
|
|||
|
|
still the dominant protocol, the ‘Netscape cookie protocol’ implemented by all
|
|||
|
|
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 notranslate"><span class="pre">http.cookiejar</span></code></a>) only bears a passing resemblance to
|
|||
|
|
the one sketched out in <code class="docutils literal notranslate"><span class="pre">cookie_spec.html</span></code>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><span class="target" id="index-6"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> - HTTP State Management Mechanism</dt><dd><p>Obsoleted by <span class="target" id="index-7"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a>. Uses <em class="mailheader">Set-Cookie</em> with version=1.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><span class="target" id="index-8"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> - HTTP State Management Mechanism</dt><dd><p>The Netscape protocol with the bugs fixed. Uses <em class="mailheader">Set-Cookie2</em> in
|
|||
|
|
place of <em class="mailheader">Set-Cookie</em>. Not widely used.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><a class="reference external" href="http://kristol.org/cookie/errata.html">http://kristol.org/cookie/errata.html</a></dt><dd><p>Unfinished errata to <span class="target" id="index-9"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a>.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><span class="target" id="index-10"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2964.html"><strong>RFC 2964</strong></a> - Use of HTTP State Management</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="cookiejar-and-filecookiejar-objects">
|
|||
|
|
<span id="cookie-jar-objects"></span><h2>CookieJar and FileCookieJar Objects<a class="headerlink" href="#cookiejar-and-filecookiejar-objects" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> objects support the <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> protocol for iterating over
|
|||
|
|
contained <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> objects.</p>
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> has the following methods:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.add_cookie_header">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">add_cookie_header</code><span class="sig-paren">(</span><em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.add_cookie_header" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Add correct <em class="mailheader">Cookie</em> header to <em>request</em>.</p>
|
|||
|
|
<p>If policy allows (ie. the <code class="xref py py-attr docutils literal notranslate"><span class="pre">rfc2965</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">hide_cookie2</span></code> attributes of
|
|||
|
|
the <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a>’s <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookiePolicy</span></code></a> instance are true and false
|
|||
|
|
respectively), the <em class="mailheader">Cookie2</em> header is also added when appropriate.</p>
|
|||
|
|
<p>The <em>request</em> object (usually a <code class="xref py py-class docutils literal notranslate"><span class="pre">urllib.request..Request</span></code> instance)
|
|||
|
|
must support the methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_full_url()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_host()</span></code>,
|
|||
|
|
<code class="xref py py-meth docutils literal notranslate"><span class="pre">get_type()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">unverifiable()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">has_header()</span></code>,
|
|||
|
|
<code class="xref py py-meth docutils literal notranslate"><span class="pre">get_header()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">header_items()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_unredirected_header()</span></code>
|
|||
|
|
and <code class="xref py py-attr docutils literal notranslate"><span class="pre">origin_req_host</span></code> attribute as documented 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 notranslate"><span class="pre">urllib.request</span></code></a>.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>request</em> object needs <code class="xref py py-attr docutils literal notranslate"><span class="pre">origin_req_host</span></code> attribute. Dependency on a
|
|||
|
|
deprecated method <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_origin_req_host()</span></code> has been removed.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.extract_cookies">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">extract_cookies</code><span class="sig-paren">(</span><em>response</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.extract_cookies" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Extract cookies from HTTP <em>response</em> 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 notranslate"><span class="pre">CookieJar</span></code></a>,
|
|||
|
|
where allowed by policy.</p>
|
|||
|
|
<p>The <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> will look for allowable <em class="mailheader">Set-Cookie</em> and
|
|||
|
|
<em class="mailheader">Set-Cookie2</em> headers in the <em>response</em> argument, and store cookies
|
|||
|
|
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 notranslate"><span class="pre">CookiePolicy.set_ok()</span></code></a> method’s approval).</p>
|
|||
|
|
<p>The <em>response</em> object (usually the result of a call to
|
|||
|
|
<a class="reference internal" href="urllib.request.html#urllib.request.urlopen" title="urllib.request.urlopen"><code class="xref py py-meth docutils literal notranslate"><span class="pre">urllib.request.urlopen()</span></code></a>, or similar) should support an <code class="xref py py-meth docutils literal notranslate"><span class="pre">info()</span></code>
|
|||
|
|
method, which returns an <a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.message.Message</span></code></a> instance.</p>
|
|||
|
|
<p>The <em>request</em> 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 notranslate"><span class="pre">urllib.request.Request</span></code></a> instance)
|
|||
|
|
must support the methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_full_url()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_host()</span></code>,
|
|||
|
|
<code class="xref py py-meth docutils literal notranslate"><span class="pre">unverifiable()</span></code>, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">origin_req_host</span></code> attribute, as documented
|
|||
|
|
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 notranslate"><span class="pre">urllib.request</span></code></a>. The request is used to set default values for
|
|||
|
|
cookie-attributes as well as for checking that the cookie is allowed to be
|
|||
|
|
set.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>request</em> object needs <code class="xref py py-attr docutils literal notranslate"><span class="pre">origin_req_host</span></code> attribute. Dependency on a
|
|||
|
|
deprecated method <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_origin_req_host()</span></code> has been removed.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.set_policy">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">set_policy</code><span class="sig-paren">(</span><em>policy</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.set_policy" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookiePolicy</span></code></a> instance to be used.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.make_cookies">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">make_cookies</code><span class="sig-paren">(</span><em>response</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.make_cookies" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return sequence of <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> objects extracted from <em>response</em> object.</p>
|
|||
|
|
<p>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 notranslate"><span class="pre">extract_cookies()</span></code></a> for the interfaces required of
|
|||
|
|
the <em>response</em> and <em>request</em> arguments.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.set_cookie_if_ok">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">set_cookie_if_ok</code><span class="sig-paren">(</span><em>cookie</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.set_cookie_if_ok" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set a <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> if policy says it’s OK to do so.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.set_cookie">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">set_cookie</code><span class="sig-paren">(</span><em>cookie</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.set_cookie" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set a <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a>, without checking with policy to see whether or not it
|
|||
|
|
should be set.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.clear">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">clear</code><span class="sig-paren">(</span><span class="optional">[</span><em>domain</em><span class="optional">[</span>, <em>path</em><span class="optional">[</span>, <em>name</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.clear" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Clear some cookies.</p>
|
|||
|
|
<p>If invoked without arguments, clear all cookies. If given a single argument,
|
|||
|
|
only cookies belonging to that <em>domain</em> will be removed. If given two arguments,
|
|||
|
|
cookies belonging to the specified <em>domain</em> and URL <em>path</em> are removed. If
|
|||
|
|
given three arguments, then the cookie with the specified <em>domain</em>, <em>path</em> and
|
|||
|
|
<em>name</em> is removed.</p>
|
|||
|
|
<p>Raises <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> if no matching cookie exists.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookieJar.clear_session_cookies">
|
|||
|
|
<code class="descclassname">CookieJar.</code><code class="descname">clear_session_cookies</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.clear_session_cookies" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Discard all session cookies.</p>
|
|||
|
|
<p>Discards all contained cookies that have a true <code class="xref py py-attr docutils literal notranslate"><span class="pre">discard</span></code> attribute
|
|||
|
|
(usually because they had either no <code class="docutils literal notranslate"><span class="pre">max-age</span></code> or <code class="docutils literal notranslate"><span class="pre">expires</span></code> cookie-attribute,
|
|||
|
|
or an explicit <code class="docutils literal notranslate"><span class="pre">discard</span></code> cookie-attribute). For interactive browsers, the end
|
|||
|
|
of a session usually corresponds to closing the browser window.</p>
|
|||
|
|
<p>Note that the <code class="xref py py-meth docutils literal notranslate"><span class="pre">save()</span></code> method won’t save session cookies anyway, unless you
|
|||
|
|
ask otherwise by passing a true <em>ignore_discard</em> argument.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileCookieJar</span></code></a> implements the following additional methods:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.FileCookieJar.save">
|
|||
|
|
<code class="descclassname">FileCookieJar.</code><code class="descname">save</code><span class="sig-paren">(</span><em>filename=None</em>, <em>ignore_discard=False</em>, <em>ignore_expires=False</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar.save" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Save cookies to a file.</p>
|
|||
|
|
<p>This base class raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>. Subclasses may leave this
|
|||
|
|
method unimplemented.</p>
|
|||
|
|
<p><em>filename</em> is the name of file in which to save cookies. If <em>filename</em> is not
|
|||
|
|
specified, <code class="xref py py-attr docutils literal notranslate"><span class="pre">self.filename</span></code> is used (whose default is the value passed to
|
|||
|
|
the constructor, if any); if <code class="xref py py-attr docutils literal notranslate"><span class="pre">self.filename</span></code> is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>,
|
|||
|
|
<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
|
|||
|
|
<p><em>ignore_discard</em>: save even cookies set to be discarded. <em>ignore_expires</em>: save
|
|||
|
|
even cookies that have expired</p>
|
|||
|
|
<p>The file is overwritten if it already exists, thus wiping all the cookies it
|
|||
|
|
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 notranslate"><span class="pre">load()</span></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 notranslate"><span class="pre">revert()</span></code></a> methods.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.FileCookieJar.load">
|
|||
|
|
<code class="descclassname">FileCookieJar.</code><code class="descname">load</code><span class="sig-paren">(</span><em>filename=None</em>, <em>ignore_discard=False</em>, <em>ignore_expires=False</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar.load" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Load cookies from a file.</p>
|
|||
|
|
<p>Old cookies are kept unless overwritten by newly loaded ones.</p>
|
|||
|
|
<p>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 notranslate"><span class="pre">save()</span></code></a>.</p>
|
|||
|
|
<p>The named file must be in the format understood by the class, or
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.LoadError" title="http.cookiejar.LoadError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LoadError</span></code></a> will be raised. Also, <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> may be raised, for
|
|||
|
|
example if the file does not exist.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span><a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></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 notranslate"><span class="pre">OSError</span></code></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.FileCookieJar.revert">
|
|||
|
|
<code class="descclassname">FileCookieJar.</code><code class="descname">revert</code><span class="sig-paren">(</span><em>filename=None</em>, <em>ignore_discard=False</em>, <em>ignore_expires=False</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar.revert" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Clear all cookies and reload cookies from a saved file.</p>
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.FileCookieJar.revert" title="http.cookiejar.FileCookieJar.revert"><code class="xref py py-meth docutils literal notranslate"><span class="pre">revert()</span></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 notranslate"><span class="pre">load()</span></code></a>. If there is a
|
|||
|
|
failure, the object’s state will not be altered.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileCookieJar</span></code></a> instances have the following public attributes:</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.FileCookieJar.filename">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Filename of default file in which to keep cookies. This attribute may be
|
|||
|
|
assigned to.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.FileCookieJar.delayload">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>If true, load cookies lazily from disk. This attribute should not be assigned
|
|||
|
|
to. This is only a hint, since this only affects performance, not behaviour
|
|||
|
|
(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 notranslate"><span class="pre">CookieJar</span></code></a> object may
|
|||
|
|
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 notranslate"><span class="pre">FileCookieJar</span></code></a> classes included in the standard
|
|||
|
|
library lazily loads cookies.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="filecookiejar-subclasses-and-co-operation-with-web-browsers">
|
|||
|
|
<span id="file-cookie-jar-classes"></span><h2>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>
|
|||
|
|
<p>The following <a class="reference internal" href="#http.cookiejar.CookieJar" title="http.cookiejar.CookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code></a> subclasses are provided for reading and
|
|||
|
|
writing.</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="http.cookiejar.MozillaCookieJar">
|
|||
|
|
<em class="property">class </em><code class="descclassname">http.cookiejar.</code><code class="descname">MozillaCookieJar</code><span class="sig-paren">(</span><em>filename</em>, <em>delayload=None</em>, <em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.MozillaCookieJar" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A <a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileCookieJar</span></code></a> that can load from and save cookies to disk in the
|
|||
|
|
Mozilla <code class="docutils literal notranslate"><span class="pre">cookies.txt</span></code> file format (which is also used by the Lynx and Netscape
|
|||
|
|
browsers).</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>This loses information about <span class="target" id="index-11"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies, and also about newer or
|
|||
|
|
non-standard cookie-attributes such as <code class="docutils literal notranslate"><span class="pre">port</span></code>.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="admonition warning">
|
|||
|
|
<p class="admonition-title">Warning</p>
|
|||
|
|
<p>Back up your cookies before saving if you have cookies whose loss / corruption
|
|||
|
|
would be inconvenient (there are some subtleties which may lead to slight
|
|||
|
|
changes in the file over a load / save round-trip).</p>
|
|||
|
|
</div>
|
|||
|
|
<p>Also note that cookies saved while Mozilla is running will get clobbered by
|
|||
|
|
Mozilla.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="http.cookiejar.LWPCookieJar">
|
|||
|
|
<em class="property">class </em><code class="descclassname">http.cookiejar.</code><code class="descname">LWPCookieJar</code><span class="sig-paren">(</span><em>filename</em>, <em>delayload=None</em>, <em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.LWPCookieJar" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A <a class="reference internal" href="#http.cookiejar.FileCookieJar" title="http.cookiejar.FileCookieJar"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileCookieJar</span></code></a> that can load from and save cookies to disk in format
|
|||
|
|
compatible with the libwww-perl library’s <code class="docutils literal notranslate"><span class="pre">Set-Cookie3</span></code> file format. This is
|
|||
|
|
convenient if you want to store cookies in a human-readable file.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="cookiepolicy-objects">
|
|||
|
|
<span id="cookie-policy-objects"></span><h2>CookiePolicy Objects<a class="headerlink" href="#cookiepolicy-objects" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Objects implementing the <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookiePolicy</span></code></a> interface have the following
|
|||
|
|
methods:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy.set_ok">
|
|||
|
|
<code class="descclassname">CookiePolicy.</code><code class="descname">set_ok</code><span class="sig-paren">(</span><em>cookie</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.set_ok" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return boolean value indicating whether cookie should be accepted from server.</p>
|
|||
|
|
<p><em>cookie</em> is a <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> instance. <em>request</em> is an object
|
|||
|
|
implementing the interface defined by 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 notranslate"><span class="pre">CookieJar.extract_cookies()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy.return_ok">
|
|||
|
|
<code class="descclassname">CookiePolicy.</code><code class="descname">return_ok</code><span class="sig-paren">(</span><em>cookie</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.return_ok" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return boolean value indicating whether cookie should be returned to server.</p>
|
|||
|
|
<p><em>cookie</em> is a <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> instance. <em>request</em> is an object
|
|||
|
|
implementing the interface defined by the documentation for
|
|||
|
|
<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 notranslate"><span class="pre">CookieJar.add_cookie_header()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy.domain_return_ok">
|
|||
|
|
<code class="descclassname">CookiePolicy.</code><code class="descname">domain_return_ok</code><span class="sig-paren">(</span><em>domain</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.domain_return_ok" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return false if cookies should not be returned, given cookie domain.</p>
|
|||
|
|
<p>This method is an optimization. It removes the need for checking every cookie
|
|||
|
|
with a particular domain (which might involve reading many files). Returning
|
|||
|
|
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 notranslate"><span class="pre">domain_return_ok()</span></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 notranslate"><span class="pre">path_return_ok()</span></code></a> leaves all the
|
|||
|
|
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 notranslate"><span class="pre">return_ok()</span></code></a>.</p>
|
|||
|
|
<p>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 notranslate"><span class="pre">domain_return_ok()</span></code></a> returns true for the cookie domain,
|
|||
|
|
<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 notranslate"><span class="pre">path_return_ok()</span></code></a> is called for the cookie path. Otherwise,
|
|||
|
|
<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 notranslate"><span class="pre">path_return_ok()</span></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 notranslate"><span class="pre">return_ok()</span></code></a> are never called for that cookie
|
|||
|
|
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 notranslate"><span class="pre">path_return_ok()</span></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 notranslate"><span class="pre">return_ok()</span></code></a> is called
|
|||
|
|
with the <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> object itself for a full check. Otherwise,
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.CookiePolicy.return_ok" title="http.cookiejar.CookiePolicy.return_ok"><code class="xref py py-meth docutils literal notranslate"><span class="pre">return_ok()</span></code></a> is never called for that cookie path.</p>
|
|||
|
|
<p>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 notranslate"><span class="pre">domain_return_ok()</span></code></a> is called for every <em>cookie</em> domain, not just
|
|||
|
|
for the <em>request</em> domain. For example, the function might be called with both
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">".example.com"</span></code> and <code class="docutils literal notranslate"><span class="pre">"www.example.com"</span></code> if the request domain is
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">"www.example.com"</span></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 notranslate"><span class="pre">path_return_ok()</span></code></a>.</p>
|
|||
|
|
<p>The <em>request</em> 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 notranslate"><span class="pre">return_ok()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy.path_return_ok">
|
|||
|
|
<code class="descclassname">CookiePolicy.</code><code class="descname">path_return_ok</code><span class="sig-paren">(</span><em>path</em>, <em>request</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.path_return_ok" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return false if cookies should not be returned, given cookie path.</p>
|
|||
|
|
<p>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 notranslate"><span class="pre">domain_return_ok()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>In addition to implementing the methods above, implementations of the
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookiePolicy</span></code></a> interface must also supply the following attributes,
|
|||
|
|
indicating which protocols should be used, and how. All of these attributes may
|
|||
|
|
be assigned to.</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy.netscape">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Implement Netscape protocol.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy.rfc2965">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Implement <span class="target" id="index-12"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> protocol.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.CookiePolicy.hide_cookie2">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Don’t add <em class="mailheader">Cookie2</em> header to requests (the presence of this header
|
|||
|
|
indicates to the server that we understand <span class="target" id="index-13"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>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 notranslate"><span class="pre">CookiePolicy</span></code></a> class is by subclassing
|
|||
|
|
from <a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code></a> and overriding some or all of the methods
|
|||
|
|
above. <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookiePolicy</span></code></a> itself may be used as a ‘null policy’ to allow
|
|||
|
|
setting and receiving any and all cookies (this is unlikely to be useful).</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="defaultcookiepolicy-objects">
|
|||
|
|
<span id="default-cookie-policy-objects"></span><h2>DefaultCookiePolicy Objects<a class="headerlink" href="#defaultcookiepolicy-objects" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Implements the standard rules for accepting and returning cookies.</p>
|
|||
|
|
<p>Both <span class="target" id="index-14"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> and Netscape cookies are covered. RFC 2965 handling is switched
|
|||
|
|
off by default.</p>
|
|||
|
|
<p>The easiest way to provide your own policy is to override this class and call
|
|||
|
|
its methods in your overridden implementations before adding your own additional
|
|||
|
|
checks:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">http.cookiejar</span>
|
|||
|
|
<span class="k">class</span> <span class="nc">MyCookiePolicy</span><span class="p">(</span><span class="n">http</span><span class="o">.</span><span class="n">cookiejar</span><span class="o">.</span><span class="n">DefaultCookiePolicy</span><span class="p">):</span>
|
|||
|
|
<span class="k">def</span> <span class="nf">set_ok</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cookie</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
|
|||
|
|
<span class="k">if</span> <span class="ow">not</span> <span class="n">http</span><span class="o">.</span><span class="n">cookiejar</span><span class="o">.</span><span class="n">DefaultCookiePolicy</span><span class="o">.</span><span class="n">set_ok</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cookie</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
|
|||
|
|
<span class="k">return</span> <span class="kc">False</span>
|
|||
|
|
<span class="k">if</span> <span class="n">i_dont_want_to_store_this_cookie</span><span class="p">(</span><span class="n">cookie</span><span class="p">):</span>
|
|||
|
|
<span class="k">return</span> <span class="kc">False</span>
|
|||
|
|
<span class="k">return</span> <span class="kc">True</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>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 notranslate"><span class="pre">CookiePolicy</span></code></a>
|
|||
|
|
interface, this class allows you to block and allow domains from setting and
|
|||
|
|
receiving cookies. There are also some strictness switches that allow you to
|
|||
|
|
tighten up the rather loose Netscape protocol rules a little bit (at the cost of
|
|||
|
|
blocking some benign cookies).</p>
|
|||
|
|
<p>A domain blacklist and whitelist is provided (both off by default). Only domains
|
|||
|
|
not in the blacklist and present in the whitelist (if the whitelist is active)
|
|||
|
|
participate in cookie setting and returning. Use the <em>blocked_domains</em>
|
|||
|
|
constructor argument, and <code class="xref py py-meth docutils literal notranslate"><span class="pre">blocked_domains()</span></code> and
|
|||
|
|
<code class="xref py py-meth docutils literal notranslate"><span class="pre">set_blocked_domains()</span></code> methods (and the corresponding argument and methods
|
|||
|
|
for <em>allowed_domains</em>). If you set a whitelist, you can turn it off again by
|
|||
|
|
setting it to <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>
|
|||
|
|
<p>Domains in block or allow lists that do not start with a dot must equal the
|
|||
|
|
cookie domain to be matched. For example, <code class="docutils literal notranslate"><span class="pre">"example.com"</span></code> matches a blacklist
|
|||
|
|
entry of <code class="docutils literal notranslate"><span class="pre">"example.com"</span></code>, but <code class="docutils literal notranslate"><span class="pre">"www.example.com"</span></code> does not. Domains that do
|
|||
|
|
start with a dot are matched by more specific domains too. For example, both
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">"www.example.com"</span></code> and <code class="docutils literal notranslate"><span class="pre">"www.coyote.example.com"</span></code> match <code class="docutils literal notranslate"><span class="pre">".example.com"</span></code>
|
|||
|
|
(but <code class="docutils literal notranslate"><span class="pre">"example.com"</span></code> itself does not). IP addresses are an exception, and
|
|||
|
|
must match exactly. For example, if blocked_domains contains <code class="docutils literal notranslate"><span class="pre">"192.168.1.2"</span></code>
|
|||
|
|
and <code class="docutils literal notranslate"><span class="pre">".168.1.2"</span></code>, 192.168.1.2 is blocked, but 193.168.1.2 is not.</p>
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code></a> implements the following additional methods:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.blocked_domains">
|
|||
|
|
<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">blocked_domains</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.blocked_domains" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the sequence of blocked domains (as a tuple).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.set_blocked_domains">
|
|||
|
|
<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">set_blocked_domains</code><span class="sig-paren">(</span><em>blocked_domains</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.set_blocked_domains" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the sequence of blocked domains.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.is_blocked">
|
|||
|
|
<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">is_blocked</code><span class="sig-paren">(</span><em>domain</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.is_blocked" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return whether <em>domain</em> is on the blacklist for setting or receiving cookies.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.allowed_domains">
|
|||
|
|
<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">allowed_domains</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.allowed_domains" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>, or the sequence of allowed domains (as a tuple).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.set_allowed_domains">
|
|||
|
|
<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">set_allowed_domains</code><span class="sig-paren">(</span><em>allowed_domains</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.set_allowed_domains" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>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 notranslate"><span class="pre">None</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.is_not_allowed">
|
|||
|
|
<code class="descclassname">DefaultCookiePolicy.</code><code class="descname">is_not_allowed</code><span class="sig-paren">(</span><em>domain</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.is_not_allowed" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return whether <em>domain</em> is not on the whitelist for setting or receiving
|
|||
|
|
cookies.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy" title="http.cookiejar.DefaultCookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code></a> instances have the following attributes, which are
|
|||
|
|
all initialised from the constructor arguments of the same name, and which may
|
|||
|
|
all be assigned to.</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.rfc2109_as_netscape">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>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 notranslate"><span class="pre">CookieJar</span></code></a> instance downgrade <span class="target" id="index-15"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies
|
|||
|
|
(ie. cookies received in a <em class="mailheader">Set-Cookie</em> header with a version
|
|||
|
|
cookie-attribute of 1) to Netscape cookies by setting the version attribute of
|
|||
|
|
the <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></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 notranslate"><span class="pre">None</span></code></a>, in which
|
|||
|
|
case RFC 2109 cookies are downgraded if and only if <span class="target" id="index-16"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> handling is turned
|
|||
|
|
off. Therefore, RFC 2109 cookies are downgraded by default.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>General strictness switches:</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.strict_domain">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Don’t allow sites to set two-component domains with country-code top-level
|
|||
|
|
domains like <code class="docutils literal notranslate"><span class="pre">.co.uk</span></code>, <code class="docutils literal notranslate"><span class="pre">.gov.uk</span></code>, <code class="docutils literal notranslate"><span class="pre">.co.nz</span></code>.etc. This is far from perfect
|
|||
|
|
and isn’t guaranteed to work!</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p><span class="target" id="index-17"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> protocol strictness switches:</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.strict_rfc2965_unverifiable">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Follow <span class="target" id="index-18"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> rules on unverifiable transactions (usually, an unverifiable
|
|||
|
|
transaction is one resulting from a redirect or a request for an image hosted on
|
|||
|
|
another site). If this is false, cookies are <em>never</em> blocked on the basis of
|
|||
|
|
verifiability</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>Netscape protocol strictness switches:</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.strict_ns_unverifiable">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Apply <span class="target" id="index-19"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> rules on unverifiable transactions even to Netscape cookies.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.strict_ns_domain">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Flags indicating how strict to be with domain-matching rules for Netscape
|
|||
|
|
cookies. See below for acceptable values.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.strict_ns_set_initial_dollar">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Ignore cookies in Set-Cookie: headers that have names starting with <code class="docutils literal notranslate"><span class="pre">'$'</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.strict_ns_set_path">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Don’t allow setting cookies whose path doesn’t path-match request URI.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p><code class="xref py py-attr docutils literal notranslate"><span class="pre">strict_ns_domain</span></code> is a collection of flags. Its value is constructed by
|
|||
|
|
or-ing together (for example, <code class="docutils literal notranslate"><span class="pre">DomainStrictNoDots|DomainStrictNonDomain</span></code> means
|
|||
|
|
both flags are set).</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.DomainStrictNoDots">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>When setting cookies, the ‘host prefix’ must not contain a dot (eg.
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">www.foo.bar.com</span></code> can’t set a cookie for <code class="docutils literal notranslate"><span class="pre">.bar.com</span></code>, because <code class="docutils literal notranslate"><span class="pre">www.foo</span></code>
|
|||
|
|
contains a dot).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.DomainStrictNonDomain">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Cookies that did not explicitly specify a <code class="docutils literal notranslate"><span class="pre">domain</span></code> cookie-attribute can only
|
|||
|
|
be returned to a domain equal to the domain that set the cookie (eg.
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">spam.example.com</span></code> won’t be returned cookies from <code class="docutils literal notranslate"><span class="pre">example.com</span></code> that had no
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">domain</span></code> cookie-attribute).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.DomainRFC2965Match">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>When setting cookies, require a full <span class="target" id="index-20"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> domain-match.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>The following attributes are provided for convenience, and are the most useful
|
|||
|
|
combinations of the above flags:</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.DomainLiberal">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
|
|||
|
|
off).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.DefaultCookiePolicy.DomainStrict">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">DomainStrictNoDots|DomainStrictNonDomain</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="cookie-objects">
|
|||
|
|
<h2>Cookie Objects<a class="headerlink" href="#cookie-objects" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p><a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> instances have Python attributes roughly corresponding to the
|
|||
|
|
standard cookie-attributes specified in the various cookie standards. The
|
|||
|
|
correspondence is not one-to-one, because there are complicated rules for
|
|||
|
|
assigning default values, because the <code class="docutils literal notranslate"><span class="pre">max-age</span></code> and <code class="docutils literal notranslate"><span class="pre">expires</span></code>
|
|||
|
|
cookie-attributes contain equivalent information, and because <span class="target" id="index-21"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies
|
|||
|
|
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 notranslate"><span class="pre">http.cookiejar</span></code></a> from version 1 to version 0 (Netscape)
|
|||
|
|
cookies.</p>
|
|||
|
|
<p>Assignment to these attributes should not be necessary other than in rare
|
|||
|
|
circumstances in a <a class="reference internal" href="#http.cookiejar.CookiePolicy" title="http.cookiejar.CookiePolicy"><code class="xref py py-class docutils literal notranslate"><span class="pre">CookiePolicy</span></code></a> method. The class does not enforce
|
|||
|
|
internal consistency, so you should know what you’re doing if you do that.</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.version">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Integer or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></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 notranslate"><span class="pre">version</span></code></a> 0. <span class="target" id="index-22"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> and
|
|||
|
|
<span class="target" id="index-23"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies have a <code class="docutils literal notranslate"><span class="pre">version</span></code> cookie-attribute of 1. However, note that
|
|||
|
|
<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 notranslate"><span class="pre">http.cookiejar</span></code></a> may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in which
|
|||
|
|
case <a class="reference internal" href="#http.cookiejar.Cookie.version" title="http.cookiejar.Cookie.version"><code class="xref py py-attr docutils literal notranslate"><span class="pre">version</span></code></a> is 0.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.name">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Cookie name (a string).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.value">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Cookie value (a string), or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.port">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>String representing a port or a set of ports (eg. ‘80’, or ‘80,8080’), or
|
|||
|
|
<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.path">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>Cookie path (a string, eg. <code class="docutils literal notranslate"><span class="pre">'/acme/rocket_launchers'</span></code>).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.secure">
|
|||
|
|
<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>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if cookie should only be returned over a secure connection.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.expires">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>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 notranslate"><span class="pre">None</span></code></a>. See also the
|
|||
|
|
<a class="reference internal" href="#http.cookiejar.Cookie.is_expired" title="http.cookiejar.Cookie.is_expired"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_expired()</span></code></a> method.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.discard">
|
|||
|
|
<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>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if this is a session cookie.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.comment">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>String comment from the server explaining the function of this cookie, or
|
|||
|
|
<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.comment_url">
|
|||
|
|
<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>
|
|||
|
|
<dd><p>URL linking to a comment from the server explaining the function of this cookie,
|
|||
|
|
or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.rfc2109">
|
|||
|
|
<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>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if this cookie was received as an <span class="target" id="index-24"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a> cookie (ie. the cookie
|
|||
|
|
arrived in a <em class="mailheader">Set-Cookie</em> header, and the value of the Version
|
|||
|
|
cookie-attribute in that header was 1). This attribute is provided because
|
|||
|
|
<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 notranslate"><span class="pre">http.cookiejar</span></code></a> may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in
|
|||
|
|
which case <a class="reference internal" href="#http.cookiejar.Cookie.version" title="http.cookiejar.Cookie.version"><code class="xref py py-attr docutils literal notranslate"><span class="pre">version</span></code></a> is 0.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.port_specified">
|
|||
|
|
<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>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if a port or set of ports was explicitly specified by the server (in the
|
|||
|
|
<em class="mailheader">Set-Cookie</em> / <em class="mailheader">Set-Cookie2</em> header).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.domain_specified">
|
|||
|
|
<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>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if a domain was explicitly specified by the server.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="http.cookiejar.Cookie.domain_initial_dot">
|
|||
|
|
<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>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the domain explicitly specified by the server began with a dot
|
|||
|
|
(<code class="docutils literal notranslate"><span class="pre">'.'</span></code>).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>Cookies may have additional non-standard cookie-attributes. These may be
|
|||
|
|
accessed using the following methods:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.Cookie.has_nonstandard_attr">
|
|||
|
|
<code class="descclassname">Cookie.</code><code class="descname">has_nonstandard_attr</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.has_nonstandard_attr" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return true if cookie has the named cookie-attribute.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.Cookie.get_nonstandard_attr">
|
|||
|
|
<code class="descclassname">Cookie.</code><code class="descname">get_nonstandard_attr</code><span class="sig-paren">(</span><em>name</em>, <em>default=None</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.get_nonstandard_attr" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>If cookie has the named cookie-attribute, return its value. Otherwise, return
|
|||
|
|
<em>default</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.Cookie.set_nonstandard_attr">
|
|||
|
|
<code class="descclassname">Cookie.</code><code class="descname">set_nonstandard_attr</code><span class="sig-paren">(</span><em>name</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.set_nonstandard_attr" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the value of the named cookie-attribute.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>The <a class="reference internal" href="#http.cookiejar.Cookie" title="http.cookiejar.Cookie"><code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code></a> class also defines the following method:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="http.cookiejar.Cookie.is_expired">
|
|||
|
|
<code class="descclassname">Cookie.</code><code class="descname">is_expired</code><span class="sig-paren">(</span><em>now=None</em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.is_expired" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if cookie has passed the time at which the server requested it should
|
|||
|
|
expire. If <em>now</em> is given (in seconds since the epoch), return whether the
|
|||
|
|
cookie has expired at the specified time.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="examples">
|
|||
|
|
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>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 notranslate"><span class="pre">http.cookiejar</span></code></a>:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">http.cookiejar</span><span class="o">,</span> <span class="nn">urllib.request</span>
|
|||
|
|
<span class="n">cj</span> <span class="o">=</span> <span class="n">http</span><span class="o">.</span><span class="n">cookiejar</span><span class="o">.</span><span class="n">CookieJar</span><span class="p">()</span>
|
|||
|
|
<span class="n">opener</span> <span class="o">=</span> <span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">build_opener</span><span class="p">(</span><span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">HTTPCookieProcessor</span><span class="p">(</span><span class="n">cj</span><span class="p">))</span>
|
|||
|
|
<span class="n">r</span> <span class="o">=</span> <span class="n">opener</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"http://example.com/"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
|
|||
|
|
cookies (assumes Unix/Netscape convention for location of the cookies file):</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span><span class="o">,</span> <span class="nn">http.cookiejar</span><span class="o">,</span> <span class="nn">urllib.request</span>
|
|||
|
|
<span class="n">cj</span> <span class="o">=</span> <span class="n">http</span><span class="o">.</span><span class="n">cookiejar</span><span class="o">.</span><span class="n">MozillaCookieJar</span><span class="p">()</span>
|
|||
|
|
<span class="n">cj</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">expanduser</span><span class="p">(</span><span class="s2">"~"</span><span class="p">),</span> <span class="s2">".netscape"</span><span class="p">,</span> <span class="s2">"cookies.txt"</span><span class="p">))</span>
|
|||
|
|
<span class="n">opener</span> <span class="o">=</span> <span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">build_opener</span><span class="p">(</span><span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">HTTPCookieProcessor</span><span class="p">(</span><span class="n">cj</span><span class="p">))</span>
|
|||
|
|
<span class="n">r</span> <span class="o">=</span> <span class="n">opener</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"http://example.com/"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>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 notranslate"><span class="pre">DefaultCookiePolicy</span></code></a>. Turn on
|
|||
|
|
<span class="target" id="index-25"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies, be more strict about domains when setting and returning
|
|||
|
|
Netscape cookies, and block some domains from setting cookies or having them
|
|||
|
|
returned:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">urllib.request</span>
|
|||
|
|
<span class="kn">from</span> <span class="nn">http.cookiejar</span> <span class="k">import</span> <span class="n">CookieJar</span><span class="p">,</span> <span class="n">DefaultCookiePolicy</span>
|
|||
|
|
<span class="n">policy</span> <span class="o">=</span> <span class="n">DefaultCookiePolicy</span><span class="p">(</span>
|
|||
|
|
<span class="n">rfc2965</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">strict_ns_domain</span><span class="o">=</span><span class="n">Policy</span><span class="o">.</span><span class="n">DomainStrict</span><span class="p">,</span>
|
|||
|
|
<span class="n">blocked_domains</span><span class="o">=</span><span class="p">[</span><span class="s2">"ads.net"</span><span class="p">,</span> <span class="s2">".ads.net"</span><span class="p">])</span>
|
|||
|
|
<span class="n">cj</span> <span class="o">=</span> <span class="n">CookieJar</span><span class="p">(</span><span class="n">policy</span><span class="p">)</span>
|
|||
|
|
<span class="n">opener</span> <span class="o">=</span> <span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">build_opener</span><span class="p">(</span><span class="n">urllib</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">HTTPCookieProcessor</span><span class="p">(</span><span class="n">cj</span><span class="p">))</span>
|
|||
|
|
<span class="n">r</span> <span class="o">=</span> <span class="n">opener</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"http://example.com/"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<h3><a href="../contents.html">Table of Contents</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> — Cookie handling for HTTP clients</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#cookiejar-and-filecookiejar-objects">CookieJar and FileCookieJar Objects</a></li>
|
|||
|
|
<li><a class="reference internal" href="#filecookiejar-subclasses-and-co-operation-with-web-browsers">FileCookieJar subclasses and co-operation with web browsers</a></li>
|
|||
|
|
<li><a class="reference internal" href="#cookiepolicy-objects">CookiePolicy Objects</a></li>
|
|||
|
|
<li><a class="reference internal" href="#defaultcookiepolicy-objects">DefaultCookiePolicy Objects</a></li>
|
|||
|
|
<li><a class="reference internal" href="#cookie-objects">Cookie Objects</a></li>
|
|||
|
|
<li><a class="reference internal" href="#examples">Examples</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="http.cookies.html"
|
|||
|
|
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookies</span></code> — HTTP state management</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="xmlrpc.html"
|
|||
|
|
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">xmlrpc</span></code> — XMLRPC server and client modules</a></p>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<h3>This Page</h3>
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/http.cookiejar.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="xmlrpc.html" title="xmlrpc — XMLRPC server and client modules"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="http.cookies.html" title="http.cookies — HTTP state management"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="internet.html" >Internet Protocols and Support</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|