Модуль http.cookiejar определяет классы для автоматической обработки файлов cookie HTTP. Он полезен для доступа к веб-сайтам, которые требуют установки небольших фрагментов данных — файлов cookie — на клиентском компьютере в ответ 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), включая учет 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 был преобразован в подкласс OSError, а не IOError.
Класс CookieJar хранит HTTP-файлы cookie. Он извлекает файлы cookie из HTTP-запросов и возвращает их в HTTP-ответах. Экземпляры CookieJar автоматически удаляют содержащиеся файлы cookie при необходимости. Подклассы также отвечают за хранение и извлечение файлов cookie из файла или базы данных.
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. По умолчанию файлы 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.
Спецификация исходного протокола куки 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 (обычно потому, что у них был либо отсутствовал атрибут куки 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
Имя файла по умолчанию, в котором хранятся куки. Этот атрибут можно изменять.
FileCookieJar.delayload
Если true, куки загружаются лениво из диска. Этот атрибут изменять нельзя. Это лишь подсказка, так как это влияет только на производительность, а не на поведение (если куки на диске изменяются). Объект CookieJar может его игнорировать. Ни один из классов FileCookieJar, включённых в стандартную библиотеку, не загружает куки лениво.
END_OF_DOCUMENT_MARKER
Подклассы 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, который может загружать и сохранять куки на диск в формате, совместимом с форматом файлов библиотеки libwww-perl Set-Cookie3. Это удобно, если вы хотите сохранить куки в удобочитаемом файле.
Возвращает 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 может использоваться в качестве «нулевой политики», чтобы разрешить установку и получение любых куки (это вряд ли будет полезно).
END_OF_DOCUMENT_MARKER
Объекты 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)
Возвращает значение, указывающее, находится ли 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 для неподтвержденных транзакций (обычно неподтвержденная транзакция — это транзакция, полученная в результате перенаправления или запроса изображения, размещенного на другом сайте). Если это ложь, файлы 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-домена, могут быть возвращены только в домен, равный домену, который установил файл cookie (например, spam.example.com не получит файлы cookie от example.com без атрибута domain cookie).
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. Файлы cookie RFC 2965 и RFC 2109 имеют атрибут файла 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
Ссылка на комментарий от сервера, объясняющий функцию этого файла cookie, или None.
Cookie.rfc2109
True если этот файл cookie был получен как файл cookie RFC 2109 (т. е. файл cookie поступил в заголовке Set-Cookie, а значение атрибута версии файла cookie в этом заголовке было равно 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/")
