http.cookiejar — Cookie handling for HTTP clients

Вихідний код: Lib/http/cookiejar.py

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

Обробляються як звичайний протокол cookie Netscape, так і протокол, визначений RFC 2965. Обробку RFC 2965 вимкнено за замовчуванням. RFC 2109 файли cookie аналізуються як файли cookie Netscape і згодом розглядаються як файли cookie Netscape або RFC 2965 відповідно до чинної «політики». Зверніть увагу, що більшість файлів cookie в Інтернеті є файлами cookie Netscape. http.cookiejar намагається слідувати фактичному протоколу файлів cookie Netscape (який суттєво відрізняється від викладеного в оригінальній специфікації Netscape), включно з врахуванням max-age і port атрибути cookie, введені з RFC 2965.

Примітка

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

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

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

Аргументи конструктора слід передавати лише як аргументи ключових слів. 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.

Дивись також

Модуль 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.

Змінено в версії 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.

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

Змінено в версії 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

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

Надається список заблокованих і білих доменів (обидва вимкнено за умовчанням). У налаштуваннях і поверненні файлів cookie беруть участь лише домени, яких немає в списку блокувань, але присутні в списку дозволених (якщо список дозволених активний). Використовуйте аргумент конструктора blocked_domains і методи blocked_domains() і set_blocked_domains() (а також відповідний аргумент і методи для allowed_domains). Якщо ви встановили білий список, ви можете вимкнути його знову, встановивши для нього значення 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()

Повернути 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.

Приклади

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