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

Объекты CookieJar и FileCookieJar¶CookieJar and FileCookieJar objects

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

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

CookieJar.add_cookie_header(request)¶

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

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

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

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

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

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

Объект запроса (обычно экземпляр 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, извлечённых из объекта ответа.

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

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

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

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¶

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

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

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

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

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

Примечание

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

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

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

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

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

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

Изменено в версии 3.8: Параметр filename поддерживает объект, подобный пути.

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

Этот метод – оптимизация. Он избавляет от необходимости проверять каждый куки для определённого домена (что может потребовать чтения многих файлов). Возврат 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() вызывается для каждого домена куки, а не только для домена запроса. Например, функция может вызываться как с ".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 может использоваться как «нулевая политика», позволяющая устанавливать и принимать любые куки (вряд ли это будет полезно).

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

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

DefaultCookiePolicy.allowed_domains()¶

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)¶

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

DefaultCookiePolicy.is_not_allowed(domain)¶

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

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

DefaultCookiePolicy.rfc2109_as_netscape¶

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

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

DefaultCookiePolicy.strict_domain¶

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

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

DefaultCookiePolicy.strict_rfc2965_unverifiable¶

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

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

DefaultCookiePolicy.strict_ns_unverifiable¶

Применяет правила RFC 2965 для непроверяемых транзакций даже к cookies 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 (например, spam.example.com не получит cookie от example.com, не имевшие атрибута domain).

DefaultCookiePolicy.DomainRFC2965Match¶

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

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

DefaultCookiePolicy.DomainLiberal¶

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

DefaultCookiePolicy.DomainStrict¶

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

Объекты Cookie¶Cookie objects

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

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

Cookie.version¶

Целое число или None. Cookie Netscape имеют version 0. Cookie RFC 2965 и RFC 2109 имеют атрибут cookie 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.domain¶

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

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

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

Cookie.has_nonstandard_attr(name)¶

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

Cookie.get_nonstandard_attr(name, default=None)¶

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

Cookie.set_nonstandard_attr(name, value)¶

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

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

Cookie.is_expired(now=None)¶

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

Примеры¶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. Включите RFC 2965 куки, будьте более строги к доменам при установке и возврате куки Netscape и заблокируйте некоторые домены, чтобы они не могли устанавливать куки или возвращать их:

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