http.cookiejar — Cookie handling for HTTP clients

Вихідний код: 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 – to be set on the client machine by an HTTP response from a web server, and then returned to the server in later HTTP requests.

Both the regular Netscape cookie protocol and the protocol defined by RFC 2965 are handled. RFC 2965 handling is switched off by default. RFC 2109 cookies are parsed as Netscape cookies and subsequently treated either as Netscape or RFC 2965 cookies according to the „policy“ in effect. Note that the great majority of cookies on the internet are Netscape cookies. http.cookiejar attempts to follow the de-facto Netscape cookie protocol (which differs substantially from that set out in the original Netscape specification), including taking note of the max-age and port cookie-attributes introduced with RFC 2965.

Примітка

The various named parameters found in Set-Cookie and Set-Cookie2 headers (for example, domain and expires) are conventionally referred to as attributes. To distinguish them from Python attributes, the documentation for this module uses the term cookie-attribute instead.

Модуль визначає такий виняток:

exception http.cookiejar.LoadError

Екземпляри FileCookieJar викликають цей виняток, якщо неможливо завантажити файли cookie з файлу. LoadError є підкласом OSError.

Змінено в версії 3.3: LoadError used to be a subtype of IOError, which is now an alias of OSError.

Передбачені такі заняття:

class http.cookiejar.CookieJar(policy=None)

policy — це об’єкт, що реалізує інтерфейс CookiePolicy.

Клас CookieJar зберігає файли cookie HTTP. Він витягує файли cookie із HTTP-запитів і повертає їх у HTTP-відповідях. Примірники CookieJar автоматично припиняють дію файлів cookie, коли це необхідно. Підкласи також відповідають за зберігання та отримання файлів cookie з файлу або бази даних.

class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)

policy — це об’єкт, що реалізує інтерфейс CookiePolicy. Інші аргументи дивіться в документації для відповідних атрибутів.

CookieJar, який може завантажувати файли cookie з файлу на диску та, можливо, зберігати файли cookie. Файли cookie НЕ завантажуються з названого файлу, доки не буде викликано метод load() або revert(). Підкласи цього класу задокументовані в розділі Підкласи FileCookieJar і співпраця з веб-браузерами.

This should not be initialized directly – use its subclasses below instead.

Змінено в версії 3.8: Параметр імені файлу підтримує path-like object.

class http.cookiejar.CookiePolicy

Цей клас відповідає за прийняття рішення про прийняття кожного файлу cookie від сервера або повернення на нього.

class http.cookiejar.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, secure_protocols=('https', 'wss'))

Constructor arguments should be passed as keyword arguments only. blocked_domains is a sequence of domain names that we never accept cookies from, nor return cookies to. allowed_domains if not None, this is a sequence of the only domains for which we accept and return cookies. secure_protocols is a sequence of protocols for which secure cookies can be added to. By default https and wss (secure websocket) are considered secure protocols. For all other arguments, see the documentation for CookiePolicy and DefaultCookiePolicy objects.

DefaultCookiePolicy implements the standard accept / reject rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (that is, cookies received in a Set-Cookie header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling is turned off or rfc2109_as_netscape is True, RFC 2109 cookies are „downgraded“ by the CookieJar instance to Netscape cookies, by setting the version attribute of the Cookie instance to 0. DefaultCookiePolicy also provides some parameters to allow some fine-tuning of policy.

class http.cookiejar.Cookie

This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not expected that users of http.cookiejar construct their own Cookie instances. Instead, if necessary, call make_cookies() on a CookieJar instance.

Дивись також

Модуль urllib.request

Відкриття URL-адреси з автоматичною обробкою файлів cookie.

Модуль http.cookies

HTTP cookie classes, principally useful for server-side code. The http.cookiejar and http.cookies modules do not depend on each other.

https://curl.se/rfc/cookie_spec.html

The specification of the original Netscape cookie protocol. Though this is still the dominant protocol, the „Netscape cookie protocol“ implemented by all the major browsers (and http.cookiejar) only bears a passing resemblance to the one sketched out in cookie_spec.html.

RFC 2109 - механізм керування станом HTTP

Застаріло RFC 2965. Використовує Set-Cookie з версією=1.

RFC 2965 - механізм керування станом HTTP

Протокол Netscape з виправленими помилками. Використовує Set-Cookie2 замість Set-Cookie. Широко не використовується.

https://kristol.org/cookie/errata.html

Незавершені помилки до RFC 2965.

RFC 2964 - Використання керування станом HTTP

CookieJar and FileCookieJar objects

Об’єкти CookieJar підтримують протокол iterator для ітерації об’єктів Cookie.

CookieJar має такі методи:

Додайте правильний заголовок Cookie до запиту.

If policy allows (that is, the rfc2965 and hide_cookie2 attributes of the CookieJar’s CookiePolicy instance are true and false respectively), the Cookie2 header is also added when appropriate.

The request object (usually a urllib.request.Request instance) must support the methods get_full_url(), has_header(), get_header(), header_items(), add_unredirected_header() and the attributes host, type, unverifiable and origin_req_host as documented by urllib.request.

Змінено в версії 3.3: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.

CookieJar.extract_cookies(response, request)

Отримайте файли cookie з відповіді HTTP та зберігайте їх у CookieJar, де це дозволено політикою.

CookieJar шукатиме допустимі заголовки Set-Cookie і Set-Cookie2 в аргументі response і зберігатиме файли cookie відповідно (згідно з CookiePolicy .set_ok() підтвердження методу).

The response object (usually the result of a call to urllib.request.urlopen(), or similar) should support an info() method, which returns an email.message.Message instance.

The request object (usually a urllib.request.Request instance) must support the method get_full_url() and the attributes host, unverifiable and origin_req_host, as documented by urllib.request. The request is used to set default values for cookie-attributes as well as for checking that the cookie is allowed to be set.

Змінено в версії 3.3: request object needs origin_req_host attribute. Dependency on a deprecated method get_origin_req_host() has been removed.

CookieJar.set_policy(policy)

Встановіть екземпляр CookiePolicy для використання.

CookieJar.make_cookies(response, request)

Послідовність повернення об’єктів Cookie, отриманих з об’єкта response.

Перегляньте документацію для extract_cookies() для інтерфейсів, необхідних для аргументів response і request.

Встановіть Cookie, якщо політика стверджує, що це допустимо.

Встановіть Cookie, не перевіряючи політику, чи потрібно його встановлювати.

CookieJar.clear([domain[, path[, name]]])

Очистити деякі файли cookie.

Якщо виклик викликаний без аргументів, видалити всі файли cookie. Якщо надати один аргумент, буде видалено лише файли cookie, що належать цьому домену. Якщо задано два аргументи, файли cookie, що належать до вказаного домену та шляху URL-адреси, видаляються. Якщо задано три аргументи, файл cookie з указаним доменом, шляхом і ім’ям видаляється.

Викликає KeyError, якщо не існує відповідного файлу cookie.

CookieJar.clear_session_cookies()

Видалити всі файли cookie сесії.

Discards all contained cookies that have a true discard attribute (usually because they had either no max-age or expires cookie-attribute, or an explicit discard cookie-attribute). For interactive browsers, the end of a session usually corresponds to closing the browser window.

Note that the save() method won’t save session cookies anyway, unless you ask otherwise by passing a true ignore_discard argument.

FileCookieJar реалізує такі додаткові методи:

FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)

Збережіть файли cookie у файл.

Цей базовий клас викликає NotImplementedError. Підкласи можуть залишати цей метод нереалізованим.

filename is the name of file in which to save cookies. If filename is not specified, self.filename is used (whose default is the value passed to the constructor, if any); if self.filename is None, ValueError is raised.

ignore_discard: зберегти навіть файли cookie, налаштовані на видалення. ignore_expires: зберігати навіть файли cookie, термін дії яких закінчився

Файл перезаписується, якщо він уже існує, таким чином знищуючи всі файли cookie, які він містить. Збережені файли cookie можна відновити пізніше за допомогою методів load() або revert().

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

Завантажити файли cookie з файлу.

Старі файли cookie зберігаються, якщо вони не перезаписані новозавантаженими.

Аргументи такі ж, як для save().

Названий файл має бути у форматі, зрозумілому класу, інакше виникне LoadError. Крім того, може виникати OSError, наприклад, якщо файл не існує.

Змінено в версії 3.3: IOError раніше викликався, тепер це псевдонім OSError.

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

Очистіть усі файли cookie та перезавантажте файли cookie зі збереженого файлу.

revert() може викликати ті самі винятки, що і load(). Якщо станеться збій, стан об’єкта не зміниться.

Екземпляри FileCookieJar мають такі публічні атрибути:

FileCookieJar.filename

Назва файлу за замовчуванням, у якому зберігатимуться файли cookie. Цей атрибут можна призначити.

FileCookieJar.delayload

Якщо істина, ліниво завантажувати файли cookie з диска. Цей атрибут не слід призначати. Це лише підказка, оскільки це впливає лише на продуктивність, а не на поведінку (якщо файли cookie на диску не змінюються). Об’єкт CookieJar може його ігнорувати. Жоден із класів FileCookieJar, включених до стандартної бібліотеки, не завантажує файли cookie ліниво.

Підкласи FileCookieJar і співпраця з веб-браузерами

Наступні підкласи CookieJar надаються для читання та запису.

class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)

A FileCookieJar that can load from and save cookies to disk in the Mozilla cookies.txt file format (which is also used by curl and the Lynx and Netscape browsers).

Примітка

Це втрачає інформацію про RFC 2965 файли cookie, а також про нові або нестандартні атрибути файлів cookie, такі як порт.

Попередження

Зробіть резервну копію файлів cookie перед збереженням, якщо у вас є файли cookie, втрата/пошкодження яких було б незручним (є деякі тонкощі, які можуть призвести до незначних змін у файлі під час завантаження/збереження в обидві сторони).

Також зауважте, що файли cookie, збережені під час роботи Mozilla, будуть видалені Mozilla.

class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)

FileCookieJar, який може завантажувати та зберігати файли cookie на диск у форматі, сумісному з форматом файлу Set-Cookie3 бібліотеки libwww-perl. Це зручно, якщо ви хочете зберігати файли cookie у файлі, який читає людина.

Змінено в версії 3.8: Параметр імені файлу підтримує path-like object.

CookiePolicy objects

Об’єкти, що реалізують інтерфейс CookiePolicy, мають такі методи:

CookiePolicy.set_ok(cookie, request)

Повертає логічне значення, яке вказує, чи слід прийняти cookie від сервера.

cookie є екземпляром Cookie. request — це об’єкт, що реалізує інтерфейс, визначений документацією для CookieJar.extract_cookies().

CookiePolicy.return_ok(cookie, request)

Повернути логічне значення, яке вказує, чи потрібно повертати файл cookie на сервер.

cookie є екземпляром Cookie. request — це об’єкт, що реалізує інтерфейс, визначений документацією для CookieJar.add_cookie_header().

CookiePolicy.domain_return_ok(domain, request)

Повертає False, якщо файли cookie не повинні повертатися, враховуючи домен файлів cookie.

Цей метод є оптимізаційним. Це позбавляє від необхідності перевіряти кожен файл cookie з певним доменом (що може передбачати читання багатьох файлів). Повернення true з domain_return_ok() і path_return_ok() залишає всю роботу return_ok().

Якщо domain_return_ok() повертає true для домену cookie, path_return_ok() викликається для шляху до cookie. В іншому випадку path_return_ok() і return_ok() ніколи не викликаються для цього домену cookie. Якщо path_return_ok() повертає true, return_ok() викликається з самим об’єктом Cookie для повної перевірки. Інакше return_ok() ніколи не викликається для цього шляху cookie.

Зауважте, що domain_return_ok() викликається для кожного домену cookie, а не лише для домену request. Наприклад, функція може бути викликана як з ".example.com", так і з "www.example.com", якщо домен запиту "www.example.com". Те саме стосується path_return_ok().

Аргумент request відповідає документації для return_ok().

CookiePolicy.path_return_ok(path, request)

Повертає False, якщо файли cookie не повинні повертатися, враховуючи шлях до файлів cookie.

Перегляньте документацію для domain_return_ok().

На додаток до реалізації наведених вище методів, реалізації інтерфейсу CookiePolicy також повинні надавати такі атрибути, що вказують, які протоколи слід використовувати та як. Усі ці атрибути можна призначити.

CookiePolicy.netscape

Впровадити протокол Netscape.

CookiePolicy.rfc2965

Впровадити протокол RFC 2965.

CookiePolicy.hide_cookie2

Не додавайте заголовок Cookie2 до запитів (наявність цього заголовка вказує серверу, що ми розуміємо файли cookie RFC 2965).

Найкориснішим способом визначення класу CookiePolicy є створення підкласу з DefaultCookiePolicy і перевизначення деяких або всіх методів вище. Сама CookiePolicy може використовуватися як «нульова політика», щоб дозволити встановлення та отримання будь-яких і всіх файлів cookie (це навряд чи буде корисним).

DefaultCookiePolicy objects

Реалізує стандартні правила прийому та повернення файлів cookie.

Охоплено файли cookie RFC 2965 і Netscape. Обробку RFC 2965 вимкнено за замовчуванням.

Найпростіший спосіб надати власну політику — перевизначити цей клас і викликати його методи у своїх перевизначених реалізаціях перед додаванням власних додаткових перевірок:

import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True

На додаток до функцій, необхідних для реалізації інтерфейсу CookiePolicy, цей клас дозволяє блокувати та дозволяти доменам установлювати та отримувати файли cookie. Є також деякі перемикачі суворості, які дозволяють трохи посилити досить вільні правила протоколу Netscape (ціною блокування деяких безпечних файлів cookie).

A domain blocklist and allowlist is provided (both off by default). Only domains not in the blocklist and present in the allowlist (if the allowlist is active) participate in cookie setting and returning. Use the blocked_domains constructor argument, and blocked_domains() and set_blocked_domains() methods (and the corresponding argument and methods for allowed_domains). If you set an allowlist, you can turn it off again by setting it to None.

Домени в списках блокування або дозволу, які не починаються з крапки, мають збігатися з доменом файлів cookie, який потрібно знайти. Наприклад, "example.com" відповідає запису списку блокувань "example.com", але "www.example.com" ні. Домени, які починаються з крапки, також відповідають більш конкретним доменам. Наприклад, і "www.example.com", і "www.coyote.example.com" відповідають ".example.com" (але "example.com" сам по собі не робить). IP-адреси є винятком і мають точно збігатися. Наприклад, якщо blocked_domains містить "192.168.1.2" і ".168.1.2", 192.168.1.2 заблоковано, а 193.168.1.2 – ні.

DefaultCookiePolicy реалізує такі додаткові методи:

DefaultCookiePolicy.blocked_domains()

Повертає послідовність заблокованих доменів (у вигляді кортежу).

DefaultCookiePolicy.set_blocked_domains(blocked_domains)

Встановіть послідовність заблокованих доменів.

DefaultCookiePolicy.is_blocked(domain)

Return True if domain is on the blocklist for setting or receiving cookies.

DefaultCookiePolicy.allowed_domains()

Return None, or the sequence of allowed domains (as a tuple).

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

Set the sequence of allowed domains, or None.

DefaultCookiePolicy.is_not_allowed(domain)

Return True if domain is not on the allowlist for setting or receiving cookies.

DefaultCookiePolicy екземпляри мають наведені нижче атрибути, які всі ініціалізуються однойменними аргументами конструктора, і які всі можуть бути призначені.

DefaultCookiePolicy.rfc2109_as_netscape

If true, request that the CookieJar instance downgrade RFC 2109 cookies (that is, cookies received in a Set-Cookie header with a version cookie-attribute of 1) to Netscape cookies by setting the version attribute of the Cookie instance to 0. The default value is None, in which case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned off. Therefore, RFC 2109 cookies are downgraded by default.

Перемикачі загальної жорсткості:

DefaultCookiePolicy.strict_domain

Не дозволяйте сайтам встановлювати двокомпонентні домени з доменами верхнього рівня з кодом країни, наприклад .co.uk, .gov.uk, .co.nz.etc. Це далеко не ідеально і не гарантовано спрацює!

RFC 2965 перемикачі суворості протоколу:

DefaultCookiePolicy.strict_rfc2965_unverifiable

Дотримуйтеся правил RFC 2965 щодо транзакцій, які не підлягають перевірці (зазвичай транзакція, яка не підлягає перевірці, є транзакцією, яка є результатом перенаправлення або запиту зображення, розміщеного на іншому сайті). Якщо це невірно, файли cookie ніколи не блокуються на основі можливості перевірки

Перемикачі суворості протоколу Netscape:

DefaultCookiePolicy.strict_ns_unverifiable

Застосовуйте правила RFC 2965 до транзакцій, які неможливо перевірити, навіть до файлів cookie Netscape.

DefaultCookiePolicy.strict_ns_domain

Прапорці, які вказують на те, наскільки суворими є правила відповідності домену для файлів cookie Netscape. Допустимі значення див. нижче.

DefaultCookiePolicy.strict_ns_set_initial_dollar

Ігноруйте файли cookie в Set-Cookie: заголовки, імена яких починаються з '$'.

DefaultCookiePolicy.strict_ns_set_path

Заборонити встановлення файлів cookie, шлях яких не відповідає URI запиту.

strict_ns_domain is a collection of flags. Its value is constructed by or-ing together (for example, DomainStrictNoDots|DomainStrictNonDomain means both flags are set).

DefaultCookiePolicy.DomainStrictNoDots

When setting cookies, the „host prefix“ must not contain a dot (for example, www.foo.bar.com can’t set a cookie for .bar.com, because www.foo contains a dot).

DefaultCookiePolicy.DomainStrictNonDomain

Cookies that did not explicitly specify a domain cookie-attribute can only be returned to a domain equal to the domain that set the cookie (for example, spam.example.com won’t be returned cookies from example.com that had no domain cookie-attribute).

DefaultCookiePolicy.DomainRFC2965Match

Під час встановлення файлів cookie вимагайте повного збігу домену RFC 2965.

Наступні атрибути надано для зручності та є найкориснішими комбінаціями наведених вище позначок:

DefaultCookiePolicy.DomainLiberal

Equivalent to 0 (that is, all of the above Netscape domain strictness flags switched off).

DefaultCookiePolicy.DomainStrict

Еквівалент DomainStrictNoDots|DomainStrictNonDomain.

Приклади

The first example shows the most common usage of http.cookiejar:

import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

У цьому прикладі показано, як відкрити URL-адресу за допомогою файлів cookie Netscape, Mozilla або Lynx (припускається, що для розташування файлу cookie використовується угода Unix/Netscape):

import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

Наступний приклад ілюструє використання DefaultCookiePolicy. Увімкніть файли cookie RFC 2965, будьте суворішими щодо доменів під час встановлення та повернення файлів cookie Netscape і забороніть деяким доменам установлювати або повертати файли cookie:

import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=Policy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")