Модуль http.cookiejar определяет классы для автоматической обработки файлов cookie HTTP. Он полезен для доступа к веб-сайтам, которые требуют установки небольших фрагментов данных — файлов cookie — на клиентском компьютере в ответ 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) традиционно называются атрибутами. Для того, чтобы отличить их от атрибутов Python, в документации этого модуля используется термин атрибут файла cookie.
Модуль определяет следующую исключительную ситуацию:
exception http.cookiejar.LoadError
Экземпляры FileCookieJar генерируют это исключение при ошибке загрузки файлов cookie из файла. LoadError является подклассом OSError.
Изменено в версии 3.3: LoadError ранее был подтипом IOError, который сейчас является псевдонимом для OSError.
Класс CookieJar хранит HTTP файлы cookie. Он извлекает файлы 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 и взаимодействие с веб-браузерами.
Не следует инициализировать его напрямую — используйте его подклассы вместо этого.
Аргументы конструктора должны передаваться только в качестве именованных аргументов. blocked_domains — последовательность доменных имён, из которых мы никогда не принимаем и не возвращаем файлы 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, экземпляр CookieJar понижает файлы cookie RFC 2109 до файлов cookie Netscape, установив атрибут version экземпляра Cookie в 0. DefaultCookiePolicy также предоставляет некоторые параметры для настройки политики.
class http.cookiejar.Cookie
Этот класс представляет файлы cookie Netscape, RFC 2109 и RFC 2965. От пользователей http.cookiejar не ожидается создание собственных экземпляров Cookie. Вместо этого, при необходимости, вызывается make_cookies() для экземпляра CookieJar.
Спецификация исходного протокола cookie Netscape. Хотя это по-прежнему доминирующий протокол, «протокол cookie Netscape», реализованный всеми основными браузерами (и http.cookiejar), имеет лишь поверхностное сходство с тем, который набросан в cookie_spec.html.
Если политика разрешает (то есть, атрибуты rfc2965 и hide_cookie2 экземпляра CookieJar’s CookiePolicy истинны и ложны соответственно), заголовок Cookie2 также добавляется при необходимости.
Объект запрос (обычно экземпляр urllib.request.Request) должен поддерживать методы get_full_url(), has_header(), get_header(), header_items(), add_unredirected_header() и атрибуты host, type, unverifiable и origin_req_host, как описано в urllib.request.
Изменено в версии 3.3: Объект запрос нуждается в атрибуте origin_req_host. Зависимость от устаревшего метода get_origin_req_host() была удалена.
CookieJar.extract_cookies(response, request)
Извлечь куки из HTTP-ответа и сохранить их в CookieJar, если это разрешено политикой.
CookieJar будет искать разрешенные заголовки Set-Cookie и Set-Cookie2 в аргументе ответ и сохранять куки соответствующим образом (подлежит одобрению методом CookiePolicy.set_ok()).
Объект запрос (обычно экземпляр urllib.request.Request) должен поддерживать метод get_full_url() и атрибуты host, unverifiable и origin_req_host, как описано в urllib.request. Запрос используется для установки значений по умолчанию для атрибутов куки, а также для проверки разрешения установки куки.
Изменено в версии 3.3: Объект запрос нуждается в атрибуте origin_req_host. Зависимость от устаревшего метода get_origin_req_host() была удалена.
CookieJar.set_policy(policy)
Установить экземпляр CookiePolicy для использования.
CookieJar.make_cookies(response, request)
Возвращает последовательность объектов Cookie, извлеченных из объекта ответ.
См. документацию для extract_cookies() для интерфейсов, требуемых для аргументов ответ и запрос.
CookieJar.set_cookie_if_ok(cookie, request)
Установить Cookie, если политика разрешает это сделать.
CookieJar.set_cookie(cookie)
Установить Cookie без проверки с политикой, чтобы увидеть, следует ли ее устанавливать.
CookieJar.clear([domain[, path[, name]]])
Очистить некоторые куки.
Если вызывается без аргументов, очистить все куки. Если задан один аргумент, удаляются только куки, относящиеся к этому домену. Если заданы два аргумента, удаляются куки, относящиеся к указанному домену и пути URL. Если заданы три аргумента, удаляется куки с указанным доменом, путем и именем.
Возбуждает KeyError, если соответствующий куки не существует.
CookieJar.clear_session_cookies()
Отбросить все куки сеанса.
Отбрасывает все содержащиеся куки, которые имеют атрибут discard (обычно потому, что у них отсутствовал атрибут куки max-age или expires, или был явный атрибут куки discard). Для интерактивных браузеров окончание сеанса обычно соответствует закрытию окна браузера.
Обратите внимание, что метод save() не сохранит куки сеанса в любом случае, если вы не попросите об этом, передав аргумент ignore_discard со значением true.
FileCookieJar реализует следующие дополнительные методы:
Этот базовый класс возбуждает NotImplementedError. Подклассы могут оставить этот метод нереализованным.
filename — имя файла, в котором следует сохранить куки. Если filename не указан, используется self.filename (по умолчанию — значение, переданное в конструктор, если таковое имеется); если self.filename равен None, возбуждается ValueError.
ignore_discard: сохранить даже куки, установленные для удаления. ignore_expires: сохранить даже куки, которые истекли
Файл перезаписывается, если он уже существует, тем самым удаляя все содержащиеся в нем куки. Сохраненные куки можно восстановить позже с помощью методов load() или revert().
Названный файл должен быть в формате, понятном классу, иначе будет возбуждено LoadError. Также может быть возбуждено OSError, например, если файла не существует.
Изменено в версии 3.3: IOError раньше возбуждалась, теперь она является алиасом для OSError.
Очистить все куки и перезагрузить куки из сохраненного файла.
revert() может возбудить те же исключения, что и load(). При возникновении ошибки состояние объекта не изменится.
FileCookieJar экземпляры имеют следующие публичные атрибуты:
FileCookieJar.filename
Имя файла по умолчанию, в котором хранятся куки. Этот атрибут может быть присвоен.
END_OF_DOCUMENT_MARKER
FileCookieJar.delayload
Если значение истинно, куки загружаются лениво из диска. Это свойство не должно быть изменено. Это лишь подсказка, так как это влияет только на производительность, а не на поведение (если только куки на диске не изменяются). Объект CookieJar может его игнорировать. Ни один из классов FileCookieJar в стандартной библиотеке не загружает куки лениво.
Подклассы FileCookieJar и взаимодействие с веб-браузерами
Для чтения и записи предоставляются следующие подклассы CookieJar.
class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)
Класс FileCookieJar, который может загружать и сохранять куки на диск в формате файлов Mozilla cookies.txt (который также используется браузерами curl, Lynx и Netscape).
Примечание
При этом теряется информация о куках RFC 2965, а также о более новых или нестандартных атрибутах куки, таких как port.
Предупреждение
Перед сохранением сделайте резервную копию куков, если у вас есть куки, потеря/повреждение которых будет неудобно (есть некоторые тонкости, которые могут привести к небольшим изменениям в файле при переходе «загрузка/сохранение»).
Также обратите внимание, что куки, сохранённые во время работы Mozilla, будут перезаписаны Mozilla.
class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)
Класс FileCookieJar, который может загружать и сохранять куки на диск в формате, совместимом с Set-Cookie3 формате файлов библиотеки libwww-perl. Это удобно, если вы хотите хранить куки в читаемом файле.
Изменено в версии 3.8: Параметр filename поддерживает объект пути.
Объекты CookiePolicy
Объекты, реализующие интерфейс CookiePolicy, имеют следующие методы:
CookiePolicy.set_ok(cookie, request)
Возвращает булево значение, указывающее, следует ли принимать куки от сервера.
Возвращает False, если куки не должны быть возвращены, учитывая домен куки.
Этот метод является оптимизацией. Он устраняет необходимость проверки каждой куки с определённым доменом (что может потребовать чтения многих файлов). Возвращение значения True из domain_return_ok() и path_return_ok() оставляет всю работу методу 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, если куки не должны быть возвращены, учитывая путь куки.
В дополнение к реализации вышеуказанных методов реализации интерфейса CookiePolicy также должны предоставляться следующие атрибуты, указывающие, какие протоколы следует использовать и как. Все эти атрибуты можно присваивать.
Не добавлять заголовок Cookie2 в запросы (наличие этого заголовка указывает серверу, что мы понимаем куки RFC 2965).
Наиболее полезный способ определения класса CookiePolicy — это наследование от DefaultCookiePolicy и переопределение некоторых или всех методов выше. CookiePolicy сам по себе может использоваться в качестве «нулевой политики», чтобы разрешить установку и получение всех куков (это вряд ли будет полезно).
Объекты DefaultCookiePolicy
Реализует стандартные правила приема и возврата файлов cookie.
Обрабатываются как файлы 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 нет.
Устанавливает последовательность разрешенных доменов или None.
DefaultCookiePolicy.is_not_allowed(domain)
Возвращает True, если domain отсутствует в списке разрешенных доменов для установки или получения файлов cookie.
DefaultCookiePolicy экземпляры имеют следующие атрибуты, которые все инициализируются из аргументов конструктора с тем же именем и к которым можно присваивать значения.
DefaultCookiePolicy.rfc2109_as_netscape
Если True, запрос о том, чтобы экземпляр 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 для неподтверждённых транзакций (обычно неподтверждённая транзакция — это та, которая получена в результате перенаправления или запроса изображения, размещённого на другом сайте). Если это значение ложно, файлы 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 отключены).
Cookie имеют атрибуты Python, примерно соответствующие стандартным атрибутам файлов cookie, указанным в различных стандартах файлов cookie. Соответствие не является взаимно однозначным, потому что существуют сложные правила для присвоения значений по умолчанию, поскольку атрибуты файлов cookie max-age и expires содержат эквивалентную информацию, и потому что файлы cookie RFC 2109 могут быть «снижены» http.cookiejar с версии 1 до версии 0 (файлы cookie Netscape).
Присвоение этих атрибутов не должно быть необходимым за исключением редких случаев в методе CookiePolicy. Класс не проверяет внутреннюю согласованность, поэтому вы должны понимать, что делаете, если это делаете.
Cookie.version
Целое число или None. Файлы cookie Netscape имеют version 0. RFC 2965 и RFC 2109 файлы cookie имеют атрибут файла cookie version равный 1. Однако обратите внимание, что http.cookiejar может «снизить» файлы cookie RFC 2109 до файлов cookie Netscape, в этом случае version равно 0.
Строка, представляющая порт или набор портов (например, «80» или «80,8080»), или None.
Cookie.domain
Домен файла cookie (строка).
Cookie.path
Путь файла cookie (строка, например, '/acme/rocket_launchers').
Cookie.secure
True если файл cookie должен возвращаться только по защищенному соединению.
Cookie.expires
Дата истечения срока действия в секундах с начала эпохи, или None. Смотрите также метод is_expired().
Cookie.discard
True если это файл cookie сессии.
Cookie.comment
Строка комментария от сервера, объясняющая функцию этого файла cookie, или None.
Cookie.comment_url
URL, который ссылается на комментарий от сервера, объясняющий функцию этого файла cookie, или None.
Cookie.rfc2109
True если этот файл cookie был получен как файл cookie RFC 2109 (то есть файл cookie пришел в заголовке Set-Cookie, и значение атрибута файла cookie Version в этом заголовке было 1). Этот атрибут предоставляется, потому что http.cookiejar может «снизить» файлы cookie RFC 2109 до файлов cookie Netscape, в этом случае version равно 0.
Cookie.port_specified
True если порт или набор портов были явно указаны сервером (в заголовке Set-Cookie / Set-Cookie2).
Cookie.domain_specified
True если домен был явно указан сервером.
Cookie.domain_initial_dot
True если домен, явно указанный сервером, начинался с точки ('.').
Файлы cookie могут иметь дополнительные нестандартные атрибуты файлов cookie. К ним можно получить доступ с помощью следующих методов:
Cookie.has_nonstandard_attr(name)
Возвращает True если файл cookie содержит указанный атрибут файла cookie.
Cookie.get_nonstandard_attr(name, default=None)
Если файл cookie имеет указанный атрибут файла cookie, возвращает его значение. В противном случае возвращает default.
Cookie.set_nonstandard_attr(name, value)
Устанавливает значение указанного атрибута файла 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 (предполагается соглашение Unix/Netscape для расположения файла cookie):
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/")
