1 :mod:`http.cookiejar` --- Cookie handling for HTTP clients 2 ========================================================== 3 4 .. module:: http.cookiejar 5 :synopsis: Classes for automatic handling of HTTP cookies. 6 7 .. moduleauthor:: John J. Lee <jjl (a] pobox.com> 8 .. sectionauthor:: John J. Lee <jjl (a] pobox.com> 9 10 **Source code:** :source:`Lib/http/cookiejar.py` 11 12 -------------- 13 14 The :mod:`http.cookiejar` module defines classes for automatic handling of HTTP 15 cookies. It is useful for accessing web sites that require small pieces of data 16 -- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a 17 web server, and then returned to the server in later HTTP requests. 18 19 Both the regular Netscape cookie protocol and the protocol defined by 20 :rfc:`2965` are handled. RFC 2965 handling is switched off by default. 21 :rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated 22 either as Netscape or RFC 2965 cookies according to the 'policy' in effect. 23 Note that the great majority of cookies on the Internet are Netscape cookies. 24 :mod:`http.cookiejar` attempts to follow the de-facto Netscape cookie protocol (which 25 differs substantially from that set out in the original Netscape specification), 26 including taking note of the ``max-age`` and ``port`` cookie-attributes 27 introduced with RFC 2965. 28 29 .. note:: 30 31 The various named parameters found in :mailheader:`Set-Cookie` and 32 :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are 33 conventionally referred to as :dfn:`attributes`. To distinguish them from 34 Python attributes, the documentation for this module uses the term 35 :dfn:`cookie-attribute` instead. 36 37 38 The module defines the following exception: 39 40 41 .. exception:: LoadError 42 43 Instances of :class:`FileCookieJar` raise this exception on failure to load 44 cookies from a file. :exc:`LoadError` is a subclass of :exc:`OSError`. 45 46 .. versionchanged:: 3.3 47 LoadError was made a subclass of :exc:`OSError` instead of 48 :exc:`IOError`. 49 50 51 The following classes are provided: 52 53 54 .. class:: CookieJar(policy=None) 55 56 *policy* is an object implementing the :class:`CookiePolicy` interface. 57 58 The :class:`CookieJar` class stores HTTP cookies. It extracts cookies from HTTP 59 requests, and returns them in HTTP responses. :class:`CookieJar` instances 60 automatically expire contained cookies when necessary. Subclasses are also 61 responsible for storing and retrieving cookies from a file or database. 62 63 64 .. class:: FileCookieJar(filename, delayload=None, policy=None) 65 66 *policy* is an object implementing the :class:`CookiePolicy` interface. For the 67 other arguments, see the documentation for the corresponding attributes. 68 69 A :class:`CookieJar` which can load cookies from, and perhaps save cookies to, a 70 file on disk. Cookies are **NOT** loaded from the named file until either the 71 :meth:`load` or :meth:`revert` method is called. Subclasses of this class are 72 documented in section :ref:`file-cookie-jar-classes`. 73 74 75 .. class:: CookiePolicy() 76 77 This class is responsible for deciding whether each cookie should be accepted 78 from / returned to the server. 79 80 81 .. class:: DefaultCookiePolicy( blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False ) 82 83 Constructor arguments should be passed as keyword arguments only. 84 *blocked_domains* is a sequence of domain names that we never accept cookies 85 from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a 86 sequence of the only domains for which we accept and return cookies. For all 87 other arguments, see the documentation for :class:`CookiePolicy` and 88 :class:`DefaultCookiePolicy` objects. 89 90 :class:`DefaultCookiePolicy` implements the standard accept / reject rules for 91 Netscape and :rfc:`2965` cookies. By default, :rfc:`2109` cookies (ie. cookies 92 received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of 93 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling 94 is turned off or :attr:`rfc2109_as_netscape` is ``True``, RFC 2109 cookies are 95 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by 96 setting the :attr:`version` attribute of the :class:`Cookie` instance to 0. 97 :class:`DefaultCookiePolicy` also provides some parameters to allow some 98 fine-tuning of policy. 99 100 101 .. class:: Cookie() 102 103 This class represents Netscape, :rfc:`2109` and :rfc:`2965` cookies. It is not 104 expected that users of :mod:`http.cookiejar` construct their own :class:`Cookie` 105 instances. Instead, if necessary, call :meth:`make_cookies` on a 106 :class:`CookieJar` instance. 107 108 109 .. seealso:: 110 111 Module :mod:`urllib.request` 112 URL opening with automatic cookie handling. 113 114 Module :mod:`http.cookies` 115 HTTP cookie classes, principally useful for server-side code. The 116 :mod:`http.cookiejar` and :mod:`http.cookies` modules do not depend on each 117 other. 118 119 https://curl.haxx.se/rfc/cookie_spec.html 120 The specification of the original Netscape cookie protocol. Though this is 121 still the dominant protocol, the 'Netscape cookie protocol' implemented by all 122 the major browsers (and :mod:`http.cookiejar`) only bears a passing resemblance to 123 the one sketched out in ``cookie_spec.html``. 124 125 :rfc:`2109` - HTTP State Management Mechanism 126 Obsoleted by :rfc:`2965`. Uses :mailheader:`Set-Cookie` with version=1. 127 128 :rfc:`2965` - HTTP State Management Mechanism 129 The Netscape protocol with the bugs fixed. Uses :mailheader:`Set-Cookie2` in 130 place of :mailheader:`Set-Cookie`. Not widely used. 131 132 http://kristol.org/cookie/errata.html 133 Unfinished errata to :rfc:`2965`. 134 135 :rfc:`2964` - Use of HTTP State Management 136 137 .. _cookie-jar-objects: 138 139 CookieJar and FileCookieJar Objects 140 ----------------------------------- 141 142 :class:`CookieJar` objects support the :term:`iterator` protocol for iterating over 143 contained :class:`Cookie` objects. 144 145 :class:`CookieJar` has the following methods: 146 147 148 .. method:: CookieJar.add_cookie_header(request) 149 150 Add correct :mailheader:`Cookie` header to *request*. 151 152 If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of 153 the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false 154 respectively), the :mailheader:`Cookie2` header is also added when appropriate. 155 156 The *request* object (usually a :class:`urllib.request..Request` instance) 157 must support the methods :meth:`get_full_url`, :meth:`get_host`, 158 :meth:`get_type`, :meth:`unverifiable`, :meth:`has_header`, 159 :meth:`get_header`, :meth:`header_items`, :meth:`add_unredirected_header` 160 and :attr:`origin_req_host` attribute as documented by 161 :mod:`urllib.request`. 162 163 .. versionchanged:: 3.3 164 165 *request* object needs :attr:`origin_req_host` attribute. Dependency on a 166 deprecated method :meth:`get_origin_req_host` has been removed. 167 168 169 .. method:: CookieJar.extract_cookies(response, request) 170 171 Extract cookies from HTTP *response* and store them in the :class:`CookieJar`, 172 where allowed by policy. 173 174 The :class:`CookieJar` will look for allowable :mailheader:`Set-Cookie` and 175 :mailheader:`Set-Cookie2` headers in the *response* argument, and store cookies 176 as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval). 177 178 The *response* object (usually the result of a call to 179 :meth:`urllib.request.urlopen`, or similar) should support an :meth:`info` 180 method, which returns an :class:`email.message.Message` instance. 181 182 The *request* object (usually a :class:`urllib.request.Request` instance) 183 must support the methods :meth:`get_full_url`, :meth:`get_host`, 184 :meth:`unverifiable`, and :attr:`origin_req_host` attribute, as documented 185 by :mod:`urllib.request`. The request is used to set default values for 186 cookie-attributes as well as for checking that the cookie is allowed to be 187 set. 188 189 .. versionchanged:: 3.3 190 191 *request* object needs :attr:`origin_req_host` attribute. Dependency on a 192 deprecated method :meth:`get_origin_req_host` has been removed. 193 194 .. method:: CookieJar.set_policy(policy) 195 196 Set the :class:`CookiePolicy` instance to be used. 197 198 199 .. method:: CookieJar.make_cookies(response, request) 200 201 Return sequence of :class:`Cookie` objects extracted from *response* object. 202 203 See the documentation for :meth:`extract_cookies` for the interfaces required of 204 the *response* and *request* arguments. 205 206 207 .. method:: CookieJar.set_cookie_if_ok(cookie, request) 208 209 Set a :class:`Cookie` if policy says it's OK to do so. 210 211 212 .. method:: CookieJar.set_cookie(cookie) 213 214 Set a :class:`Cookie`, without checking with policy to see whether or not it 215 should be set. 216 217 218 .. method:: CookieJar.clear([domain[, path[, name]]]) 219 220 Clear some cookies. 221 222 If invoked without arguments, clear all cookies. If given a single argument, 223 only cookies belonging to that *domain* will be removed. If given two arguments, 224 cookies belonging to the specified *domain* and URL *path* are removed. If 225 given three arguments, then the cookie with the specified *domain*, *path* and 226 *name* is removed. 227 228 Raises :exc:`KeyError` if no matching cookie exists. 229 230 231 .. method:: CookieJar.clear_session_cookies() 232 233 Discard all session cookies. 234 235 Discards all contained cookies that have a true :attr:`discard` attribute 236 (usually because they had either no ``max-age`` or ``expires`` cookie-attribute, 237 or an explicit ``discard`` cookie-attribute). For interactive browsers, the end 238 of a session usually corresponds to closing the browser window. 239 240 Note that the :meth:`save` method won't save session cookies anyway, unless you 241 ask otherwise by passing a true *ignore_discard* argument. 242 243 :class:`FileCookieJar` implements the following additional methods: 244 245 246 .. method:: FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False) 247 248 Save cookies to a file. 249 250 This base class raises :exc:`NotImplementedError`. Subclasses may leave this 251 method unimplemented. 252 253 *filename* is the name of file in which to save cookies. If *filename* is not 254 specified, :attr:`self.filename` is used (whose default is the value passed to 255 the constructor, if any); if :attr:`self.filename` is :const:`None`, 256 :exc:`ValueError` is raised. 257 258 *ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save 259 even cookies that have expired 260 261 The file is overwritten if it already exists, thus wiping all the cookies it 262 contains. Saved cookies can be restored later using the :meth:`load` or 263 :meth:`revert` methods. 264 265 266 .. method:: FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False) 267 268 Load cookies from a file. 269 270 Old cookies are kept unless overwritten by newly loaded ones. 271 272 Arguments are as for :meth:`save`. 273 274 The named file must be in the format understood by the class, or 275 :exc:`LoadError` will be raised. Also, :exc:`OSError` may be raised, for 276 example if the file does not exist. 277 278 .. versionchanged:: 3.3 279 :exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`. 280 281 282 .. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False) 283 284 Clear all cookies and reload cookies from a saved file. 285 286 :meth:`revert` can raise the same exceptions as :meth:`load`. If there is a 287 failure, the object's state will not be altered. 288 289 :class:`FileCookieJar` instances have the following public attributes: 290 291 292 .. attribute:: FileCookieJar.filename 293 294 Filename of default file in which to keep cookies. This attribute may be 295 assigned to. 296 297 298 .. attribute:: FileCookieJar.delayload 299 300 If true, load cookies lazily from disk. This attribute should not be assigned 301 to. This is only a hint, since this only affects performance, not behaviour 302 (unless the cookies on disk are changing). A :class:`CookieJar` object may 303 ignore it. None of the :class:`FileCookieJar` classes included in the standard 304 library lazily loads cookies. 305 306 307 .. _file-cookie-jar-classes: 308 309 FileCookieJar subclasses and co-operation with web browsers 310 ----------------------------------------------------------- 311 312 The following :class:`CookieJar` subclasses are provided for reading and 313 writing. 314 315 .. class:: MozillaCookieJar(filename, delayload=None, policy=None) 316 317 A :class:`FileCookieJar` that can load from and save cookies to disk in the 318 Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape 319 browsers). 320 321 .. note:: 322 323 This loses information about :rfc:`2965` cookies, and also about newer or 324 non-standard cookie-attributes such as ``port``. 325 326 .. warning:: 327 328 Back up your cookies before saving if you have cookies whose loss / corruption 329 would be inconvenient (there are some subtleties which may lead to slight 330 changes in the file over a load / save round-trip). 331 332 Also note that cookies saved while Mozilla is running will get clobbered by 333 Mozilla. 334 335 336 .. class:: LWPCookieJar(filename, delayload=None, policy=None) 337 338 A :class:`FileCookieJar` that can load from and save cookies to disk in format 339 compatible with the libwww-perl library's ``Set-Cookie3`` file format. This is 340 convenient if you want to store cookies in a human-readable file. 341 342 343 .. _cookie-policy-objects: 344 345 CookiePolicy Objects 346 -------------------- 347 348 Objects implementing the :class:`CookiePolicy` interface have the following 349 methods: 350 351 352 .. method:: CookiePolicy.set_ok(cookie, request) 353 354 Return boolean value indicating whether cookie should be accepted from server. 355 356 *cookie* is a :class:`Cookie` instance. *request* is an object 357 implementing the interface defined by the documentation for 358 :meth:`CookieJar.extract_cookies`. 359 360 361 .. method:: CookiePolicy.return_ok(cookie, request) 362 363 Return boolean value indicating whether cookie should be returned to server. 364 365 *cookie* is a :class:`Cookie` instance. *request* is an object 366 implementing the interface defined by the documentation for 367 :meth:`CookieJar.add_cookie_header`. 368 369 370 .. method:: CookiePolicy.domain_return_ok(domain, request) 371 372 Return false if cookies should not be returned, given cookie domain. 373 374 This method is an optimization. It removes the need for checking every cookie 375 with a particular domain (which might involve reading many files). Returning 376 true from :meth:`domain_return_ok` and :meth:`path_return_ok` leaves all the 377 work to :meth:`return_ok`. 378 379 If :meth:`domain_return_ok` returns true for the cookie domain, 380 :meth:`path_return_ok` is called for the cookie path. Otherwise, 381 :meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie 382 domain. If :meth:`path_return_ok` returns true, :meth:`return_ok` is called 383 with the :class:`Cookie` object itself for a full check. Otherwise, 384 :meth:`return_ok` is never called for that cookie path. 385 386 Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just 387 for the *request* domain. For example, the function might be called with both 388 ``".example.com"`` and ``"www.example.com"`` if the request domain is 389 ``"www.example.com"``. The same goes for :meth:`path_return_ok`. 390 391 The *request* argument is as documented for :meth:`return_ok`. 392 393 394 .. method:: CookiePolicy.path_return_ok(path, request) 395 396 Return false if cookies should not be returned, given cookie path. 397 398 See the documentation for :meth:`domain_return_ok`. 399 400 In addition to implementing the methods above, implementations of the 401 :class:`CookiePolicy` interface must also supply the following attributes, 402 indicating which protocols should be used, and how. All of these attributes may 403 be assigned to. 404 405 406 .. attribute:: CookiePolicy.netscape 407 408 Implement Netscape protocol. 409 410 411 .. attribute:: CookiePolicy.rfc2965 412 413 Implement :rfc:`2965` protocol. 414 415 416 .. attribute:: CookiePolicy.hide_cookie2 417 418 Don't add :mailheader:`Cookie2` header to requests (the presence of this header 419 indicates to the server that we understand :rfc:`2965` cookies). 420 421 The most useful way to define a :class:`CookiePolicy` class is by subclassing 422 from :class:`DefaultCookiePolicy` and overriding some or all of the methods 423 above. :class:`CookiePolicy` itself may be used as a 'null policy' to allow 424 setting and receiving any and all cookies (this is unlikely to be useful). 425 426 427 .. _default-cookie-policy-objects: 428 429 DefaultCookiePolicy Objects 430 --------------------------- 431 432 Implements the standard rules for accepting and returning cookies. 433 434 Both :rfc:`2965` and Netscape cookies are covered. RFC 2965 handling is switched 435 off by default. 436 437 The easiest way to provide your own policy is to override this class and call 438 its methods in your overridden implementations before adding your own additional 439 checks:: 440 441 import http.cookiejar 442 class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy): 443 def set_ok(self, cookie, request): 444 if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request): 445 return False 446 if i_dont_want_to_store_this_cookie(cookie): 447 return False 448 return True 449 450 In addition to the features required to implement the :class:`CookiePolicy` 451 interface, this class allows you to block and allow domains from setting and 452 receiving cookies. There are also some strictness switches that allow you to 453 tighten up the rather loose Netscape protocol rules a little bit (at the cost of 454 blocking some benign cookies). 455 456 A domain blacklist and whitelist is provided (both off by default). Only domains 457 not in the blacklist and present in the whitelist (if the whitelist is active) 458 participate in cookie setting and returning. Use the *blocked_domains* 459 constructor argument, and :meth:`blocked_domains` and 460 :meth:`set_blocked_domains` methods (and the corresponding argument and methods 461 for *allowed_domains*). If you set a whitelist, you can turn it off again by 462 setting it to :const:`None`. 463 464 Domains in block or allow lists that do not start with a dot must equal the 465 cookie domain to be matched. For example, ``"example.com"`` matches a blacklist 466 entry of ``"example.com"``, but ``"www.example.com"`` does not. Domains that do 467 start with a dot are matched by more specific domains too. For example, both 468 ``"www.example.com"`` and ``"www.coyote.example.com"`` match ``".example.com"`` 469 (but ``"example.com"`` itself does not). IP addresses are an exception, and 470 must match exactly. For example, if blocked_domains contains ``"192.168.1.2"`` 471 and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not. 472 473 :class:`DefaultCookiePolicy` implements the following additional methods: 474 475 476 .. method:: DefaultCookiePolicy.blocked_domains() 477 478 Return the sequence of blocked domains (as a tuple). 479 480 481 .. method:: DefaultCookiePolicy.set_blocked_domains(blocked_domains) 482 483 Set the sequence of blocked domains. 484 485 486 .. method:: DefaultCookiePolicy.is_blocked(domain) 487 488 Return whether *domain* is on the blacklist for setting or receiving cookies. 489 490 491 .. method:: DefaultCookiePolicy.allowed_domains() 492 493 Return :const:`None`, or the sequence of allowed domains (as a tuple). 494 495 496 .. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains) 497 498 Set the sequence of allowed domains, or :const:`None`. 499 500 501 .. method:: DefaultCookiePolicy.is_not_allowed(domain) 502 503 Return whether *domain* is not on the whitelist for setting or receiving 504 cookies. 505 506 :class:`DefaultCookiePolicy` instances have the following attributes, which are 507 all initialised from the constructor arguments of the same name, and which may 508 all be assigned to. 509 510 511 .. attribute:: DefaultCookiePolicy.rfc2109_as_netscape 512 513 If true, request that the :class:`CookieJar` instance downgrade :rfc:`2109` cookies 514 (ie. cookies received in a :mailheader:`Set-Cookie` header with a version 515 cookie-attribute of 1) to Netscape cookies by setting the version attribute of 516 the :class:`Cookie` instance to 0. The default value is :const:`None`, in which 517 case RFC 2109 cookies are downgraded if and only if :rfc:`2965` handling is turned 518 off. Therefore, RFC 2109 cookies are downgraded by default. 519 520 521 General strictness switches: 522 523 .. attribute:: DefaultCookiePolicy.strict_domain 524 525 Don't allow sites to set two-component domains with country-code top-level 526 domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc. This is far from perfect 527 and isn't guaranteed to work! 528 529 530 :rfc:`2965` protocol strictness switches: 531 532 .. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable 533 534 Follow :rfc:`2965` rules on unverifiable transactions (usually, an unverifiable 535 transaction is one resulting from a redirect or a request for an image hosted on 536 another site). If this is false, cookies are *never* blocked on the basis of 537 verifiability 538 539 540 Netscape protocol strictness switches: 541 542 .. attribute:: DefaultCookiePolicy.strict_ns_unverifiable 543 544 Apply :rfc:`2965` rules on unverifiable transactions even to Netscape cookies. 545 546 547 .. attribute:: DefaultCookiePolicy.strict_ns_domain 548 549 Flags indicating how strict to be with domain-matching rules for Netscape 550 cookies. See below for acceptable values. 551 552 553 .. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar 554 555 Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``. 556 557 558 .. attribute:: DefaultCookiePolicy.strict_ns_set_path 559 560 Don't allow setting cookies whose path doesn't path-match request URI. 561 562 :attr:`strict_ns_domain` is a collection of flags. Its value is constructed by 563 or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means 564 both flags are set). 565 566 567 .. attribute:: DefaultCookiePolicy.DomainStrictNoDots 568 569 When setting cookies, the 'host prefix' must not contain a dot (eg. 570 ``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo`` 571 contains a dot). 572 573 574 .. attribute:: DefaultCookiePolicy.DomainStrictNonDomain 575 576 Cookies that did not explicitly specify a ``domain`` cookie-attribute can only 577 be returned to a domain equal to the domain that set the cookie (eg. 578 ``spam.example.com`` won't be returned cookies from ``example.com`` that had no 579 ``domain`` cookie-attribute). 580 581 582 .. attribute:: DefaultCookiePolicy.DomainRFC2965Match 583 584 When setting cookies, require a full :rfc:`2965` domain-match. 585 586 The following attributes are provided for convenience, and are the most useful 587 combinations of the above flags: 588 589 590 .. attribute:: DefaultCookiePolicy.DomainLiberal 591 592 Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched 593 off). 594 595 596 .. attribute:: DefaultCookiePolicy.DomainStrict 597 598 Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``. 599 600 601 Cookie Objects 602 -------------- 603 604 :class:`Cookie` instances have Python attributes roughly corresponding to the 605 standard cookie-attributes specified in the various cookie standards. The 606 correspondence is not one-to-one, because there are complicated rules for 607 assigning default values, because the ``max-age`` and ``expires`` 608 cookie-attributes contain equivalent information, and because :rfc:`2109` cookies 609 may be 'downgraded' by :mod:`http.cookiejar` from version 1 to version 0 (Netscape) 610 cookies. 611 612 Assignment to these attributes should not be necessary other than in rare 613 circumstances in a :class:`CookiePolicy` method. The class does not enforce 614 internal consistency, so you should know what you're doing if you do that. 615 616 617 .. attribute:: Cookie.version 618 619 Integer or :const:`None`. Netscape cookies have :attr:`version` 0. :rfc:`2965` and 620 :rfc:`2109` cookies have a ``version`` cookie-attribute of 1. However, note that 621 :mod:`http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which 622 case :attr:`version` is 0. 623 624 625 .. attribute:: Cookie.name 626 627 Cookie name (a string). 628 629 630 .. attribute:: Cookie.value 631 632 Cookie value (a string), or :const:`None`. 633 634 635 .. attribute:: Cookie.port 636 637 String representing a port or a set of ports (eg. '80', or '80,8080'), or 638 :const:`None`. 639 640 641 .. attribute:: Cookie.path 642 643 Cookie path (a string, eg. ``'/acme/rocket_launchers'``). 644 645 646 .. attribute:: Cookie.secure 647 648 ``True`` if cookie should only be returned over a secure connection. 649 650 651 .. attribute:: Cookie.expires 652 653 Integer expiry date in seconds since epoch, or :const:`None`. See also the 654 :meth:`is_expired` method. 655 656 657 .. attribute:: Cookie.discard 658 659 ``True`` if this is a session cookie. 660 661 662 .. attribute:: Cookie.comment 663 664 String comment from the server explaining the function of this cookie, or 665 :const:`None`. 666 667 668 .. attribute:: Cookie.comment_url 669 670 URL linking to a comment from the server explaining the function of this cookie, 671 or :const:`None`. 672 673 674 .. attribute:: Cookie.rfc2109 675 676 ``True`` if this cookie was received as an :rfc:`2109` cookie (ie. the cookie 677 arrived in a :mailheader:`Set-Cookie` header, and the value of the Version 678 cookie-attribute in that header was 1). This attribute is provided because 679 :mod:`http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in 680 which case :attr:`version` is 0. 681 682 683 .. attribute:: Cookie.port_specified 684 685 ``True`` if a port or set of ports was explicitly specified by the server (in the 686 :mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header). 687 688 689 .. attribute:: Cookie.domain_specified 690 691 ``True`` if a domain was explicitly specified by the server. 692 693 694 .. attribute:: Cookie.domain_initial_dot 695 696 ``True`` if the domain explicitly specified by the server began with a dot 697 (``'.'``). 698 699 Cookies may have additional non-standard cookie-attributes. These may be 700 accessed using the following methods: 701 702 703 .. method:: Cookie.has_nonstandard_attr(name) 704 705 Return true if cookie has the named cookie-attribute. 706 707 708 .. method:: Cookie.get_nonstandard_attr(name, default=None) 709 710 If cookie has the named cookie-attribute, return its value. Otherwise, return 711 *default*. 712 713 714 .. method:: Cookie.set_nonstandard_attr(name, value) 715 716 Set the value of the named cookie-attribute. 717 718 The :class:`Cookie` class also defines the following method: 719 720 721 .. method:: Cookie.is_expired(now=None) 722 723 ``True`` if cookie has passed the time at which the server requested it should 724 expire. If *now* is given (in seconds since the epoch), return whether the 725 cookie has expired at the specified time. 726 727 728 Examples 729 -------- 730 731 The first example shows the most common usage of :mod:`http.cookiejar`:: 732 733 import http.cookiejar, urllib.request 734 cj = http.cookiejar.CookieJar() 735 opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj)) 736 r = opener.open("http://example.com/") 737 738 This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx 739 cookies (assumes Unix/Netscape convention for location of the cookies file):: 740 741 import os, http.cookiejar, urllib.request 742 cj = http.cookiejar.MozillaCookieJar() 743 cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt")) 744 opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj)) 745 r = opener.open("http://example.com/") 746 747 The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on 748 :rfc:`2965` cookies, be more strict about domains when setting and returning 749 Netscape cookies, and block some domains from setting cookies or having them 750 returned:: 751 752 import urllib.request 753 from http.cookiejar import CookieJar, DefaultCookiePolicy 754 policy = DefaultCookiePolicy( 755 rfc2965=True, strict_ns_domain=Policy.DomainStrict, 756 blocked_domains=["ads.net", ".ads.net"]) 757 cj = CookieJar(policy) 758 opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj)) 759 r = opener.open("http://example.com/") 760 761
