Модуль http.cookiejar определяет классы для автоматической обработки файлов cookie HTTP. Он полезен для доступа к веб-сайтам, которые требуют установки небольших фрагментов данных — куки — на клиентском компьютере в ответ 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 автоматически истекают, когда это необходимо.
class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)
policy — объект, реализующий интерфейс CookiePolicy. Для других аргументов см. документацию по соответствующим атрибутам.
Аргументы конструктора следует передавать только в виде ключевых аргументов. blocked_domains — последовательность имен доменов, от которых мы никогда не принимаем и не возвращаем файлы cookie. allowed_domains, если не None, это последовательность единственных доменов, для которых мы принимаем и возвращаем файлы cookie. secure_protocols — последовательность протоколов, для которых можно добавлять безопасные файлы cookie. По умолчанию https и wss (безопасные веб-сокеты) считаются безопасными протоколами. Для всех остальных аргументов см. документацию по CookiePolicy и DefaultCookiePolicy объектам.
DefaultCookiePolicy реализует стандартные правила принятия/отклонения для файлов cookie Netscape и RFC 2965. По умолчанию RFC 2109 файлы cookie (т. е. файлы cookie, полученные в заголовке Set-Cookie с атрибутом версии файла cookie 1) обрабатываются в соответствии с правилами RFC 2965. Однако если обработка RFC 2965 отключена или rfc2109_as_netscapeTrue, файлы 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.
Спецификация исходного протокола куки Netscape. Хотя это по-прежнему доминирующий протокол, «протокол куки Netscape», реализованный всеми основными браузерами (и http.cookiejar) лишь отдаленно напоминает описанный в cookie_spec.html.
Если политика разрешает (т.е. атрибуты rfc2965 и hide_cookie2 экземпляра CookieJar’s CookiePolicy соответственно равны true и false), то заголовок 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 true (обычно потому, что у них отсутствовал либо атрибут куки max-age, либо expires, или явно задавался атрибут куки discard). Для интерактивных браузеров окончание сессии обычно соответствует закрытию окна браузера.
Обратите внимание, что метод save() не будет сохранять куки сессии, если вы не попросите иначе, передав значение true для аргумента ignore_discard.
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
Имя файла по умолчанию, в котором хранятся куки. Этот атрибут можно изменить.
FileCookieJar.delayload
Если значение true, куки загружаются лениво с диска. К этому атрибуту не следует обращаться. Это лишь подсказка, так как это влияет только на производительность, а не на поведение (если куки на диске изменяются). Объект 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. Это удобно, если вы хотите сохранить куки в удобочитаемом файле.
Возвращает 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 для недостоверных транзакций (обычно недостоверная транзакция — это транзакция, полученная в результате перенаправления или запроса изображения, размещенного на другом сайте). Если это false, файлы 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.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/")
