Содержание страницы

21.24. `http.cookiejar` – Обработка cookie для HTTP-клиентов¶http.cookiejar – Cookie handling for HTTP clients

The http.cookiejar module defines classes for automatic handling of HTTP cookies. It is useful for accessing web sites that require small pieces of data – cookies – to be set on the client machine by an HTTP response from a web server, and then returned to the server in later HTTP requests.

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

Примечание

Различные именованные параметры, встречающиеся в заголовках Set-Cookie и Set-Cookie2 (например, domain и expires), обычно называют атрибутами. Чтобы отличать их от атрибутов Python, в документации этого модуля используется термин cookie-attribute.

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

exception http.cookiejar.LoadError¶: Instances of FileCookieJar raise this exception on failure to load cookies from a file. LoadError is a subclass of OSError.

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

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

class http.cookiejar.CookieJar(policy=None)¶

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

The CookieJar class stores HTTP cookies. It extracts cookies from HTTP requests, and returns them in HTTP responses. CookieJar instances automatically expire contained cookies when necessary. Subclasses are also responsible for storing and retrieving cookies from a file or database.

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

policy – это объект, реализующий интерфейс CookiePolicy. Остальные аргументы описаны в документации соответствующих атрибутов.

A CookieJar which can load cookies from, and perhaps save cookies to, a file on disk. Cookies are NOT loaded from the named file until either the load() or revert() method is called. Subclasses of this class are documented in section FileCookieJar subclasses and co-operation with web browsers.

class http.cookiejar.CookiePolicy¶: Этот класс отвечает за принятие решения о том, следует ли принять каждый куки от сервера / вернуть его серверу.

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 – это последовательность доменных имён, с которых мы никогда не принимаем куки и на которые не отправляем куки. allowed_domains, если не равно None, – это последовательность доменов, для которых мы принимаем и отправляем куки. Что касается всех остальных аргументов, см. документацию объектов CookiePolicy и DefaultCookiePolicy.

DefaultCookiePolicy реализует стандартные правила приёма/отклонения для Netscape и RFC 2965 cookie. По умолчанию cookie RFC 2109 (т.е. cookie, полученные в заголовке Set-Cookie с атрибутом cookie version, равным 1) обрабатываются по правилам RFC 2965. Однако если обработка RFC 2965 отключена или rfc2109_as_netscape равно True, cookie RFC 2109 «понижаются» экземпляром CookieJar до Netscape cookie путём установки атрибута version экземпляра Cookie в 0. DefaultCookiePolicy также предоставляет некоторые параметры для более точной настройки политики.

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

См. также

Модуль urllib.request: Открытие URL с автоматической обработкой куки.
Модуль http.cookies: Классы HTTP cookie, в основном полезные для серверного кода. Модули http.cookiejar и http.cookies не зависят друг от друга.
http://wp.netscape.com/newsref/std/cookie_spec.html: Спецификация оригинального протокола Netscape cookie. Хотя это всё ещё доминирующий протокол, «протокол Netscape cookie», реализуемый всеми основными браузерами (а также http.cookiejar), лишь отдалённо напоминает тот, что описан в cookie_spec.html.
RFC 2109 – Механизм управления состоянием HTTP: Заменено RFC 2965. Использует Set-Cookie с version=1.
RFC 2965 – Механизм управления состоянием HTTP: Протокол Netscape с исправленными ошибками. Использует Set-Cookie2 вместо Set-Cookie. Широко не используется.
http://kristol.org/cookie/errata.html: Незавершённые исправления к RFC 2965.

RFC 2964 – Использование управления состоянием HTTP

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

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

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

CookieJar.add_cookie_header(request)¶

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

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

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

CookieJar.extract_cookies(response, request)¶

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

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

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

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

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()¶

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

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

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

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

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

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

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

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

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

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

21.24.2. Подклассы FileCookieJar и взаимодействие с веб-браузерами¶FileCookieJar subclasses and co-operation with web browsers

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

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

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

Примечание

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

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

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

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

class http.cookiejar.LWPCookieJar(filename, delayload=None, policy=None)¶: FileCookieJar, который может загружать и сохранять файлы cookie на диск в формате, совместимом с форматом файла Set-Cookie3 библиотеки libwww-perl. Это удобно, если требуется хранить файлы cookie в читаемом человеком файле.

21.24.3. Объекты CookiePolicy¶CookiePolicy Objects

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

CookiePolicy.set_ok(cookie, request)¶

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

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

CookiePolicy.return_ok(cookie, request)¶

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

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

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

21.24.4. Объекты DefaultCookiePolicy¶DefaultCookiePolicy Objects

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

Охватываются как куки 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 в чёрном списке для установки или получения куки.

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)¶: Устанавливает последовательность разрешённых доменов или None.

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

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

DefaultCookiePolicy.rfc2109_as_netscape¶: Если true, запрашивает, чтобы экземпляр CookieJar понижал версию файлов cookie RFC 2109 (т.е. файлы cookie, полученные в заголовке Set-Cookie с атрибутом версии cookie-attribute, равным 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 для непроверяемых транзакций (обычно непроверяемая транзакция возникает в результате перенаправления или запроса изображения, размещённого на другом сайте). Если это False, куки никогда не блокируются на основе проверяемости.

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

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

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

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

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

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

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

DefaultCookiePolicy.DomainStrictNonDomain¶: Файлы cookie, которые не указали явно атрибут domain cookie-attribute, могут быть возвращены только домену, равному домену, установившему cookie (например, spam.example.com не будут возвращены файлы cookie от example.com, у которых не было domain cookie-attribute).

DefaultCookiePolicy.DomainRFC2965Match¶: При установке куки требовать полного соответствия домена по RFC 2965.

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

DefaultCookiePolicy.DomainLiberal¶: Эквивалентно 0 (то есть все указанные выше флаги строгости домена Netscape отключены).

DefaultCookiePolicy.DomainStrict¶: Эквивалентно DomainStrictNoDots|DomainStrictNonDomain.

21.24.6. Примеры¶Examples

Первый пример показывает наиболее распространённое использование 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 с использованием ваших куки Netscape, Mozilla или Lynx (предполагается соглашение Unix/Netscape о местоположении файла куки):

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