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

Объекты CookieJar и 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: Объекту request необходим атрибут origin_req_host. Устранена зависимость от устаревшего метода get_origin_req_host().

CookieJar.extract_cookies(response, request)¶

Извлечение cookies из HTTP ответа и сохранение их в CookieJar, если это разрешено политикой.

CookieJar будет искать допустимые заголовки Set-Cookie и Set-Cookie2 в аргументе response, и сохранять cookies, если это необходимо (при условии одобрения метода CookiePolicy.set_ok()).

Объект ответ (обычно результат вызова 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: Объекту request необходим атрибут 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, которые имеют истинный атрибут discard (обычно потому, что у них не было атрибута max-age или expires cookie, или был явный атрибут discard cookie). Для интерактивных браузеров завершение сеанса обычно соответствует закрытию окна браузера.

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

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

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

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

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

filename - имя файла, в котором будут сохранены cookies. Если filename не указано, используется self.filename (по умолчанию используется значение, переданное в конструктор, если таковое имеется); если self.filename - None, то поднимается вопрос ValueError.

ignore_discard: сохранять даже те файлы cookie, которые настроены на отказ от использования. ignore_expires: сохранять даже те файлы 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, то печенье загружается лениво с диска. Этот атрибут не должен быть назначен. Это только подсказка, так как это влияет только на производительность, а не на поведение (если только cookies на диске не меняются). Объект CookieJar может игнорировать его. Ни один из классов FileCookieJar, включенных в стандартную библиотеку, не загружает cookies лениво.

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

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

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

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

Примечание

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

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

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

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

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

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

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

Объекты политики CookiePolicy¶

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

Если domain_return_ok() возвращает true для домена cookie, path_return_ok() вызывается для пути cookie. В противном случае 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().

Аргумент запрос соответствует документированному для return_ok().

CookiePolicy.path_return_ok(path, request)¶

Возвращает False, если куки не должны быть возвращены, учитывая путь к кукам.

См. документацию для domain_return_ok().

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

CookiePolicy.netscape¶

Внедрить протокол Netscape.

CookiePolicy.rfc2965¶

Реализуйте протокол RFC 2965.

CookiePolicy.hide_cookie2¶

Не добавляйте в запросы заголовок Cookie2 (наличие этого заголовка указывает серверу, что мы понимаем RFC 2965 cookies).

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

Объекты DefaultCookiePolicy¶

Реализует стандартные правила приема и возврата файлов cookie.

Поддерживаются куки RFC 2965 и 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, этот класс позволяет блокировать и разрешать доменам устанавливать и получать cookies. Есть также некоторые переключатели строгости, которые позволяют немного ужесточить довольно свободные правила протокола Netscape (ценой блокирования некоторых доброкачественных cookies).

Предусмотрены блокирующий список доменов и разрешающий список (по умолчанию оба выключены). Только домены, отсутствующие в списке блокировки и присутствующие в списке разрешений (если список разрешений активен), участвуют в установке и возврате 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)¶

Возвращает, находится ли домен в списке блокировки для установки или получения cookies.

DefaultCookiePolicy.allowed_domains()¶

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)¶

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

DefaultCookiePolicy.is_not_allowed(domain)¶

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

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

DefaultCookiePolicy.rfc2109_as_netscape¶

Если true, запросите, чтобы экземпляр CookieJar понизил версию cookies RFC 2109 (т.е. cookies, полученные в заголовке Set-Cookie с атрибутом cookie-версии, равным 1) до версии cookies Netscape, установив атрибут version экземпляра Cookie в 0. Значение по умолчанию None, в этом случае cookies RFC 2109 понижаются, если и только если обработка RFC 2965 выключена. Поэтому по умолчанию куки RFC 2109 понижаются.

Переключатели общей строгости:

DefaultCookiePolicy.strict_domain¶

Не позволяйте сайтам устанавливать двухкомпонентные домены с кодом страны в доменах верхнего уровня типа .co.uk, .gov.uk, .co.nz.и т.д. Это далеко не идеально и не гарантированно работает!

RFC 2965 переключатели строгости протокола:

DefaultCookiePolicy.strict_rfc2965_unverifiable¶

Соблюдайте правила RFC 2965 в отношении непроверяемых транзакций (обычно непроверяемой считается транзакция, возникшая в результате перенаправления или запроса изображения, размещенного на другом сайте). Если это неверно, куки никогда не блокируются на основании проверяемости.

Переключатели строгости протокола Netscape:

DefaultCookiePolicy.strict_ns_unverifiable¶

Применяйте правила RFC 2965 о непроверяемых транзакциях даже к файлам cookie Netscape.

DefaultCookiePolicy.strict_ns_domain¶

Флаги, указывающие, насколько строгими должны быть правила сопоставления доменов для файлов cookie Netscape. Допустимые значения см. ниже.

DefaultCookiePolicy.strict_ns_set_initial_dollar¶

Игнорировать куки в заголовках Set-Cookie:, имена которых начинаются с '$'.

DefaultCookiePolicy.strict_ns_set_path¶

Не разрешайте установку cookies, путь к которым не совпадает с URI запроса.

strict_ns_domain - это набор флагов. Его значение строится с помощью букв «или-» (например, DomainStrictNoDots|DomainStrictNonDomain означает, что оба флага установлены).

DefaultCookiePolicy.DomainStrictNoDots¶

При установке cookies «префикс хоста» не должен содержать точку (например, www.foo.bar.com не может установить cookie для .bar.com, потому что www.foo содержит точку).

DefaultCookiePolicy.DomainStrictNonDomain¶

Cookies, в которых явно не указан cookie-атрибут domain, могут быть возвращены только домену, равному домену, установившему cookie (например, spam.example.com не будут возвращены cookie от example.com, в которых не указан cookie-атрибут domain).

DefaultCookiePolicy.DomainRFC2965Match¶

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

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

DefaultCookiePolicy.DomainLiberal¶

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

DefaultCookiePolicy.DomainStrict¶

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

Объекты печенья¶

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

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

Cookie.version¶

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

Cookie.name¶

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

Cookie.value¶

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

Cookie.port¶

Строка, представляющая порт или набор портов (например, „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 может «понижать» куки RFC 2109 до куки 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 истекло время, на которое сервер запросил его истечение. Если указано 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. Включите cookies RFC 2965, будьте более строги к доменам при установке и возврате cookies Netscape, и заблокируйте некоторые домены от установки cookies или их возврата:

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/")