Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
http.cookiejar.html1126 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="http.cookiejar — Cookie handling for HTTP clients" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/http.cookiejar.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/http/cookiejar.py The http.cookiejar module defines classes for automatic handling of HTTP cookies. It is useful for accessing websites that require small pieces of data – cookies ..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_http.cookiejar_ac6e3781.png" />15<meta property="og:image:alt" content="Source code: Lib/http/cookiejar.py The http.cookiejar module defines classes for automatic handling of HTTP cookies. It is useful for accessing websites that require small pieces of data – cookies ..." />16<meta name="description" content="Source code: Lib/http/cookiejar.py The http.cookiejar module defines classes for automatic handling of HTTP cookies. It is useful for accessing websites that require small pieces of data – cookies ..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>http.cookiejar — Cookie handling for HTTP clients &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="xmlrpc — XMLRPC server and client modules" href="xmlrpc.html" />43    <link rel="prev" title="http.cookies — HTTP state management" href="http.cookies.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/http.cookiejar.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<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>108<li><a class="reference internal" href="#cookiejar-and-filecookiejar-objects">CookieJar and FileCookieJar Objects</a></li>109<li><a class="reference internal" href="#filecookiejar-subclasses-and-co-operation-with-web-browsers">FileCookieJar subclasses and co-operation with web browsers</a></li>110<li><a class="reference internal" href="#cookiepolicy-objects">CookiePolicy Objects</a></li>111<li><a class="reference internal" href="#defaultcookiepolicy-objects">DefaultCookiePolicy Objects</a></li>112<li><a class="reference internal" href="#cookie-objects">Cookie Objects</a></li>113<li><a class="reference internal" href="#examples">Examples</a></li>114</ul>115</li>116</ul>117 118  </div>119  <div>120    <h4>Previous topic</h4>121    <p class="topless"><a href="http.cookies.html"122                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookies</span></code> — HTTP state management</a></p>123  </div>124  <div>125    <h4>Next topic</h4>126    <p class="topless"><a href="xmlrpc.html"127                          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>128  </div>129  <script>130    document.addEventListener('DOMContentLoaded', () => {131        const title = document.querySelector('meta[property="og:title"]').content;132        const elements = document.querySelectorAll('.improvepage');133        const pageurl = window.location.href.split('?')[0];134        elements.forEach(element => {135            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));136            url.searchParams.set('pagetitle', title);137            url.searchParams.set('pageurl', pageurl);138            url.searchParams.set('pagesource', "library/http.cookiejar.rst");139            element.href = url.toString();140        });141    });142  </script>143  <div role="note" aria-label="source link">144    <h3>This page</h3>145    <ul class="this-page-menu">146      <li><a href="../bugs.html">Report a bug</a></li>147      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>148      <li>149        <a href="https://github.com/python/cpython/blob/main/Doc/library/http.cookiejar.rst?plain=1"150            rel="nofollow">Show source151        </a>152      </li>153      154    </ul>155  </div>156        </nav>157    </div>158</div>159 160  161    <div class="related" role="navigation" aria-label="Related">162      <h3>Navigation</h3>163      <ul>164        <li class="right" style="margin-right: 10px">165          <a href="../genindex.html" title="General Index"166             accesskey="I">index</a></li>167        <li class="right" >168          <a href="../py-modindex.html" title="Python Module Index"169             >modules</a> |</li>170        <li class="right" >171          <a href="xmlrpc.html" title="xmlrpc — XMLRPC server and client modules"172             accesskey="N">next</a> |</li>173        <li class="right" >174          <a href="http.cookies.html" title="http.cookies — HTTP state management"175             accesskey="P">previous</a> |</li>176 177          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>178          <li><a href="https://www.python.org/">Python</a> &#187;</li>179          <li class="switchers">180            <div class="language_switcher_placeholder"></div>181            <div class="version_switcher_placeholder"></div>182          </li>183          <li>184              185          </li>186    <li id="cpython-language-and-version">187      <a href="../index.html">3.15.0a6 Documentation</a> &#187;188    </li>189 190          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>191          <li class="nav-item nav-item-2"><a href="internet.html" accesskey="U">Internet Protocols and Support</a> &#187;</li>192        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> — Cookie handling for HTTP clients</a></li>193                <li class="right">194                    195 196    <div class="inline-search" role="search">197        <form class="inline-search" action="../search.html" method="get">198          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">199          <input type="submit" value="Go">200        </form>201    </div>202                     |203                </li>204            <li class="right">205<label class="theme-selector-label">206    Theme207    <select class="theme-selector" oninput="activateTheme(this.value)">208        <option value="auto" selected>Auto</option>209        <option value="light">Light</option>210        <option value="dark">Dark</option>211    </select>212</label> |</li>213            214      </ul>215    </div>    216 217    <div class="document">218      <div class="documentwrapper">219        <div class="bodywrapper">220          <div class="body" role="main">221            222  <section id="module-http.cookiejar">223<span id="http-cookiejar-cookie-handling-for-http-clients"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> — Cookie handling for HTTP clients<a class="headerlink" href="#module-http.cookiejar" title="Link to this heading">¶</a></h1>224<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/http/cookiejar.py">Lib/http/cookiejar.py</a></p>225<hr class="docutils" />226<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> module defines classes for automatic handling of HTTP227cookies.  It is useful for accessing websites that require small pieces of data228– <em class="dfn">cookies</em> – to be set on the client machine by an HTTP response from a229web server, and then returned to the server in later HTTP requests.</p>230<p>Both the regular Netscape cookie protocol and the protocol defined by231<span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> are handled.  RFC 2965 handling is switched off by default.232<span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies are parsed as Netscape cookies and subsequently treated233either as Netscape or RFC 2965 cookies according to the ‘policy’ in effect.234Note that the great majority of cookies on the internet are Netscape cookies.235<code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> attempts to follow the de-facto Netscape cookie protocol (which236differs substantially from that set out in the original Netscape specification),237including 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-attributes238introduced with RFC 2965.</p>239<div class="admonition note">240<p class="admonition-title">Note</p>241<p>The various named parameters found in <em class="mailheader">Set-Cookie</em> and242<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>) are243conventionally referred to as <em class="dfn">attributes</em>.  To distinguish them from244Python attributes, the documentation for this module uses the term245<em class="dfn">cookie-attribute</em> instead.</p>246</div>247<p>The module defines the following exception:</p>248<dl class="py exception">249<dt class="sig sig-object py" id="http.cookiejar.LoadError">250<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">LoadError</span></span><a class="headerlink" href="#http.cookiejar.LoadError" title="Link to this definition">¶</a></dt>251<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 load252cookies from a file.  <code class="xref py py-exc docutils literal notranslate"><span class="pre">LoadError</span></code> 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>253<div class="versionchanged">254<p><span class="versionmodified changed">Changed in version 3.3: </span><code class="xref py py-exc docutils literal notranslate"><span class="pre">LoadError</span></code> used to be a subtype 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>, which is now an255alias 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>256</div>257</dd></dl>258 259<p>The following classes are provided:</p>260<dl class="py class">261<dt class="sig sig-object py" id="http.cookiejar.CookieJar">262<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">CookieJar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar" title="Link to this definition">¶</a></dt>263<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>264<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code> class stores HTTP cookies.  It extracts cookies from HTTP265requests, and returns them in HTTP responses. <code class="xref py py-class docutils literal notranslate"><span class="pre">CookieJar</span></code> instances266automatically expire contained cookies when necessary.  Subclasses are also267responsible for storing and retrieving cookies from a file or database.</p>268</dd></dl>269 270<dl class="py class">271<dt class="sig sig-object py" id="http.cookiejar.FileCookieJar">272<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">FileCookieJar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">delayload</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar" title="Link to this definition">¶</a></dt>273<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 the274other arguments, see the documentation for the corresponding attributes.</p>275<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, a276file on disk.  Cookies are <strong>NOT</strong> loaded from the named file until either the277<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 are278documented 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>279<p>This should not be initialized directly – use its subclasses below instead.</p>280<div class="versionchanged">281<p><span class="versionmodified changed">Changed in version 3.8: </span>The filename parameter supports a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>282</div>283</dd></dl>284 285<dl class="py class">286<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy">287<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">CookiePolicy</span></span><a class="headerlink" href="#http.cookiejar.CookiePolicy" title="Link to this definition">¶</a></dt>288<dd><p>This class is responsible for deciding whether each cookie should be accepted289from / returned to the server.</p>290</dd></dl>291 292<dl class="py class">293<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy">294<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">DefaultCookiePolicy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">blocked_domains</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allowed_domains</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">netscape</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rfc2965</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rfc2109_as_netscape</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">hide_cookie2</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_domain</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_rfc2965_unverifiable</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_ns_unverifiable</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_ns_domain</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DefaultCookiePolicy.DomainLiberal</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_ns_set_initial_dollar</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">strict_ns_set_path</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">secure_protocols</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">('https',</span> <span class="pre">'wss')</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy" title="Link to this definition">¶</a></dt>295<dd><p>Constructor arguments should be passed as keyword arguments only.296<em>blocked_domains</em> is a sequence of domain names that we never accept cookies297from, 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 a298sequence of the only domains for which we accept and return cookies.299<em>secure_protocols</em> is a sequence of protocols for which secure cookies can be300added to. By default <em>https</em> and <em>wss</em> (secure websocket) are considered301secure protocols. For all other arguments, see the documentation for302<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 <code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code> objects.</p>303<p><code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code> implements the standard accept / reject rules for304Netscape and <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/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://datatracker.ietf.org/doc/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies (ie. cookies305received in a <em class="mailheader">Set-Cookie</em> header with a version cookie-attribute of3061) are treated according to the RFC 2965 rules.  However, if RFC 2965 handling307is 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 are308‘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, by309setting 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.310<code class="xref py py-class docutils literal notranslate"><span class="pre">DefaultCookiePolicy</span></code> also provides some parameters to allow some311fine-tuning of policy.</p>312</dd></dl>313 314<dl class="py class">315<dt class="sig sig-object py" id="http.cookiejar.Cookie">316<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">Cookie</span></span><a class="headerlink" href="#http.cookiejar.Cookie" title="Link to this definition">¶</a></dt>317<dd><p>This class represents Netscape, <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2109.html"><strong>RFC 2109</strong></a> and <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies.  It is not318expected that users of <code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> construct their own <code class="xref py py-class docutils literal notranslate"><span class="pre">Cookie</span></code>319instances.  Instead, if necessary, call <code class="xref py py-meth docutils literal notranslate"><span class="pre">make_cookies()</span></code> on a320<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>321</dd></dl>322 323<div class="admonition seealso">324<p class="admonition-title">See also</p>325<dl class="simple">326<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>327</dd>328<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.  The329<code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> 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 each330other.</p>331</dd>332<dt><a class="reference external" href="https://curl.se/rfc/cookie_spec.html">https://curl.se/rfc/cookie_spec.html</a></dt><dd><p>The specification of the original Netscape cookie protocol.  Though this is333still the dominant protocol, the ‘Netscape cookie protocol’ implemented by all334the major browsers (and <code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code>) only bears a passing resemblance to335the one sketched out in <code class="docutils literal notranslate"><span class="pre">cookie_spec.html</span></code>.</p>336</dd>337<dt><span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/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://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a>. Uses <em class="mailheader">Set-Cookie</em> with version=1.</p>338</dd>339<dt><span class="target" id="index-8"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/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> in340place of <em class="mailheader">Set-Cookie</em>.  Not widely used.</p>341</dd>342<dt><a class="reference external" href="https://kristol.org/cookie/errata.html">https://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://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a>.</p>343</dd>344</dl>345<p><span class="target" id="index-10"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2964.html"><strong>RFC 2964</strong></a> - Use of HTTP State Management</p>346</div>347<section id="cookiejar-and-filecookiejar-objects">348<span id="cookie-jar-objects"></span><h2>CookieJar and FileCookieJar Objects<a class="headerlink" href="#cookiejar-and-filecookiejar-objects" title="Link to this heading">¶</a></h2>349<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 over350contained <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>351<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>352<dl class="py method">353<dt class="sig sig-object py" id="http.cookiejar.CookieJar.add_cookie_header">354<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">add_cookie_header</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.add_cookie_header" title="Link to this definition">¶</a></dt>355<dd><p>Add correct <em class="mailheader">Cookie</em> header to <em>request</em>.</p>356<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 of357the <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 false358respectively), the <em class="mailheader">Cookie2</em> header is also added when appropriate.</p>359<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)360must 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">has_header()</span></code>,361<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>362and the attributes <code class="xref py py-attr docutils literal notranslate"><span class="pre">host</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">unverifiable</span></code>363and <code class="xref py py-attr docutils literal notranslate"><span class="pre">origin_req_host</span></code> 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>364<div class="versionchanged">365<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 a366deprecated method <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_origin_req_host()</span></code> has been removed.</p>367</div>368</dd></dl>369 370<dl class="py method">371<dt class="sig sig-object py" id="http.cookiejar.CookieJar.extract_cookies">372<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">extract_cookies</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">response</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.extract_cookies" title="Link to this definition">¶</a></dt>373<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>,374where allowed by policy.</p>375<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> and376<em class="mailheader">Set-Cookie2</em> headers in the <em>response</em> argument, and store cookies377as 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>378<p>The <em>response</em> object (usually the result of a call to379<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>380method, 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>381<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)382must support the method <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_full_url()</span></code> and the attributes383<code class="xref py py-attr docutils literal notranslate"><span class="pre">host</span></code>, <code class="xref py py-attr 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>,384as 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 set385default values for cookie-attributes as well as for checking that the386cookie is allowed to be set.</p>387<div class="versionchanged">388<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 a389deprecated method <code class="xref py py-meth docutils literal notranslate"><span class="pre">get_origin_req_host()</span></code> has been removed.</p>390</div>391</dd></dl>392 393<dl class="py method">394<dt class="sig sig-object py" id="http.cookiejar.CookieJar.set_policy">395<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">set_policy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">policy</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.set_policy" title="Link to this definition">¶</a></dt>396<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>397</dd></dl>398 399<dl class="py method">400<dt class="sig sig-object py" id="http.cookiejar.CookieJar.make_cookies">401<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">make_cookies</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">response</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.make_cookies" title="Link to this definition">¶</a></dt>402<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>403<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 of404the <em>response</em> and <em>request</em> arguments.</p>405</dd></dl>406 407<dl class="py method">408<dt class="sig sig-object py" id="http.cookiejar.CookieJar.set_cookie_if_ok">409<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">set_cookie_if_ok</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cookie</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.set_cookie_if_ok" title="Link to this definition">¶</a></dt>410<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>411</dd></dl>412 413<dl class="py method">414<dt class="sig sig-object py" id="http.cookiejar.CookieJar.set_cookie">415<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">set_cookie</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cookie</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.set_cookie" title="Link to this definition">¶</a></dt>416<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 it417should be set.</p>418</dd></dl>419 420<dl class="py method">421<dt class="sig sig-object py" id="http.cookiejar.CookieJar.clear">422<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">domain</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">path</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></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="Link to this definition">¶</a></dt>423<dd><p>Clear some cookies.</p>424<p>If invoked without arguments, clear all cookies.  If given a single argument,425only cookies belonging to that <em>domain</em> will be removed. If given two arguments,426cookies belonging to the specified <em>domain</em> and URL <em>path</em> are removed.  If427given three arguments, then the cookie with the specified <em>domain</em>, <em>path</em> and428<em>name</em> is removed.</p>429<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>430</dd></dl>431 432<dl class="py method">433<dt class="sig sig-object py" id="http.cookiejar.CookieJar.clear_session_cookies">434<span class="sig-prename descclassname"><span class="pre">CookieJar.</span></span><span class="sig-name descname"><span class="pre">clear_session_cookies</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookieJar.clear_session_cookies" title="Link to this definition">¶</a></dt>435<dd><p>Discard all session cookies.</p>436<p>Discards all contained cookies that have a true <code class="xref py py-attr docutils literal notranslate"><span class="pre">discard</span></code> attribute437(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,438or an explicit <code class="docutils literal notranslate"><span class="pre">discard</span></code> cookie-attribute).  For interactive browsers, the end439of a session usually corresponds to closing the browser window.</p>440<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 you441ask otherwise by passing a true <em>ignore_discard</em> argument.</p>442</dd></dl>443 444<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>445<dl class="py method">446<dt class="sig sig-object py" id="http.cookiejar.FileCookieJar.save">447<span class="sig-prename descclassname"><span class="pre">FileCookieJar.</span></span><span class="sig-name descname"><span class="pre">save</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_discard</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_expires</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar.save" title="Link to this definition">¶</a></dt>448<dd><p>Save cookies to a file.</p>449<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 this450method unimplemented.</p>451<p><em>filename</em> is the name of file in which to save cookies.  If <em>filename</em> is not452specified, <code class="xref py py-attr docutils literal notranslate"><span class="pre">self.filename</span></code> is used (whose default is the value passed to453the 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>,454<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>455<p><em>ignore_discard</em>: save even cookies set to be discarded. <em>ignore_expires</em>: save456even cookies that have expired</p>457<p>The file is overwritten if it already exists, thus wiping all the cookies it458contains.  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> or459<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>460</dd></dl>461 462<dl class="py method">463<dt class="sig sig-object py" id="http.cookiejar.FileCookieJar.load">464<span class="sig-prename descclassname"><span class="pre">FileCookieJar.</span></span><span class="sig-name descname"><span class="pre">load</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_discard</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_expires</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar.load" title="Link to this definition">¶</a></dt>465<dd><p>Load cookies from a file.</p>466<p>Old cookies are kept unless overwritten by newly loaded ones.</p>467<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>468<p>The named file must be in the format understood by the class, or469<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, for470example if the file does not exist.</p>471<div class="versionchanged">472<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>473</div>474</dd></dl>475 476<dl class="py method">477<dt class="sig sig-object py" id="http.cookiejar.FileCookieJar.revert">478<span class="sig-prename descclassname"><span class="pre">FileCookieJar.</span></span><span class="sig-name descname"><span class="pre">revert</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_discard</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_expires</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.FileCookieJar.revert" title="Link to this definition">¶</a></dt>479<dd><p>Clear all cookies and reload cookies from a saved file.</p>480<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">revert()</span></code> 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 a481failure, the object’s state will not be altered.</p>482</dd></dl>483 484<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>485<dl class="py attribute">486<dt class="sig sig-object py" id="http.cookiejar.FileCookieJar.filename">487<span class="sig-prename descclassname"><span class="pre">FileCookieJar.</span></span><span class="sig-name descname"><span class="pre">filename</span></span><a class="headerlink" href="#http.cookiejar.FileCookieJar.filename" title="Link to this definition">¶</a></dt>488<dd><p>Filename of default file in which to keep cookies.  This attribute may be489assigned to.</p>490</dd></dl>491 492<dl class="py attribute">493<dt class="sig sig-object py" id="http.cookiejar.FileCookieJar.delayload">494<span class="sig-prename descclassname"><span class="pre">FileCookieJar.</span></span><span class="sig-name descname"><span class="pre">delayload</span></span><a class="headerlink" href="#http.cookiejar.FileCookieJar.delayload" title="Link to this definition">¶</a></dt>495<dd><p>If true, load cookies lazily from disk.  This attribute should not be assigned496to.  This is only a hint, since this only affects performance, not behaviour497(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 may498ignore 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 standard499library lazily loads cookies.</p>500</dd></dl>501 502</section>503<section id="filecookiejar-subclasses-and-co-operation-with-web-browsers">504<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="Link to this heading">¶</a></h2>505<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 and506writing.</p>507<dl class="py class">508<dt class="sig sig-object py" id="http.cookiejar.MozillaCookieJar">509<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">MozillaCookieJar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">delayload</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.MozillaCookieJar" title="Link to this definition">¶</a></dt>510<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 the511Mozilla <code class="docutils literal notranslate"><span class="pre">cookies.txt</span></code> file format (which is also used by curl and the Lynx512and Netscape browsers).</p>513<div class="admonition note">514<p class="admonition-title">Note</p>515<p>This loses information about <span class="target" id="index-11"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies, and also about newer or516non-standard cookie-attributes such as <code class="docutils literal notranslate"><span class="pre">port</span></code>.</p>517</div>518<div class="admonition warning">519<p class="admonition-title">Warning</p>520<p>Back up your cookies before saving if you have cookies whose loss / corruption521would be inconvenient (there are some subtleties which may lead to slight522changes in the file over a load / save round-trip).</p>523</div>524<p>Also note that cookies saved while Mozilla is running will get clobbered by525Mozilla.</p>526</dd></dl>527 528<dl class="py class">529<dt class="sig sig-object py" id="http.cookiejar.LWPCookieJar">530<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">http.cookiejar.</span></span><span class="sig-name descname"><span class="pre">LWPCookieJar</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">delayload</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.LWPCookieJar" title="Link to this definition">¶</a></dt>531<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 format532compatible with the libwww-perl library’s <code class="docutils literal notranslate"><span class="pre">Set-Cookie3</span></code> file format.  This is533convenient if you want to store cookies in a human-readable file.</p>534<div class="versionchanged">535<p><span class="versionmodified changed">Changed in version 3.8: </span>The filename parameter supports a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>536</div>537</dd></dl>538 539</section>540<section id="cookiepolicy-objects">541<span id="cookie-policy-objects"></span><h2>CookiePolicy Objects<a class="headerlink" href="#cookiepolicy-objects" title="Link to this heading">¶</a></h2>542<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 following543methods:</p>544<dl class="py method">545<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy.set_ok">546<span class="sig-prename descclassname"><span class="pre">CookiePolicy.</span></span><span class="sig-name descname"><span class="pre">set_ok</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cookie</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.set_ok" title="Link to this definition">¶</a></dt>547<dd><p>Return boolean value indicating whether cookie should be accepted from server.</p>548<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 object549implementing the interface defined by the documentation for550<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>551</dd></dl>552 553<dl class="py method">554<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy.return_ok">555<span class="sig-prename descclassname"><span class="pre">CookiePolicy.</span></span><span class="sig-name descname"><span class="pre">return_ok</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cookie</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.return_ok" title="Link to this definition">¶</a></dt>556<dd><p>Return boolean value indicating whether cookie should be returned to server.</p>557<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 object558implementing the interface defined by the documentation for559<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>560</dd></dl>561 562<dl class="py method">563<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy.domain_return_ok">564<span class="sig-prename descclassname"><span class="pre">CookiePolicy.</span></span><span class="sig-name descname"><span class="pre">domain_return_ok</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">domain</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.domain_return_ok" title="Link to this definition">¶</a></dt>565<dd><p>Return <code class="docutils literal notranslate"><span class="pre">False</span></code> if cookies should not be returned, given cookie domain.</p>566<p>This method is an optimization.  It removes the need for checking every cookie567with a particular domain (which might involve reading many files).  Returning568true from <code class="xref py py-meth docutils literal notranslate"><span class="pre">domain_return_ok()</span></code> 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 the569work 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>570<p>If <code class="xref py py-meth docutils literal notranslate"><span class="pre">domain_return_ok()</span></code> returns true for the cookie domain,571<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,572<code class="xref py py-meth docutils literal notranslate"><span class="pre">path_return_ok()</span></code> 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 cookie573domain.  If <code class="xref py py-meth docutils literal notranslate"><span class="pre">path_return_ok()</span></code> returns true, <code class="xref py py-meth docutils literal notranslate"><span class="pre">return_ok()</span></code> is called574with 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,575<code class="xref py py-meth docutils literal notranslate"><span class="pre">return_ok()</span></code> is never called for that cookie path.</p>576<p>Note that <code class="xref py py-meth docutils literal notranslate"><span class="pre">domain_return_ok()</span></code> is called for every <em>cookie</em> domain, not just577for the <em>request</em> domain.  For example, the function might be called with both578<code class="docutils literal notranslate"><span class="pre">&quot;.example.com&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;www.example.com&quot;</span></code> if the request domain is579<code class="docutils literal notranslate"><span class="pre">&quot;www.example.com&quot;</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>580<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>581</dd></dl>582 583<dl class="py method">584<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy.path_return_ok">585<span class="sig-prename descclassname"><span class="pre">CookiePolicy.</span></span><span class="sig-name descname"><span class="pre">path_return_ok</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">request</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.CookiePolicy.path_return_ok" title="Link to this definition">¶</a></dt>586<dd><p>Return <code class="docutils literal notranslate"><span class="pre">False</span></code> if cookies should not be returned, given cookie path.</p>587<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>588</dd></dl>589 590<p>In addition to implementing the methods above, implementations of the591<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,592indicating which protocols should be used, and how.  All of these attributes may593be assigned to.</p>594<dl class="py attribute">595<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy.netscape">596<span class="sig-prename descclassname"><span class="pre">CookiePolicy.</span></span><span class="sig-name descname"><span class="pre">netscape</span></span><a class="headerlink" href="#http.cookiejar.CookiePolicy.netscape" title="Link to this definition">¶</a></dt>597<dd><p>Implement Netscape protocol.</p>598</dd></dl>599 600<dl class="py attribute">601<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy.rfc2965">602<span class="sig-prename descclassname"><span class="pre">CookiePolicy.</span></span><span class="sig-name descname"><span class="pre">rfc2965</span></span><a class="headerlink" href="#http.cookiejar.CookiePolicy.rfc2965" title="Link to this definition">¶</a></dt>603<dd><p>Implement <span class="target" id="index-12"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> protocol.</p>604</dd></dl>605 606<dl class="py attribute">607<dt class="sig sig-object py" id="http.cookiejar.CookiePolicy.hide_cookie2">608<span class="sig-prename descclassname"><span class="pre">CookiePolicy.</span></span><span class="sig-name descname"><span class="pre">hide_cookie2</span></span><a class="headerlink" href="#http.cookiejar.CookiePolicy.hide_cookie2" title="Link to this definition">¶</a></dt>609<dd><p>Don’t add <em class="mailheader">Cookie2</em> header to requests (the presence of this header610indicates to the server that we understand <span class="target" id="index-13"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies).</p>611</dd></dl>612 613<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 subclassing614from <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 methods615above.  <code class="xref py py-class docutils literal notranslate"><span class="pre">CookiePolicy</span></code> itself may be used as a ‘null policy’ to allow616setting and receiving any and all cookies (this is unlikely to be useful).</p>617</section>618<section id="defaultcookiepolicy-objects">619<span id="default-cookie-policy-objects"></span><h2>DefaultCookiePolicy Objects<a class="headerlink" href="#defaultcookiepolicy-objects" title="Link to this heading">¶</a></h2>620<p>Implements the standard rules for accepting and returning cookies.</p>621<p>Both <span class="target" id="index-14"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> and Netscape cookies are covered.  RFC 2965 handling is switched622off by default.</p>623<p>The easiest way to provide your own policy is to override this class and call624its methods in your overridden implementations before adding your own additional625checks:</p>626<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">http.cookiejar</span>627<span class="k">class</span><span class="w"> </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>628    <span class="k">def</span><span class="w"> </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>629        <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>630            <span class="k">return</span> <span class="kc">False</span>631        <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>632            <span class="k">return</span> <span class="kc">False</span>633        <span class="k">return</span> <span class="kc">True</span>634</pre></div>635</div>636<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>637interface, this class allows you to block and allow domains from setting and638receiving cookies.  There are also some strictness switches that allow you to639tighten up the rather loose Netscape protocol rules a little bit (at the cost of640blocking some benign cookies).</p>641<p>A domain blocklist and allowlist is provided (both off by default). Only domains642not in the blocklist and present in the allowlist (if the allowlist is active)643participate in cookie setting and returning.  Use the <em>blocked_domains</em>644constructor argument, and <code class="xref py py-meth docutils literal notranslate"><span class="pre">blocked_domains()</span></code> and645<code class="xref py py-meth docutils literal notranslate"><span class="pre">set_blocked_domains()</span></code> methods (and the corresponding argument and methods646for <em>allowed_domains</em>).  If you set an allowlist, you can turn it off again by647setting 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>648<p>Domains in block or allow lists that do not start with a dot must equal the649cookie domain to be matched.  For example, <code class="docutils literal notranslate"><span class="pre">&quot;example.com&quot;</span></code> matches a blocklist650entry of <code class="docutils literal notranslate"><span class="pre">&quot;example.com&quot;</span></code>, but <code class="docutils literal notranslate"><span class="pre">&quot;www.example.com&quot;</span></code> does not.  Domains that do651start with a dot are matched by more specific domains too. For example, both652<code class="docutils literal notranslate"><span class="pre">&quot;www.example.com&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;www.coyote.example.com&quot;</span></code> match <code class="docutils literal notranslate"><span class="pre">&quot;.example.com&quot;</span></code>653(but <code class="docutils literal notranslate"><span class="pre">&quot;example.com&quot;</span></code> itself does not).  IP addresses are an exception, and654must match exactly.  For example, if blocked_domains contains <code class="docutils literal notranslate"><span class="pre">&quot;192.168.1.2&quot;</span></code>655and <code class="docutils literal notranslate"><span class="pre">&quot;.168.1.2&quot;</span></code>, 192.168.1.2 is blocked, but 193.168.1.2 is not.</p>656<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>657<dl class="py method">658<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.blocked_domains">659<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">blocked_domains</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.blocked_domains" title="Link to this definition">¶</a></dt>660<dd><p>Return the sequence of blocked domains (as a tuple).</p>661</dd></dl>662 663<dl class="py method">664<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.set_blocked_domains">665<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">set_blocked_domains</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">blocked_domains</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.set_blocked_domains" title="Link to this definition">¶</a></dt>666<dd><p>Set the sequence of blocked domains.</p>667</dd></dl>668 669<dl class="py method">670<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.is_blocked">671<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">is_blocked</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">domain</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.is_blocked" title="Link to this definition">¶</a></dt>672<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>domain</em> is on the blocklist for setting or receiving673cookies.</p>674</dd></dl>675 676<dl class="py method">677<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.allowed_domains">678<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">allowed_domains</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.allowed_domains" title="Link to this definition">¶</a></dt>679<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>680</dd></dl>681 682<dl class="py method">683<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.set_allowed_domains">684<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">set_allowed_domains</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">allowed_domains</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.set_allowed_domains" title="Link to this definition">¶</a></dt>685<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>686</dd></dl>687 688<dl class="py method">689<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.is_not_allowed">690<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">is_not_allowed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">domain</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.is_not_allowed" title="Link to this definition">¶</a></dt>691<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>domain</em> is not on the allowlist for setting or receiving692cookies.</p>693</dd></dl>694 695<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 are696all initialised from the constructor arguments of the same name, and which may697all be assigned to.</p>698<dl class="py attribute">699<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.rfc2109_as_netscape">700<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">rfc2109_as_netscape</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.rfc2109_as_netscape" title="Link to this definition">¶</a></dt>701<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://datatracker.ietf.org/doc/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies702(ie. cookies received in a <em class="mailheader">Set-Cookie</em> header with a version703cookie-attribute of 1) to Netscape cookies by setting the version attribute of704the <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 which705case RFC 2109 cookies are downgraded if and only if <span class="target" id="index-16"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> handling is turned706off.  Therefore, RFC 2109 cookies are downgraded by default.</p>707</dd></dl>708 709<p>General strictness switches:</p>710<dl class="py attribute">711<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.strict_domain">712<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">strict_domain</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_domain" title="Link to this definition">¶</a></dt>713<dd><p>Don’t allow sites to set two-component domains with country-code top-level714domains 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 perfect715and isn’t guaranteed to work!</p>716</dd></dl>717 718<p><span class="target" id="index-17"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> protocol strictness switches:</p>719<dl class="py attribute">720<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.strict_rfc2965_unverifiable">721<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">strict_rfc2965_unverifiable</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_rfc2965_unverifiable" title="Link to this definition">¶</a></dt>722<dd><p>Follow <span class="target" id="index-18"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> rules on unverifiable transactions (usually, an unverifiable723transaction is one resulting from a redirect or a request for an image hosted on724another site).  If this is false, cookies are <em>never</em> blocked on the basis of725verifiability</p>726</dd></dl>727 728<p>Netscape protocol strictness switches:</p>729<dl class="py attribute">730<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.strict_ns_unverifiable">731<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">strict_ns_unverifiable</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_unverifiable" title="Link to this definition">¶</a></dt>732<dd><p>Apply <span class="target" id="index-19"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> rules on unverifiable transactions even to Netscape cookies.</p>733</dd></dl>734 735<dl class="py attribute">736<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.strict_ns_domain">737<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">strict_ns_domain</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_domain" title="Link to this definition">¶</a></dt>738<dd><p>Flags indicating how strict to be with domain-matching rules for Netscape739cookies.  See below for acceptable values.</p>740</dd></dl>741 742<dl class="py attribute">743<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.strict_ns_set_initial_dollar">744<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">strict_ns_set_initial_dollar</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_set_initial_dollar" title="Link to this definition">¶</a></dt>745<dd><p>Ignore cookies in Set-Cookie: headers that have names starting with <code class="docutils literal notranslate"><span class="pre">'$'</span></code>.</p>746</dd></dl>747 748<dl class="py attribute">749<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.strict_ns_set_path">750<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">strict_ns_set_path</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_set_path" title="Link to this definition">¶</a></dt>751<dd><p>Don’t allow setting cookies whose path doesn’t path-match request URI.</p>752</dd></dl>753 754<p><a class="reference internal" href="#http.cookiejar.DefaultCookiePolicy.strict_ns_domain" title="http.cookiejar.DefaultCookiePolicy.strict_ns_domain"><code class="xref py py-attr docutils literal notranslate"><span class="pre">strict_ns_domain</span></code></a> is a collection of flags.  Its value is constructed by755or-ing together (for example, <code class="docutils literal notranslate"><span class="pre">DomainStrictNoDots|DomainStrictNonDomain</span></code> means756both flags are set).</p>757<dl class="py attribute">758<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.DomainStrictNoDots">759<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">DomainStrictNoDots</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainStrictNoDots" title="Link to this definition">¶</a></dt>760<dd><p>When setting cookies, the ‘host prefix’ must not contain a dot (eg.761<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>762contains a dot).</p>763</dd></dl>764 765<dl class="py attribute">766<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.DomainStrictNonDomain">767<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">DomainStrictNonDomain</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainStrictNonDomain" title="Link to this definition">¶</a></dt>768<dd><p>Cookies that did not explicitly specify a <code class="docutils literal notranslate"><span class="pre">domain</span></code> cookie-attribute can only769be returned to a domain equal to the domain that set the cookie (eg.770<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 no771<code class="docutils literal notranslate"><span class="pre">domain</span></code> cookie-attribute).</p>772</dd></dl>773 774<dl class="py attribute">775<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.DomainRFC2965Match">776<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">DomainRFC2965Match</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainRFC2965Match" title="Link to this definition">¶</a></dt>777<dd><p>When setting cookies, require a full <span class="target" id="index-20"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> domain-match.</p>778</dd></dl>779 780<p>The following attributes are provided for convenience, and are the most useful781combinations of the above flags:</p>782<dl class="py attribute">783<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.DomainLiberal">784<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">DomainLiberal</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainLiberal" title="Link to this definition">¶</a></dt>785<dd><p>Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched786off).</p>787</dd></dl>788 789<dl class="py attribute">790<dt class="sig sig-object py" id="http.cookiejar.DefaultCookiePolicy.DomainStrict">791<span class="sig-prename descclassname"><span class="pre">DefaultCookiePolicy.</span></span><span class="sig-name descname"><span class="pre">DomainStrict</span></span><a class="headerlink" href="#http.cookiejar.DefaultCookiePolicy.DomainStrict" title="Link to this definition">¶</a></dt>792<dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">DomainStrictNoDots|DomainStrictNonDomain</span></code>.</p>793</dd></dl>794 795</section>796<section id="cookie-objects">797<h2>Cookie Objects<a class="headerlink" href="#cookie-objects" title="Link to this heading">¶</a></h2>798<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 the799standard cookie-attributes specified in the various cookie standards.  The800correspondence is not one-to-one, because there are complicated rules for801assigning 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>802cookie-attributes contain equivalent information, and because <span class="target" id="index-21"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2109.html"><strong>RFC 2109</strong></a> cookies803may be ‘downgraded’ by <code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> from version 1 to version 0 (Netscape)804cookies.</p>805<p>Assignment to these attributes should not be necessary other than in rare806circumstances 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 enforce807internal consistency, so you should know what you’re doing if you do that.</p>808<dl class="py attribute">809<dt class="sig sig-object py" id="http.cookiejar.Cookie.version">810<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">version</span></span><a class="headerlink" href="#http.cookiejar.Cookie.version" title="Link to this definition">¶</a></dt>811<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://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> and812<span class="target" id="index-23"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/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 that813<code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in which814case <code class="xref py py-attr docutils literal notranslate"><span class="pre">version</span></code> is 0.</p>815</dd></dl>816 817<dl class="py attribute">818<dt class="sig sig-object py" id="http.cookiejar.Cookie.name">819<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#http.cookiejar.Cookie.name" title="Link to this definition">¶</a></dt>820<dd><p>Cookie name (a string).</p>821</dd></dl>822 823<dl class="py attribute">824<dt class="sig sig-object py" id="http.cookiejar.Cookie.value">825<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">value</span></span><a class="headerlink" href="#http.cookiejar.Cookie.value" title="Link to this definition">¶</a></dt>826<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>827</dd></dl>828 829<dl class="py attribute">830<dt class="sig sig-object py" id="http.cookiejar.Cookie.port">831<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">port</span></span><a class="headerlink" href="#http.cookiejar.Cookie.port" title="Link to this definition">¶</a></dt>832<dd><p>String representing a port or a set of ports (eg. ‘80’, or ‘80,8080’), or833<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>834</dd></dl>835 836<dl class="py attribute">837<dt class="sig sig-object py" id="http.cookiejar.Cookie.domain">838<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">domain</span></span><a class="headerlink" href="#http.cookiejar.Cookie.domain" title="Link to this definition">¶</a></dt>839<dd><p>Cookie domain (a string).</p>840</dd></dl>841 842<dl class="py attribute">843<dt class="sig sig-object py" id="http.cookiejar.Cookie.path">844<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">path</span></span><a class="headerlink" href="#http.cookiejar.Cookie.path" title="Link to this definition">¶</a></dt>845<dd><p>Cookie path (a string, eg. <code class="docutils literal notranslate"><span class="pre">'/acme/rocket_launchers'</span></code>).</p>846</dd></dl>847 848<dl class="py attribute">849<dt class="sig sig-object py" id="http.cookiejar.Cookie.secure">850<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">secure</span></span><a class="headerlink" href="#http.cookiejar.Cookie.secure" title="Link to this definition">¶</a></dt>851<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if cookie should only be returned over a secure connection.</p>852</dd></dl>853 854<dl class="py attribute">855<dt class="sig sig-object py" id="http.cookiejar.Cookie.expires">856<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">expires</span></span><a class="headerlink" href="#http.cookiejar.Cookie.expires" title="Link to this definition">¶</a></dt>857<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 the858<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>859</dd></dl>860 861<dl class="py attribute">862<dt class="sig sig-object py" id="http.cookiejar.Cookie.discard">863<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">discard</span></span><a class="headerlink" href="#http.cookiejar.Cookie.discard" title="Link to this definition">¶</a></dt>864<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if this is a session cookie.</p>865</dd></dl>866 867<dl class="py attribute">868<dt class="sig sig-object py" id="http.cookiejar.Cookie.comment">869<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">comment</span></span><a class="headerlink" href="#http.cookiejar.Cookie.comment" title="Link to this definition">¶</a></dt>870<dd><p>String comment from the server explaining the function of this cookie, or871<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>872</dd></dl>873 874<dl class="py attribute">875<dt class="sig sig-object py" id="http.cookiejar.Cookie.comment_url">876<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">comment_url</span></span><a class="headerlink" href="#http.cookiejar.Cookie.comment_url" title="Link to this definition">¶</a></dt>877<dd><p>URL linking to a comment from the server explaining the function of this cookie,878or <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>879</dd></dl>880 881<dl class="py attribute">882<dt class="sig sig-object py" id="http.cookiejar.Cookie.rfc2109">883<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">rfc2109</span></span><a class="headerlink" href="#http.cookiejar.Cookie.rfc2109" title="Link to this definition">¶</a></dt>884<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://datatracker.ietf.org/doc/html/rfc2109.html"><strong>RFC 2109</strong></a> cookie (ie. the cookie885arrived in a <em class="mailheader">Set-Cookie</em> header, and the value of the Version886cookie-attribute in that header was 1).  This attribute is provided because887<code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> may ‘downgrade’ RFC 2109 cookies to Netscape cookies, in888which 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>889</dd></dl>890 891<dl class="py attribute">892<dt class="sig sig-object py" id="http.cookiejar.Cookie.port_specified">893<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">port_specified</span></span><a class="headerlink" href="#http.cookiejar.Cookie.port_specified" title="Link to this definition">¶</a></dt>894<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 the895<em class="mailheader">Set-Cookie</em> / <em class="mailheader">Set-Cookie2</em> header).</p>896</dd></dl>897 898<dl class="py attribute">899<dt class="sig sig-object py" id="http.cookiejar.Cookie.domain_specified">900<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">domain_specified</span></span><a class="headerlink" href="#http.cookiejar.Cookie.domain_specified" title="Link to this definition">¶</a></dt>901<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if a domain was explicitly specified by the server.</p>902</dd></dl>903 904<dl class="py attribute">905<dt class="sig sig-object py" id="http.cookiejar.Cookie.domain_initial_dot">906<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">domain_initial_dot</span></span><a class="headerlink" href="#http.cookiejar.Cookie.domain_initial_dot" title="Link to this definition">¶</a></dt>907<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the domain explicitly specified by the server began with a dot908(<code class="docutils literal notranslate"><span class="pre">'.'</span></code>).</p>909</dd></dl>910 911<p>Cookies may have additional non-standard cookie-attributes.  These may be912accessed using the following methods:</p>913<dl class="py method">914<dt class="sig sig-object py" id="http.cookiejar.Cookie.has_nonstandard_attr">915<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">has_nonstandard_attr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.has_nonstandard_attr" title="Link to this definition">¶</a></dt>916<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if cookie has the named cookie-attribute.</p>917</dd></dl>918 919<dl class="py method">920<dt class="sig sig-object py" id="http.cookiejar.Cookie.get_nonstandard_attr">921<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">get_nonstandard_attr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.get_nonstandard_attr" title="Link to this definition">¶</a></dt>922<dd><p>If cookie has the named cookie-attribute, return its value. Otherwise, return923<em>default</em>.</p>924</dd></dl>925 926<dl class="py method">927<dt class="sig sig-object py" id="http.cookiejar.Cookie.set_nonstandard_attr">928<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">set_nonstandard_attr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.set_nonstandard_attr" title="Link to this definition">¶</a></dt>929<dd><p>Set the value of the named cookie-attribute.</p>930</dd></dl>931 932<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>933<dl class="py method">934<dt class="sig sig-object py" id="http.cookiejar.Cookie.is_expired">935<span class="sig-prename descclassname"><span class="pre">Cookie.</span></span><span class="sig-name descname"><span class="pre">is_expired</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">now</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#http.cookiejar.Cookie.is_expired" title="Link to this definition">¶</a></dt>936<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 should937expire.  If <em>now</em> is given (in seconds since the epoch), return whether the938cookie has expired at the specified time.</p>939</dd></dl>940 941</section>942<section id="examples">943<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>944<p>The first example shows the most common usage of <code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code>:</p>945<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">http.cookiejar</span><span class="o">,</span><span class="w"> </span><span class="nn">urllib.request</span>946<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>947<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>948<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">&quot;http://example.com/&quot;</span><span class="p">)</span>949</pre></div>950</div>951<p>This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx952cookies (assumes Unix/Netscape convention for location of the cookies file):</p>953<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">os</span><span class="o">,</span><span class="w"> </span><span class="nn">http.cookiejar</span><span class="o">,</span><span class="w"> </span><span class="nn">urllib.request</span>954<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>955<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">&quot;~&quot;</span><span class="p">),</span> <span class="s2">&quot;.netscape&quot;</span><span class="p">,</span> <span class="s2">&quot;cookies.txt&quot;</span><span class="p">))</span>956<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>957<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">&quot;http://example.com/&quot;</span><span class="p">)</span>958</pre></div>959</div>960<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 on961<span class="target" id="index-25"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2965.html"><strong>RFC 2965</strong></a> cookies, be more strict about domains when setting and returning962Netscape cookies, and block some domains from setting cookies or having them963returned:</p>964<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">urllib.request</span>965<span class="kn">from</span><span class="w"> </span><span class="nn">http.cookiejar</span><span class="w"> </span><span class="kn">import</span> <span class="n">CookieJar</span><span class="p">,</span> <span class="n">DefaultCookiePolicy</span>966<span class="n">policy</span> <span class="o">=</span> <span class="n">DefaultCookiePolicy</span><span class="p">(</span>967    <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>968    <span class="n">blocked_domains</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;ads.net&quot;</span><span class="p">,</span> <span class="s2">&quot;.ads.net&quot;</span><span class="p">])</span>969<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>970<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>971<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">&quot;http://example.com/&quot;</span><span class="p">)</span>972</pre></div>973</div>974</section>975</section>976 977 978            <div class="clearer"></div>979          </div>980        </div>981      </div>982      <div class="sphinxsidebar" role="navigation" aria-label="Main">983        <div class="sphinxsidebarwrapper">984  <div>985    <h3><a href="../contents.html">Table of Contents</a></h3>986    <ul>987<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>988<li><a class="reference internal" href="#cookiejar-and-filecookiejar-objects">CookieJar and FileCookieJar Objects</a></li>989<li><a class="reference internal" href="#filecookiejar-subclasses-and-co-operation-with-web-browsers">FileCookieJar subclasses and co-operation with web browsers</a></li>990<li><a class="reference internal" href="#cookiepolicy-objects">CookiePolicy Objects</a></li>991<li><a class="reference internal" href="#defaultcookiepolicy-objects">DefaultCookiePolicy Objects</a></li>992<li><a class="reference internal" href="#cookie-objects">Cookie Objects</a></li>993<li><a class="reference internal" href="#examples">Examples</a></li>994</ul>995</li>996</ul>997 998  </div>999  <div>1000    <h4>Previous topic</h4>1001    <p class="topless"><a href="http.cookies.html"1002                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookies</span></code> — HTTP state management</a></p>1003  </div>1004  <div>1005    <h4>Next topic</h4>1006    <p class="topless"><a href="xmlrpc.html"1007                          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>1008  </div>1009  <script>1010    document.addEventListener('DOMContentLoaded', () => {1011        const title = document.querySelector('meta[property="og:title"]').content;1012        const elements = document.querySelectorAll('.improvepage');1013        const pageurl = window.location.href.split('?')[0];1014        elements.forEach(element => {1015            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));1016            url.searchParams.set('pagetitle', title);1017            url.searchParams.set('pageurl', pageurl);1018            url.searchParams.set('pagesource', "library/http.cookiejar.rst");1019            element.href = url.toString();1020        });1021    });1022  </script>1023  <div role="note" aria-label="source link">1024    <h3>This page</h3>1025    <ul class="this-page-menu">1026      <li><a href="../bugs.html">Report a bug</a></li>1027      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>1028      <li>1029        <a href="https://github.com/python/cpython/blob/main/Doc/library/http.cookiejar.rst?plain=1"1030            rel="nofollow">Show source1031        </a>1032      </li>1033      1034    </ul>1035  </div>1036        </div>1037<div id="sidebarbutton" title="Collapse sidebar">1038<span>«</span>1039</div>1040 1041      </div>1042      <div class="clearer"></div>1043    </div>  1044    <div class="related" role="navigation" aria-label="Related">1045      <h3>Navigation</h3>1046      <ul>1047        <li class="right" style="margin-right: 10px">1048          <a href="../genindex.html" title="General Index"1049             >index</a></li>1050        <li class="right" >1051          <a href="../py-modindex.html" title="Python Module Index"1052             >modules</a> |</li>1053        <li class="right" >1054          <a href="xmlrpc.html" title="xmlrpc — XMLRPC server and client modules"1055             >next</a> |</li>1056        <li class="right" >1057          <a href="http.cookies.html" title="http.cookies — HTTP state management"1058             >previous</a> |</li>1059 1060          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>1061          <li><a href="https://www.python.org/">Python</a> &#187;</li>1062          <li class="switchers">1063            <div class="language_switcher_placeholder"></div>1064            <div class="version_switcher_placeholder"></div>1065          </li>1066          <li>1067              1068          </li>1069    <li id="cpython-language-and-version">1070      <a href="../index.html">3.15.0a6 Documentation</a> &#187;1071    </li>1072 1073          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>1074          <li class="nav-item nav-item-2"><a href="internet.html" >Internet Protocols and Support</a> &#187;</li>1075        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">http.cookiejar</span></code> — Cookie handling for HTTP clients</a></li>1076                <li class="right">1077                    1078 1079    <div class="inline-search" role="search">1080        <form class="inline-search" action="../search.html" method="get">1081          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">1082          <input type="submit" value="Go">1083        </form>1084    </div>1085                     |1086                </li>1087            <li class="right">1088<label class="theme-selector-label">1089    Theme1090    <select class="theme-selector" oninput="activateTheme(this.value)">1091        <option value="auto" selected>Auto</option>1092        <option value="light">Light</option>1093        <option value="dark">Dark</option>1094    </select>1095</label> |</li>1096            1097      </ul>1098    </div>  1099    <div class="footer">1100    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.1101    <br>1102    This page is licensed under the Python Software Foundation License Version 2.1103    <br>1104    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.1105    <br>1106    1107      See <a href="/license.html">History and License</a> for more information.<br>1108    1109    1110    <br>1111 1112    The Python Software Foundation is a non-profit corporation.1113<a href="https://www.python.org/psf/donations/">Please donate.</a>1114<br>1115    <br>1116      Last updated on Mar 10, 2026 (08:58 UTC).1117    1118      <a href="/bugs.html">Found a bug</a>?1119    1120    <br>1121 1122    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.1123    </div>1124 1125  </body>1126</html>