`http.cookiejar` — Обработка cookie для HTTP клиентов¶

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

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

Примечание

Различные именованные параметры, содержащиеся в заголовках Set- Cookie и Set-Cookie2 (например, domain и expires), обычно обозначаются как атрибуты. Чтобы отличить их от атрибутов Python, в документации по этому модулю вместо этого используется термин cookie-атрибут.

Модуль определяет следующее исключение:

exception http.cookiejar.LoadError¶: Экземпляры FileCookieJar вызывают это исключение при неудачной загрузке cookie из файла. LoadError является подклассом OSError.

Изменено в версии 3.3: LoadError был сделан подклассом OSError вместо IOError.

Предоставляются следующие классы:

class http.cookiejar.CookieJar(policy=None)¶

policy — это объект, реализующий интерфейс CookiePolicy.

Класс CookieJar хранит cookie HTTP. Он извлекает cookie из HTTP- запросов и возвращает их в HTTP-ответах. Экземпляры CookieJar автоматически удаляют содержащиеся cookie при необходимости. Подклассы также отвечают за хранение и получение cookie из файла или базы данных.

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

policy — это объект, реализующий интерфейс CookiePolicy. По поводу других аргументов см. документацию по соответствующим атрибутам.

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

Изменено в версии 3.8: Параметр имени файла поддерживает путеподобный объект.

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.haxx.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. Не широко используется.
http://kristol.org/cookie/errata.html: Незавершенные исправления к RFC 2965.

RFC 2964 — Использование управления состоянием HTTP

Объекты CookieJar и FileCookieJar¶

Объекты CookieJar поддерживают протокол итератора для перебора содержащихся объектов Cookie.

У CookieJar следующие методы:

CookieJar.add_cookie_header(request)¶

Добавить правильный заголовок Cookie в request.

Если политика разрешает (т. е. Атрибуты rfc2965 и hide_cookie2 экземпляра CookiePolicy CookieJar имеют значение истина и ложь соответственно), при необходимости также добавляется заголовок Cookie2.

Объект request (обычно экземпляр urllib.request.Request`3) должен поддерживать методы :meth:`get_full_url, get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() и origin_req_host атрибут по документу urllib.request.

Изменено в версии 3.3: Объекту request требуется атрибут origin_req_host. Удалена зависимость от устаревшего метода get_origin_req_host().

CookieJar.extract_cookies(response, request)¶

Извлечь cookie из HTTP response и сохранить их в CookieJar, если это разрешено политикой.

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

Объект response (обычно результат вызова urllib.request.urlopen() или аналогичного) должен поддерживать метод info(), который возвращает экземпляр email.message.Message.

Объект request (обычно экземпляр urllib.request.Request) должен поддерживать методы get_full_url(), get_host(), unverifiable() и атрибут origin_req_host, как приведено в urllib.request. Запрос используется для установки значений по умолчанию для атрибутов cookie, а также для проверки того, разрешено ли устанавливать cookie.

Изменено в версии 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.

CookieJar.set_cookie_if_ok(cookie, request)¶: Устанавливает Cookie, если политика разрешает это делать.

CookieJar.set_cookie(cookie)¶: Устанавливает Cookie, не сверяясь с политикой, нужно ли его устанавливать.

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

Удалить некоторые cookie.

Если вызывается без аргументов, очистить все cookie. Если указан один аргумент, будут удалены только cookie, принадлежащие этому domain. Если задано два аргумента, cookie, принадлежащие указанному domain и URL-адресу path, удаляются. Если задано три аргумента, cookie с указанными domain, path и name удаляется.

Вызывает KeyError, если соответствующий cookie не существует.

CookieJar.clear_session_cookies()¶

Отменить все cookie сеанса.

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

Обратите внимание, что метод save() в любом случае не будет сохранять cookie сеанса, если вы не укажете иное, передав истинный аргумент ignore_discard.

FileCookieJar реализует следующие дополнительные методы:

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

Сохранить куки в файл.

Данный базовый класс вызывает NotImplementedError. Подклассы могут оставить данный метод нереализованным.

filename — это имя файла для сохранения 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, delayload=None, policy=None)¶

FileCookieJar, который может загружать и сохранять cookie на диск в формате файла Mozilla cookies.txt (который также используется браузерами Lynx и Netscape).

Примечание

При этом теряется информация о файлах cookie RFC 2965, а также о новых или нестандартных атрибутах cookie, таких как port.

Предупреждение

Сделайте резервную копию cookie перед сохранением, если у вас есть cookie, потеря/повреждение которых было бы неудобно (есть некоторые тонкости, которые могут привести к незначительным изменениям в файле во время цикла загрузки/сохранения).

Также обратите внимание, что cookie, сохраненные во время работы Mozilla, будут уничтожены Mozilla.

class http.cookiejar.LWPCookieJar(filename, delayload=None, policy=None)¶: FileCookieJar, который может загружать и сохранять cookie на диск в формате, совместимом с форматом файлов Set-Cookie3 библиотеки libwww- perl. Это удобно, если вы хотите хранить cookie в удобочитаемом файле.

Изменено в версии 3.8: Параметр имени файла поддерживает путеподобный объект.

Объекты 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 с определенным доменом (что может включать чтение большого количества файлов). При возврате истины из domain_return_ok() и path_return_ok() вся работа остаётся на return_ok().

Если domain_return_ok() возвращает истину для домена cookie, для пути cookie вызывается path_return_ok(). В противном случае для этого домена cookie никогда не вызываются path_return_ok() и return_ok(). Если path_return_ok() возвращает истину, return_ok() вызывается с самим объектом Cookie для полной проверки. В противном случае для этого пути cookie никогда не вызывается return_ok().

Обратите внимание, что 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.

Защищены как RFC 2965, так и cookie 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)¶: Указать, находится ли domain в черном списке для установки или получения cookie.

DefaultCookiePolicy.allowed_domains()¶: Возвращает None или последовательность разрешённых доменов (в виде кортежа).

DefaultCookiePolicy.set_allowed_domains(allowed_domains)¶: Устанавливает последовательность разрешённых доменов, или None.

DefaultCookiePolicy.is_not_allowed(domain)¶: Указать, нет ли domain в белом списке для настройки или получения cookie.

Экземпляры 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 и т. д.. Это далеко не идеально и не гарантирует, что сработает.

Переключатели строгости протокола 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 — это множество флагов. Его значение создаётся путём объединения или (например, DomainStrictNoDots|DomainStrictNonDomain означает, что установлены оба флага).

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

DefaultCookiePolicy.DomainStrictNonDomain¶: Cookie, в которых явно не указан атрибут cookie domain, могут быть возвращены только в домен, равный домену, который установил 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/")

http.cookiejar — Обработка cookie для HTTP клиентов¶