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-атрибут.
Модуль определяет следующее исключение:
Экземпляры
FileCookieJar
вызывают это исключение при неудачной загрузке cookie из файла.LoadError
является подклассомOSError
.
Предоставляются следующие классы:
policy — это объект, реализующий интерфейс
CookiePolicy
.Класс
CookieJar
хранит cookie HTTP. Он извлекает cookie из HTTP- запросов и возвращает их в HTTP-ответах. ЭкземплярыCookieJar
автоматически удаляют содержащиеся cookie при необходимости. Подклассы также отвечают за хранение и получение cookie из файла или базы данных.
policy — это объект, реализующий интерфейс
CookiePolicy
. По поводу других аргументов см. документацию по соответствующим атрибутам.CookieJar
, который может загружать cookie и, возможно, сохранять cookie в файле на диске. Cookie НЕ загружаются из указанного файла до тех пор, пока не будет вызван методload()
илиrevert()
. Подклассы этого класса описаны в разделе Подклассы FileCookieJar и взаимодействие с веб-браузерами.Изменено в версии 3.8: Параметр имени файла поддерживает путеподобный объект.
Данный класс отвечает за принятие решения о том, следует ли принимать каждый cookie или возвращать его на сервер.
Аргументы конструктора должны передаваться только как ключевые аргументы. 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
также предоставляет некоторые параметры, позволяющие добиться некоторого тонкой настройки политики.
Данный класс представляет 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
следующие методы:
Добавить правильный заголовок 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()
.
Извлечь 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()
.
Задаёт экземпляр
CookiePolicy
, который будет использоваться.
Возвращает последовательность объектов
Cookie
, извлеченных из объекта response.См. документацию для
extract_cookies()
, чтобы узнать об интерфейсах, необходимых для аргументов response и request.
Устанавливает
Cookie
, если политика разрешает это делать.
Устанавливает
Cookie
, не сверяясь с политикой, нужно ли его устанавливать.
Удалить некоторые cookie.
Если вызывается без аргументов, очистить все cookie. Если указан один аргумент, будут удалены только cookie, принадлежащие этому domain. Если задано два аргумента, cookie, принадлежащие указанному domain и URL-адресу path, удаляются. Если задано три аргумента, cookie с указанными domain, path и name удаляется.
Вызывает
KeyError
, если соответствующий cookie не существует.
Отменить все cookie сеанса.
Отбрасывает все содержащиеся cookie, которые имеют истинный атрибут
discard
(обычно потому, что у них не было атрибута cookiemax- age
илиexpires
или явного атрибута cookiediscard
). Для интерактивных браузеров окончание сеанса обычно соответствует закрытию окна браузера.Обратите внимание, что метод
save()
в любом случае не будет сохранять cookie сеанса, если вы не укажете иное, передав истинный аргумент ignore_discard.
FileCookieJar
реализует следующие дополнительные методы:
Сохранить куки в файл.
Данный базовый класс вызывает
NotImplementedError
. Подклассы могут оставить данный метод нереализованным.filename — это имя файла для сохранения cookie. Если filename не указан, используется
self.filename
(по умолчанию значение, переданное конструктору, если таковое имеется); еслиself.filename
— этоNone
, повышаетсяValueError
.ignore_discard: сохранить даже установленные cookie для удаления. ignore_expires: сохранять даже cookie, срок действия которых истек
Файл перезаписывается, если он уже существует, таким образом удаляя все cookie, которые он содержит. Сохраненные cookie можно восстановить позже с помощью методов
load()
илиrevert()
.
Загрузить cookie из файла.
Старые cookie сохраняются, если они не перезаписываются новыми загруженными.
Аргументы такие же, как для
save()
.Именованный файл должен иметь формат, понятный классу, в противном случае будет вызвано
LoadError
. Также может возникнутьOSError
, например, если файл не существует.
Удалить все cookie и повторно загрузить cookie из сохраненного файла.
revert()
может вызывать те же исключения, что иload()
. В случае сбоя состояние объекта не изменится.
Экземпляры FileCookieJar
имеют следующие общедоступные атрибуты:
Имя файла по умолчанию, в котором хранятся cookie. Данный атрибут может быть присвоен.
Если истина, лениво загружать cookie с диска. Данный атрибут не должен присваиваться. Это только подсказка, т. к. это влияет только на производительность, а не на поведение (если cookie на диске не меняются). Объект
CookieJar
может игнорировать его. Ни один из классовFileCookieJar
, включенных в стандартную библиотеку, не загружает cookie лениво.
Подклассы FileCookieJar и взаимодействие с веб-браузерами¶
Следующие подклассы CookieJar
предназначены для чтения и записи.
FileCookieJar
, который может загружать и сохранять cookie на диск в формате файла Mozillacookies.txt
(который также используется браузерами Lynx и Netscape).Примечание
При этом теряется информация о файлах cookie RFC 2965, а также о новых или нестандартных атрибутах cookie, таких как
port
.Предупреждение
Сделайте резервную копию cookie перед сохранением, если у вас есть cookie, потеря/повреждение которых было бы неудобно (есть некоторые тонкости, которые могут привести к незначительным изменениям в файле во время цикла загрузки/сохранения).
Также обратите внимание, что cookie, сохраненные во время работы Mozilla, будут уничтожены Mozilla.
FileCookieJar
, который может загружать и сохранять cookie на диск в формате, совместимом с форматом файловSet-Cookie3
библиотеки libwww- perl. Это удобно, если вы хотите хранить cookie в удобочитаемом файле.Изменено в версии 3.8: Параметр имени файла поддерживает путеподобный объект.
Объекты CookiePolicy¶
У объектов, реализующих интерфейс CookiePolicy
, есть следующие методы:
Возвращает логическое значение, указывающее, следует ли принимать cookie от сервера.
cookie — это экземпляр
Cookie
. request — это объект, реализующий интерфейс, определённый в документации дляCookieJar.extract_cookies()
.
Возвращает логическое значение, указывающее, следует ли возвращать cookie на сервер.
cookie — это экземпляр
Cookie
. request — это объект, реализующий интерфейс, определённый в документации дляCookieJar.add_cookie_header()
.
Возвращает
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()
.
Возвращает
False
, если cookie не должны возвращаться при заданном пути для cookie.См. документацию для
domain_return_ok()
.
В дополнение к реализации вышеуказанных методов реализации интерфейса
CookiePolicy
должны также предоставлять следующие атрибуты,
указывающие, какие протоколы следует использовать и как. Все данные атрибуты
могут быть присвоены.
Реализация протокола Netscape.
Реализация протокола RFC 2965.
Не добавляйте в запросы заголовок 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
реализует следующие дополнительные методы:
Возвращает последовательность заблокированных доменов (в виде кортежа).
Устанавливает последовательность блокируемых доменов.
Указать, находится ли domain в черном списке для установки или получения cookie.
Возвращает
None
или последовательность разрешённых доменов (в виде кортежа).
Устанавливает последовательность разрешённых доменов, или
None
.
Указать, нет ли domain в белом списке для настройки или получения cookie.
Экземпляры DefaultCookiePolicy
имеют следующие атрибуты, которые
инициализируются одноименными аргументами конструктора и которым все могут быть
присвоены.
Если истина, запросить, чтобы экземпляр
CookieJar
понизил версию cookie RFC 2109 (т. е. Cookie, полученные в заголовке Set-Cookie с атрибутом cookie версии 1) до cookie Netscape, установив для атрибута версии экземпляраCookie
значение 0. Значение по умолчанию —None
, в этом случае cookie RFC 2109 будут понижены, если и только если отключена обработка RFC 2965. Таким образом, cookie RFC 2109 по умолчанию понижены.
Переключатели общей строгости:
Не разрешать сайтам устанавливать двухкомпонентные домены с доменами верхнего уровня с кодом страны, такими как
.co.uk
,.gov.uk
,.co.nz
и т. д.. Это далеко не идеально и не гарантирует, что сработает.
Переключатели строгости протокола RFC 2965:
Следуйте правилам RFC 2965 в отношении непроверяемых транзакций (обычно непроверяемая транзакция является результатом перенаправления или запроса изображения, размещенного на другом сайте). Если — ложь, cookie никогда не блокируются на основании проверяемости.
Переключатели строгости протокола Netscape:
Применяйте правила RFC 2965 к непроверяемым транзакциям даже к файлам cookie Netscape.
Флаги, указывающие, насколько строгими должны быть правила сопоставления доменов для cookie Netscape. См. ниже допустимые значения.
Игнорировать cookie в Set-Cookie: заголовки, имена которых начинаются с
'$'
.
Не разрешать установку cookie, путь которых не соответствует URI запроса.
strict_ns_domain
— это множество флагов. Его значение создаётся путём
объединения или (например, DomainStrictNoDots|DomainStrictNonDomain
означает, что установлены оба флага).
При настройке cookie «префикс хоста» не должен содержать точки (например,
www.foo.bar.com
не может установить cookie для.bar.com
, потому чтоwww.foo
содержит точку).
Cookie, в которых явно не указан атрибут cookie
domain
, могут быть возвращены только в домен, равный домену, который установил cookie (например,spam.example.com
не будет возвращён cookie изexample.com
, у которого нет атрибута cookiedomain
).
При настройке cookie требуется полное соответствие домена RFC 2965.
Следующие атрибуты предоставлены для удобства и представляют собой наиболее полезные комбинации вышеуказанных флагов:
Эквивалентно 0 (т. е. все вышеперечисленные флаги строгости домена Netscape выключены).
Эквивалентен
DomainStrictNoDots|DomainStrictNonDomain
.
Объекты Cookie¶
У экземпляров Cookie
есть атрибуты Python, примерно соответствующие
стандартным атрибутам cookie, указанным в различных стандартах cookie.
Соответствие не является взаимно однозначным, потому что существуют сложные
правила для присвоения значений по умолчанию, потому что атрибуты cookie max-
age
и expires
содержат эквивалентную информацию, и поскольку cookie
RFC 2109 могут быть понижены с версии 1 до версии 0 (Netscape) куки.
Назначение данных атрибутов не обязательно, кроме редких случаев в методе
CookiePolicy
. Класс не обеспечивает внутренней согласованности,
поэтому вы должны знать, что вы делаете.
Целое число или
None
. Cookie Netscape имеютversion
0. Cookie RFC 2965 и RFC 2109 имеют атрибут cookieversion
, равный 1. Однако обратите внимание, чтоhttp.cookiejar
может «понизить» cookie RFC 2109 до cookie Netscape, и в этом случаеversion
равен 0.
Имя файла cookie (строка).
Значение cookie (строка) или
None
.
Строка, представляющая порт или множество портов (например, «80» или «80, 8080») или
None
.
Путь к файлу cookie (строка, например,
'/acme/rocket_launchers'
).
True
, если cookie следует возвращать только через безопасное соединение.
Целочисленный срок годности в секундах с начала эпохи или
None
. См. также методis_expired()
.
True
, если это cookie сеанса.
Строковый комментарий сервера, объясняющий функцию этого файла cookie, или
None
.
URL-адрес, указывающий на комментарий сервера, объясняющий функцию этого файла cookie, или
None
.
True
, если данный куки-файл был получен как куки-файл RFC 2109 (т. е. cookie-файл прибыл в заголовке Set-Cookie, и значение атрибута «Версия куки-файла» в этом заголовке было равна 1). Данный атрибут предоставляется, потому чтоhttp.cookiejar
может «понизить» cookie RFC 2109 до cookie Netscape, и в этом случаеversion
равен 0.
True
, если порт или множество портов были явно указаны сервером (в заголовке Set-Cookie/Set-Cookie2).
True
, если домен был явно указан сервером.
True
, если домен, явно указанный сервером, начинается с точки ('.'
).
Cookie могут иметь дополнительные нестандартные атрибуты cookie. К ним можно получить доступ, используя следующие методы:
Возвращает
True
, если у cookie есть именованный атрибут cookie.
Если у cookie есть именованный атрибут cookie, возвращает его значение. В противном случае возвращает default.
Устанавливает значение названного атрибута cookie.
Класс Cookie
также определяет следующий метод:
True
, если для файла cookie прошло время, в которое запросил сервер, срок его действия должен истечь. Если задано now (в секундах с начала эпохи), возвращает, истек ли срок действия cookie в указанное время.
Примеры¶
В первом примере показано наиболее частое использование 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/")