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

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

Модуль cookielib определяет классы для автоматической обработки файлов cookie HTTP. Он полезен для доступа к веб-сайтам, которые требуют, чтобы небольшие фрагменты данных — куки — были установлены на клиентском компьютере ответом HTTP веб-сервера, а затем возвращались на сервер в последующих HTTP-запросах.

Обрабатываются как обычный протокол файлов cookie Netscape, так и протокол, определенный в RFC 2965. Обработка RFC 2965 отключена по умолчанию. Файлы cookie RFC 2109 парсятся как файлы cookie Netscape и впоследствии обрабатываются как файлы cookie Netscape или RFC 2965 в зависимости от действующей «политики». Обратите внимание, что подавляющее большинство файлов cookie в Интернете являются файлами cookie Netscape. cookielib пытается следовать фактическому протоколу файлов cookie Netscape (который существенно отличается от протокола, описанного в исходной спецификации Netscape), включая учет max-age и port атрибутов файлов cookie, введенных в RFC 2965.

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

exception cookielib.LoadError

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

Примечание

Для обратной совместимости с Python 2.4 (который генерировал IOError), LoadError является подклассом IOError.

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

class cookielib.CookieJar(policy=None)

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

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

class cookielib.FileCookieJar(filename, delayload=None, policy=None)

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

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

class cookielib.CookiePolicy

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

class cookielib.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 с которых никогда не принимаются и не возвращаются. 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 «преобразуются» экземпляром CookieJar в файлы cookie Netscape, установив атрибут version экземпляра Cookie в 0. DefaultCookiePolicy также предоставляет некоторые параметры для настройки политики.

class cookielib.Cookie

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

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

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

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

CookieJar.add_cookie_header(request)

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

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

Объект запроса (обычно экземпляр urllib2.Request) должен поддерживать методы get_full_url(), get_host(), get_type(), unverifiable(), get_origin_req_host(), has_header(), get_header(), header_items(), и add_unredirected_header(), как описано в urllib2.

CookieJar.extract_cookies(response, request)

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

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

Объект response (обычно результат вызова urllib2.urlopen() или аналогичного) должен поддерживать метод info(), который возвращает объект с методом getallmatchingheaders() (обычно экземпляр mimetools.Message).

Объект запроса (обычно экземпляр urllib2.Request) должен поддерживать методы get_full_url(), get_host(), unverifiable(), и get_origin_req_host(), как документировано в urllib2. Запрос используется для установки значений по умолчанию для атрибутов куки, а также для проверки разрешения установки куки.

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]]])

Очистить некоторые куки.

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

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

CookieJar.clear_session_cookies()

Удалить все сеансовые куки.

Удаляет все содержащиеся куки, у которых атрибут discard имеет значение true (обычно потому, что у них отсутствовал либо атрибут куки 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. Также может быть вызвано исключение IOError, например, если файл не существует.

Примечание

Для обратной совместимости с Python 2.4 (в котором было вызвано исключение IOError), LoadError является подклассом IOError.

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

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

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

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

FileCookieJar.filename

Имя файла по умолчанию, в котором хранятся куки. К этому атрибуту можно обращаться.

FileCookieJar.delayload

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

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

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

class cookielib.MozillaCookieJar(filename, delayload=None, policy=None)

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

Примечание

Версия 3 веб-браузера Firefox больше не записывает куки в формате файлов cookies.txt.

Примечание

Это приводит к потере информации о куках RFC 2965, а также о более новых или нестандартных атрибутах куки, таких как port.

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

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

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

class cookielib.LWPCookieJar(filename, delayload=None, policy=None)

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

3. Объекты CookiePolicy

Объекты, реализующие интерфейс CookiePolicy, имеют следующие методы:

CookiePolicy.set_ok(cookie, request)

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

cookie — экземпляр класса cookielib.Cookie. request — объект, реализующий интерфейс, определённый в документации для CookieJar.extract_cookies().

CookiePolicy.return_ok(cookie, request)

Возвращает булево значение, указывающее, следует ли возвращать куки серверу.

cookie — экземпляр класса cookielib.Cookie. request — объект, реализующий интерфейс, определённый в документации для CookieJar.add_cookie_header().

CookiePolicy.domain_return_ok(domain, request)

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

Этот метод является оптимизацией. Он устраняет необходимость проверки каждого куки с определённым доменом (что может потребовать чтения многих файлов). Возвращение true из domain_return_ok() и path_return_ok() оставляет всю работу return_ok().

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

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

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

CookiePolicy.netscape

Реализует протокол Netscape.

CookiePolicy.rfc2965

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

CookiePolicy.hide_cookie2

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

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

4. Объекты DefaultCookiePolicy

Реализует стандартные правила для принятия и возврата куки.

Обеспечивает поддержку куки RFC 2965 и Netscape. Обработка RFC 2965 выключена по умолчанию.

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

import cookielib
class MyCookiePolicy(cookielib.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True

Помимо функций, необходимых для реализации интерфейса CookiePolicy, этот класс позволяет блокировать и разрешать домены для установки и получения куки. Также есть несколько переключателей строгости, которые позволяют немного ужесточить довольно свободные правила протокола Netscape (за счёт блокировки некоторых безобидных куки).

Предоставляется чёрный и белый списки доменов (оба выключены по умолчанию). Только домены, не находящиеся в чёрном списке и присутствующие в белом списке (если белый список активен), участвуют в установке и возврате куки. Используйте аргумент конструктора blocked_domains и методы blocked_domains() и set_blocked_domains() (и соответствующие аргументы и методы для allowed_domains). Если вы установили белый список, вы можете снова отключить его, задав значение None.

Домены в чёрном или белом списках, не начинающиеся с точки, должны совпадать с доменом куки для соответствия. Например, "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 в чёрном списке для установки или получения куки.

DefaultCookiePolicy.allowed_domains()

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

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

DefaultCookiePolicy.is_not_allowed(domain)

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

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

DefaultCookiePolicy.rfc2109_as_netscape

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

New in version 2.5.

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

DefaultCookiePolicy.strict_domain

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

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

DefaultCookiePolicy.strict_rfc2965_unverifiable

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

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

DefaultCookiePolicy.strict_ns_unverifiable

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

DefaultCookiePolicy.strict_ns_domain

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

DefaultCookiePolicy.strict_ns_set_initial_dollar

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

DefaultCookiePolicy.strict_ns_set_path

Не разрешать установку куки, путь которых не соответствует пути URI запроса.

strict_ns_domain представляет собой набор флагов. Его значение формируется путём побитового ИЛИ (например, DomainStrictNoDots|DomainStrictNonDomain означает, что оба флага установлены).

DefaultCookiePolicy.DomainStrictNoDots

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

DefaultCookiePolicy.DomainStrictNonDomain

Куки, которые явно не указали атрибут domain куки, могут быть возвращены только в домен, равный домену, который установил куки (например, spam.example.com не получит куки из example.com, которые не имели атрибута domain куки).

DefaultCookiePolicy.DomainRFC2965Match

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

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

DefaultCookiePolicy.DomainLiberal

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

DefaultCookiePolicy.DomainStrict

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

5. Объекты куки

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

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

Cookie.version

Целое число или None. Куки Netscape имеют version 0. Куки RFC 2965 и RFC 2109 имеют атрибут куки version со значением 1. Однако обратите внимание, что cookielib может «снизить» куки RFC 2109 до куки Netscape, в этом случае version равно 0.

Cookie.name

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

Cookie.value

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

Cookie.port

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

Cookie.path

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

Cookie.secure

True если куки должны возвращаться только по защищённому соединению.

Cookie.expires

Дата истечения срока действия в секундах с начала эпохи, или None. См. также метод is_expired().

Cookie.discard

True если это куки сессии.

Cookie.comment

Строка комментария от сервера, объясняющего назначение этой куки, или None.

Cookie.comment_url

URL, содержащий комментарий сервера, объясняющий назначение этой куки, или None.

Cookie.rfc2109

True если эта куки была получена как куки RFC 2109 (т. е. куки поступила в заголовке Set-Cookie, а значение атрибута куки Version в этом заголовке было 1). Этот атрибут предоставляется, потому что cookielib может «снизить» куки RFC 2109 до куки Netscape, в этом случае version равно 0.

Добавлена в версии 2.5.

Cookie.port_specified

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

Cookie.domain_specified

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

Cookie.domain_initial_dot

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

Куки могут иметь дополнительные нестандартные атрибуты куки. К ним можно получить доступ с помощью следующих методов:

Cookie.has_nonstandard_attr(name)

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

Cookie.get_nonstandard_attr(name, default=None)

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

Cookie.set_nonstandard_attr(name, value)

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

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

Cookie.is_expired([now=None])

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

6. Примеры

Первый пример демонстрирует наиболее распространённое использование cookielib:

import cookielib, urllib2
cj = cookielib.CookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

Этот пример иллюстрирует, как открыть URL-адрес, используя ваши куки Netscape, Mozilla или Lynx (предполагается соглашение Unix/Netscape для расположения файла куки):

import os, cookielib, urllib2
cj = cookielib.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

Следующий пример иллюстрирует использование DefaultCookiePolicy. Включить куки RFC 2965, быть более строгим относительно доменов при установке и возврате куки Netscape, и заблокировать некоторые домены от установки куки или их возврата:

import urllib2
from cookielib import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=DefaultCookiePolicy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")