http.cookiejar --- Cookie handling for HTTP clients

Kod źródłowy: Lib/http/cookiejar.py

Модуль http.cookiejar визначає класи для автоматичної обробки файлів cookie HTTP. Це корисно для доступу до веб-сайтів, яким потрібні невеликі фрагменти даних — cookies — які встановлюються на клієнтській машині за допомогою відповіді HTTP від веб-сервера, а потім повертаються на сервер у наступних запитах HTTP.

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.

Catatan

Різноманітні іменовані параметри, які містяться в заголовках Set-Cookie і Set-Cookie2 (наприклад, domain і expires), зазвичай називаються attributes . Щоб відрізнити їх від атрибутів Python, у документації для цього модуля замість цього використовується термін cookie-attribute.

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

exception http.cookiejar.LoadError

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

Berubah pada versi 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.

Berubah pada versi 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'))

Аргументи конструктора слід передавати лише як аргументи ключових слів. blocked_domains – це послідовність доменних імен, з яких ми ніколи не приймаємо файли cookie та не повертаємо файли cookie. allowed_domains якщо не None, це послідовність єдиних доменів, для яких ми приймаємо та повертаємо файли cookie. secure_protocols — це послідовність протоколів, до яких можна додати захищені файли cookie. За умовчанням https і wss (безпечний веб-сокет) вважаються безпечними протоколами. Усі інші аргументи дивіться в документації для об’єктів CookiePolicy і DefaultCookiePolicy.

DefaultCookiePolicy реалізує стандартні правила прийняття/відхилення файлів cookie Netscape і RFC 2965. За замовчуванням файли cookie RFC 2109 (тобто файли cookie, отримані в заголовку Set-Cookie з атрибутом cookie версії 1) обробляються відповідно до правил RFC 2965. Проте, якщо обробку RFC 2965 вимкнено або rfc2109_as_netscape має значення True, файли cookie RFC 2109 "понижуються" екземпляром CookieJar до файлів cookie Netscape, встановлюючи version екземпляра Cookie дорівнює 0. DefaultCookiePolicy також надає деякі параметри, щоб дозволити деяке тонке налаштування політики.

class http.cookiejar.Cookie

Цей клас представляє файли cookie Netscape, RFC 2109 і RFC 2965. Не очікується, що користувачі http.cookiejar створюватимуть власні екземпляри Cookie. Замість цього, якщо необхідно, викличте make_cookies() на екземплярі CookieJar.

Lihat juga

Модуль urllib.request

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

Модуль http.cookies

Класи cookie HTTP, які в основному корисні для коду на стороні сервера. Модулі http.cookiejar і http.cookies не залежать один від одного.

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

Специфікація оригінального протоколу cookie Netscape. Хоча це все ще домінуючий протокол, "протокол файлів cookie Netscape", реалізований усіма основними браузерами (і http.cookiejar), лише побіжно схожий на той, який накреслено в 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 і FileCookieJar

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

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

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

Якщо політика дозволяє (тобто атрибути rfc2965 і hide_cookie2 екземпляра CookieJar CookiePolicy мають значення true і false відповідно), Заголовок Cookie2 також додається, коли це необхідно.

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.

Berubah pada versi 3.3: Об’єкту request потрібен атрибут origin_req_host. Залежність від застарілого методу get_origin_req_host() видалено.

CookieJar.extract_cookies(response, request)

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

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

Об’єкт response (зазвичай це результат виклику urllib.request.urlopen() або подібного) має підтримувати метод info(), який повертає email.message.Message. екземпляр.

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.

Berubah pada versi 3.3: Об’єкту request потрібен атрибут origin_req_host. Залежність від застарілого методу get_origin_req_host() видалено.

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 сесії.

Відкидає всі файли cookie, які мають справжній атрибут discard (зазвичай тому, що вони не мали атрибута cookie max-age або expires, або явного атрибута discard cookie-attribute ). Для інтерактивних браузерів кінець сеансу зазвичай відповідає закриттю вікна браузера.

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

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

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

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

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

ім’я файлу — це ім’я файлу, у якому зберігатимуться файли cookie. Якщо filename не вказано, self.filename використовується (яке за умовчанням є значенням, переданим конструктору, якщо такий є); якщо self.filename має значення None, виникає ValueError.

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, наприклад, якщо файл не існує.

Berubah pada versi 3.3: IOError sebelumnya ditimbulkan, sekarang merupakan alias dari 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).

Catatan

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

Peringatan

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

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

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

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

Berubah pada versi 3.8: Параметр імені файлу підтримує path-like object.

Об’єкти CookiePolicy

Об’єкти, що реалізують інтерфейс 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

Реалізує стандартні правила прийому та повернення файлів 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.

Domains in block or allow lists that do not start with a dot must equal the cookie domain to be matched. For example, "example.com" matches a blocklist entry of "example.com", but "www.example.com" does not. Domains that do start with a dot are matched by more specific domains too. For example, both "www.example.com" and "www.coyote.example.com" match ".example.com" (but "example.com" itself does not). IP addresses are an exception, and must match exactly. For example, if blocked_domains contains "192.168.1.2" and ".168.1.2", 192.168.1.2 is blocked, but 193.168.1.2 is not.

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()

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

Встановіть послідовність дозволених доменів або 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

Якщо істина, вимагайте, щоб екземпляр CookieJar повернув файли cookie RFC 2109 (тобто файли cookie, отримані в заголовку Set-Cookie з атрибутом cookie-версії 1) до файлів cookie Netscape встановлення атрибута версії екземпляра Cookie на 0. Значенням за замовчуванням є None, у цьому випадку файли cookie RFC 2109 повертаються до попередньої версії тоді і тільки якщо обробку RFC 2965 вимкнено. Тому за замовчуванням файли cookie RFC 2109 знижуються.

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

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

Під час встановлення файлів cookie "префікс хосту" не повинен містити крапку (наприклад, www.foo.bar.com не може встановити файл cookie для .bar.com, оскільки www.foo містить крапку).

DefaultCookiePolicy.DomainStrictNonDomain

Файли cookie, у яких явно не вказано атрибут cookie домену, можна повернути лише в домен, який відповідає домену, який встановив файл cookie (наприклад, spam.example.com не повертатиме файли cookie з example.com, який не мав атрибута cookie domain).

DefaultCookiePolicy.DomainRFC2965Match

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

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

DefaultCookiePolicy.DomainLiberal

Еквівалент 0 (тобто всі наведені вище позначки суворості домену Netscape вимкнено).

DefaultCookiePolicy.DomainStrict

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

Contoh-contoh

Перший приклад показує найпоширеніше використання 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/")