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

Исходный код: Lib/http/cookiejar.py

Модуль 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.

Модуль определяет следующую исключительную ситуацию:

exception http.cookiejar.LoadError

Экземпляры FileCookieJar генерируют это исключение при неудачной загрузке файлов cookie из файла. LoadError является подклассом OSError.

Изменено в версии 3.3: LoadError был сделан подклассом OSError вместо IOError.

Предоставляются следующие классы:

class http.cookiejar.CookieJar(policy=None)

policy — объект, реализующий интерфейс CookiePolicy.

Класс CookieJar хранит файлы cookie HTTP. Он извлекает файлы cookie из HTTP-запросов и возвращает их в HTTP-ответах. Экземпляры CookieJar автоматически истекают содержащимися файлами cookie при необходимости. Подклассы также отвечают за хранение и извлечение файлов cookie из файла или базы данных.

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

policy — объект, реализующий интерфейс CookiePolicy. Для других аргументов см. документацию по соответствующим атрибутам.

Класс CookieJar, который может загружать файлы cookie из файла и, возможно, сохранять файлы cookie в файл на диске. Файлы cookie НЕ загружаются из указанного файла до тех пор, пока не будет вызван метод load() или revert(). Подклассы этого класса документированы в разделе Подклассы FileCookieJar и взаимодействие с веб-браузерами.

class http.cookiejar.CookiePolicy

Этот класс отвечает за решение вопроса о том, следует ли принимать каждый файл cookie от сервера/возвращать на сервер.

class http.cookiejar.DefaultCookiePolicy(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False)

Аргументы конструктора должны передаваться только как именованные аргументы. blocked_domains — последовательность доменных имён, файлы cookie от которых никогда не принимаются и на которые не возвращаются файлы cookie. allowed_domains, если не None, — последовательность единственных доменов, для которых принимаются и возвращаются файлы cookie. Для всех остальных аргументов см. документацию по объектам 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 «приводятся к виду» файлов cookie Netscape в экземпляре CookieJar, устанавливая атрибут version экземпляра Cookie в 0. DefaultCookiePolicy также предоставляет некоторые параметры для настройки политики.

class http.cookiejar.Cookie

Этот класс представляет файлы cookie Netscape, RFC 2109 и RFC 2965. Не ожидается, что пользователи http.cookiejar будут создавать собственные экземпляры Cookie. Вместо этого, при необходимости вызовите make_cookies() для экземпляра CookieJar.

21.24.1. Объекты CookieJar и FileCookieJar

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

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

CookieJar.add_cookie_header(request)

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

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

Объект запрос (обычно экземпляр urllib.request..Request ) должен поддерживать методы get_full_url(), get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() и атрибут 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.urlopen() или аналогичного) должен поддерживать метод info(), возвращающий экземпляр email.message.Message.

Объект запрос (обычно экземпляр urllib.request.Request) должен поддерживать методы get_full_url(), get_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 реализует следующие дополнительные методы:

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

Сохранить куки в файл.

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

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

ignore_discard: сохранить даже куки, установленные для удаления. ignore_expires: сохранить даже куки, срок действия которых истек.

Файл перезаписывается, если он уже существует, тем самым удаляя все содержащиеся в нём куки. Сохранённые куки можно восстановить позже, используя методы load() или revert().

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

Загрузить куки из файла.

Старые куки сохраняются, если они не перезаписываются вновь загруженными.

Аргументы такие же, как у save().

Имя файла должно иметь формат, понятный для класса, иначе возбуждается LoadError. Также может быть возбуждено OSError, например, если файла не существует.

Изменено в версии 3.3: IOError раньше возбуждался, сейчас он является псевдонимом OSError.

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

Очистить все куки и перезагрузить куки из сохранённого файла.

revert() может возбуждать те же исключения, что и load(). Если произошла ошибка, состояние объекта не изменится.

FileCookieJar экземпляры имеют следующие публичные атрибуты:

FileCookieJar.filename

Имя файла по умолчанию, в котором хранятся куки. Этот атрибут может быть изменён.

FileCookieJar.delayload

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

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

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

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

A FileCookieJar that can load from and save cookies to disk in the Mozilla cookies.txt file format (which is also used by the Lynx and Netscape browsers).

Примечание

This loses information about RFC 2965 cookies, and also about newer or non-standard cookie-attributes such as port.

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

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

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

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

A FileCookieJar that can load from and save cookies to disk in format compatible with the libwww-perl library’s Set-Cookie3 file format. This is convenient if you want to store cookies in a human-readable file.

21.24.3. Объекты 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 не должны быть возвращены, учитывая домен cookie.

Этот метод является оптимизацией. Он устраняет необходимость проверки каждого 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().

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

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

21.24.4. Объекты DefaultCookiePolicy

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

Оба типа файлов 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, этот класс позволяет блокировать и разрешать домены для установки и получения файлов 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)

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

DefaultCookiePolicy.allowed_domains()

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

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

DefaultCookiePolicy.is_not_allowed(domain)

Возвращает значение, указывающее, находится ли domain в списке запрещенных для установки или получения cookie.

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

DefaultCookiePolicy.rfc2109_as_netscape

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

Общие переключатели строгости:

DefaultCookiePolicy.strict_domain

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

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

DefaultCookiePolicy.strict_rfc2965_unverifiable

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

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

DefaultCookiePolicy.strict_ns_unverifiable

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

DefaultCookiePolicy.strict_ns_domain

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

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-attribute, могут быть возвращены только домену, который установил cookie (например, spam.example.com не получит cookie от example.com, у которых не было атрибута domain cookie).

DefaultCookiePolicy.DomainRFC2965Match

Требует полного соответствия домену по RFC 2965.

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

DefaultCookiePolicy.DomainLiberal

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

DefaultCookiePolicy.DomainStrict

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

21.24.5. Объекты Cookie

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

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

Cookie.version

Целое число или None. Netscape cookie имеют version 0. RFC 2965 и RFC 2109 cookie имеют атрибут cookie-attribute version равный 1. Однако обратите внимание, что http.cookiejar может «снижать» RFC 2109 cookie до Netscape cookie, в этом случае 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 было получено как RFC 2109 cookie (т.е. cookie поступило в заголовке Set-Cookie, и значение атрибута Version cookie в этом заголовке было 1). Этот атрибут предоставляется, поскольку http.cookiejar может «снижать» RFC 2109 cookie до Netscape cookie, в этом случае version равно 0.

Cookie.port_specified

True если порт или набор портов был явно указан сервером (в заголовке Set-Cookie / Set-Cookie2).

Cookie.domain_specified

True если домен был явно указан сервером.

Cookie.domain_initial_dot

True если домен, явно указанный сервером, начинался с точки ('.').

Cookies могут иметь дополнительные нестандартные атрибуты cookie. К ним можно получить доступ, используя следующие методы:

Cookie.has_nonstandard_attr(name)

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

Cookie.get_nonstandard_attr(name, default=None)

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

Cookie.set_nonstandard_attr(name, value)

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

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

Cookie.is_expired(now=None)

True если cookie истек, то есть прошло время, в которое сервер запросил его истечение. Если now задано (в секундах с эпохи), возвращает, истек ли cookie в указанное время.

21.24.6. Примеры

Первый пример демонстрирует наиболее распространенное использование 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/")