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

Объекты типа «Банка для печенья» и «FileCookieJar»¶

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

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

CookieJar.add_cookie_header(request)¶

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

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

Объект request (обычно это экземпляр 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)¶

Извлеките файлы 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() и атрибуты host, unverifiable и origin_req_host, как описано в urllib.request. Запрос используется для установки значений по умолчанию для атрибутов cookie, а также для проверки того, разрешена ли установка cookie.

Изменено в версии 3.3: для запроса объекта требуется атрибут 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, принадлежащие указанному домену и URL-адресу. Если заданы три аргумента, то файл cookie с указанными доменом, путем и именем удаляется.

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

CookieJar.clear_session_cookies()¶

Удалите все сеансовые файлы cookie.

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

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

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

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

Сохраните файлы cookie в файл.

Этот базовый класс генерирует NotImplementedError. В подклассах этот метод может не реализовываться.

имя файла - это имя файла, в который сохраняются файлы cookie. Если имя файла не указано, используется 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¶

Если значение true, то файлы cookie загружаются с диска медленно. Этот атрибут не следует присваивать. Это всего лишь подсказка, поскольку это влияет только на производительность, а не на поведение (если только файлы cookie на диске не изменяются). Объект CookieJar может игнорировать это. Ни один из классов FileCookieJar, включенных в стандартную библиотеку, не загружает файлы cookie лениво.

Подклассы FileCookieJar и взаимодействие с веб-браузерами¶

Следующие CookieJar подклассы предназначены для чтения и записи.

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

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

Примечание

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

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

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

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

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

Файл FileCookieJar, который может загружаться из файлов cookie и сохранять их на диске в формате, совместимом с форматом файла библиотеки libwww-perl Set-Cookie3. Это удобно, если вы хотите хранить файлы cookie в удобочитаемом файле.

Изменено в версии 3.8: Параметр filename поддерживает значение path-like object.

Объекты политики использования файлов cookie¶

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

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

Обратите внимание, что 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 к запросам (наличие этого заголовка указывает серверу, что мы понимаем RFC 2965 cookies).

Наиболее полезным способом определения класса CookiePolicy является создание подкласса из DefaultCookiePolicy и переопределение некоторых или всех вышеперечисленных методов. CookiePolicy сам по себе может использоваться в качестве «нулевой политики», позволяющей устанавливать и получать любые файлы cookie (это вряд ли будет полезно).

Объекты 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 - нет.

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

DefaultCookiePolicy.blocked_domains()¶

Возвращает последовательность заблокированных доменов (в виде кортежа).

DefaultCookiePolicy.set_blocked_domains(blocked_domains)¶

Установите последовательность заблокированных доменов.

DefaultCookiePolicy.is_blocked(domain)¶

Верните True, если домен находится в списке заблокированных для установки или получения файлов cookie.

DefaultCookiePolicy.allowed_domains()¶

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)¶

Задайте последовательность разрешенных доменов, или None.

DefaultCookiePolicy.is_not_allowed(domain)¶

Верните True, если домен отсутствует в списке разрешенных для установки или получения файлов cookie.

DefaultCookiePolicy экземпляры имеют следующие атрибуты, которые все инициализируются из одноименных аргументов конструктора и которым все они могут быть присвоены.

DefaultCookiePolicy.rfc2109_as_netscape¶

Если значение равно true, запросите, чтобы экземпляр CookieJar понизил RFC 2109 cookie-файлов (т.е. файлы 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, в которых явно не указан атрибут domain, могут быть возвращены только в домен, соответствующий домену, установившему файл cookie (например, spam.example.com не будут возвращены файлы cookie из example.com, у которых не было domain cookie-атрибут).

DefaultCookiePolicy.DomainRFC2965Match¶

При настройке файлов cookie требуется полное соответствие домена RFC 2965.

Следующие атрибуты предоставлены для удобства и являются наиболее полезными комбинациями вышеуказанных флагов:

DefaultCookiePolicy.DomainLiberal¶

Эквивалентно 0 (т.е. все вышеперечисленные флаги строгости домена Netscape отключены).

DefaultCookiePolicy.DomainStrict¶

Эквивалентно DomainStrictNoDots|DomainStrictNonDomain.

Объекты cookie-файлов¶

Cookie экземпляры имеют атрибуты Python, примерно соответствующие стандартным атрибутам файлов cookie, указанным в различных стандартах файлов cookie. Соответствие не является однозначным, поскольку существуют сложные правила присвоения значений по умолчанию, поскольку max-age и expires cookie-атрибуты содержат эквивалентную информацию, а также поскольку RFC 2109 cookie-файлы могут быть «понижены» на http.cookiejar файлы cookie с версии 1 по версию 0 (Netscape).

Назначение этих атрибутов не должно быть необходимым, за исключением редких случаев в методе CookiePolicy. Класс не обеспечивает внутреннюю согласованность, поэтому вы должны знать, что делаете, если делаете это.

Cookie.version¶

Целое число или None. Файлы cookie Netscape имеют version 0. RFC 2965 и RFC 2109 файлы cookie имеют version атрибут cookie, равный 1. Однако обратите внимание, что http.cookiejar может «понизить» статус файлов cookie RFC 2109 до файлов cookie Netscape, и в этом случае version равно 0.

Cookie.name¶

Имя файла cookie (строка).

Cookie.value¶

Значение файла cookie (строка) или None.

Cookie.port¶

Строка, представляющая порт или набор портов (например, „80“, или „80,8080“), или None.

Cookie.domain¶

Домен файла cookie (строка).

Cookie.path¶

Путь к файлу cookie (строка, например. '/acme/rocket_launchers').

Cookie.secure¶

True если файл cookie должен быть возвращен только по защищенному соединению.

Cookie.expires¶

Целочисленная дата истечения срока действия в секундах, начиная с epoch, или 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-версии в этом заголовке было равно 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.has_nonstandard_attr(name)¶

Возвращает True, если файл cookie имеет именованный атрибут cookie.

Cookie.get_nonstandard_attr(name, default=None)¶

Если файл cookie имеет именованный атрибут cookie, верните его значение. В противном случае верните значение по умолчанию.

Cookie.set_nonstandard_attr(name, value)¶

Установите значение именованного атрибута cookie.

Класс Cookie также определяет следующий метод:

Cookie.is_expired(now=None)¶

True если срок действия файла cookie истек по истечении времени, запрошенного сервером, он должен истечь. Если указано значение сейчас (в секундах с момента начала периода), укажите, истек ли срок действия файла 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. Включите RFC 2965 cookies, будьте более строги к доменам при установке и возврате файлов 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/")