Объекты запроса¶Request Objects

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

Request.full_url¶

Оригинальный URL, переданный конструктору.

Изменено в версии 3.4.

Request.full_url – это свойство с сеттером, геттером и делитером. При получении full_url возвращает оригинальный URL запроса вместе с фрагментом, если он присутствовал.

Request.type¶

Схема URI.

Request.host¶

Авторитетная часть URI, обычно хост, но может также содержать порт, отделённый двоеточием.

Request.origin_req_host¶

Исходный хост запроса, без порта.

Request.selector¶

Путь URI. Если Request использует прокси, то selector будет содержать полный URL, который передаётся прокси.

Request.data¶

Тело сущности запроса или None, если не задано.

Изменено в версии 3.4: Изменение значения Request.data теперь удаляет заголовок “Content-Length” , если он был ранее установлен или вычислен.

Request.unverifiable¶

логическое значение, указывает, является ли запрос непроверяемым, как определено в RFC 2965.

Request.method¶

HTTP-метод запроса. По умолчанию его значение равно None, что означает, что get_method() выполнит обычное вычисление метода. Значение можно задать (тем самым переопределив вычисление по умолчанию в get_method()), либо установив значение по умолчанию на уровне класса в подклассе Request, либо передав значение в конструктор Request через аргумент method.

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

Изменено в версии 3.4: Теперь значение по умолчанию можно задавать в подклассах; ранее его можно было установить только через аргумент конструктора.

Request.get_method()¶

Возвращает строку, указывающую HTTP-метод запроса. Если Request.method не равно None, возвращается его значение; иначе возвращается 'GET', если Request.data равно None, или 'POST' в противном случае. Это имеет смысл только для HTTP-запросов.

Изменено в версии 3.3: get_method теперь учитывает значение Request.method.

Request.add_header(key, val)¶

Добавляет ещё один заголовок в запрос. В настоящее время заголовки игнорируются всеми обработчиками, кроме HTTP-обработчиков, где они добавляются в список заголовков, отправляемых серверу. Обратите внимание, что не может быть более одного заголовка с одним и тем же именем, и последующие вызовы перезаписывают предыдущие, если key совпадает. В настоящее время это не приводит к потере функциональности HTTP, поскольку все заголовки, которые имеют смысл при многократном использовании, имеют (заголовок-специфичный) способ достижения той же функциональности с помощью только одного заголовка. Обратите внимание, что заголовки, добавленные этим методом, также добавляются в перенаправленные запросы.

Request.add_unredirected_header(key, header)¶

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

Request.has_header(header)¶

Возвращает, имеет ли экземпляр указанный заголовок (проверяет как обычные, так и неперенаправленные).

Request.remove_header(header)¶

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

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

Request.get_full_url()¶

Возвращает URL, переданный в конструктор.

Изменено в версии 3.4.

Возвращает Request.full_url

Request.set_proxy(host, type)¶

Подготавливает запрос, подключаясь к прокси-серверу. host и type заменят соответствующие значения экземпляра, а selector экземпляра будет содержать исходный URL, переданный в конструктор.

Request.get_header(header_name, default=None)¶

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

Request.header_items()¶

Возвращает список кортежей (имя_заголовка, значение_заголовка) заголовков запроса.

Объекты OpenerDirector¶OpenerDirector Objects

Экземпляры OpenerDirector имеют следующие методы:

OpenerDirector.add_handler(handler)¶

handler должен быть экземпляром BaseHandler. Поиск осуществляется среди следующих методов, и они добавляются в возможные цепочки (обратите внимание: ошибки HTTP являются особым случаем). Обратите внимание, что в следующих методах протокол следует заменить на фактический обрабатываемый протокол, например http_response() будет обработчиком ответа протокола HTTP. Кроме того, type следует заменить на фактический код HTTP, например http_error_404() будет обрабатывать ошибки HTTP 404.

• <protocol>_open() – сигнал о том, что обработчик умеет открывать URL протокол.

  Подробнее см. BaseHandler.<protocol>_open().

• http_error_<type>() – сигнал о том, что обработчик умеет обрабатывать ошибки HTTP с кодом ошибки HTTP type.

  Подробнее см. BaseHandler.http_error_<nnn>().

• <protocol>_error() – сигнал о том, что обработчик умеет обрабатывать ошибки от (не-http) протокол.

• <protocol>_request() – сигнал о том, что обработчик умеет предварительно обрабатывать запросы протокол.

  Подробнее см. BaseHandler.<protocol>_request().

• <protocol>_response() – сигнал о том, что обработчик умеет постобрабатывать ответы протокол.

  Подробнее см. BaseHandler.<protocol>_response().

OpenerDirector.open(url, data=None[, timeout])¶

Открывает указанный url (который может быть объектом запроса или строкой), при необходимости передавая указанные data. Аргументы, возвращаемые значения и вызываемые исключения такие же, как у urlopen() (который просто вызывает метод open() текущего установленного глобального OpenerDirector). Необязательный параметр timeout задаёт тайм-аут в секундах для блокирующих операций, таких как попытка подключения (если не указан, будет использоваться глобальная настройка тайм-аута по умолчанию). Функция тайм-аута на самом деле работает только для HTTP, HTTPS и FTP соединений.

OpenerDirector.error(proto, *args)¶

Обрабатывает ошибку указанного протокола. Вызывает зарегистрированные обработчики ошибок для данного протокола с указанными аргументами (зависящими от протокола). Протокол HTTP является особым случаем: для определения конкретного обработчика ошибок используется код ответа HTTP; обратитесь к методам http_error_<type>() классов обработчиков.

Возвращаемые значения и вызываемые исключения такие же, как у urlopen().

Объекты OpenerDirector открывают URL в три этапа:

Порядок вызова этих методов в каждом этапе определяется сортировкой экземпляров обработчиков.

1. Каждый обработчик, имеющий метод с именем <protocol>_request(), вызывает этот метод для предварительной обработки запроса.

2. Обработчики, имеющие метод с именем <protocol>_open(), вызываются для обработки запроса. Этот этап завершается, когда обработчик либо возвращает значение, отличное от None (т.е. ответ), либо вызывает исключение (обычно URLError). Исключения могут распространяться дальше.

   На самом деле, описанный выше алгоритм сначала применяется для методов с именем default_open(). Если все такие методы возвращают None, алгоритм повторяется для методов с именем <protocol>_open(). Если все такие методы возвращают None, алгоритм повторяется для методов с именем unknown_open().

   Обратите внимание, что реализация этих методов может включать вызовы методов open() и error() родительского экземпляра OpenerDirector.

3. Каждый обработчик, имеющий метод с именем <protocol>_response(), вызывает этот метод для постобработки ответа.

Объекты BaseHandler¶BaseHandler Objects

Объекты BaseHandler предоставляют несколько методов, которые непосредственно полезны, а также другие методы, предназначенные для использования производными классами. Они предназначены для прямого использования:

BaseHandler.add_parent(director)¶

Добавляет директор в качестве родителя.

BaseHandler.close()¶

Удаляет всех родителей.

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

BaseHandler.parent¶

Действительный OpenerDirector, который можно использовать для открытия через другой протокол или для обработки ошибок.

BaseHandler.default_open(req)¶

Этот метод не определён в BaseHandler, но подклассы должны определить его, если хотят перехватывать все URL.

Если этот метод реализован, он будет вызван родительским OpenerDirector. Он должен возвращать файлоподобный объект, как описано в возвращаемом значении метода open() класса OpenerDirector, или None. Он должен вызывать исключение URLError, если не происходит действительно исключительной ситуации (например, MemoryError не должен отображаться на URLError).

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

BaseHandler.<protocol>_open(req)

Этот метод не определён в BaseHandler, но подклассы должны определить его, если хотят обрабатывать URL с указанным протоколом.

Если этот метод определён, он будет вызван родительским OpenerDirector. Возвращаемые значения должны быть такими же, как для default_open().

BaseHandler.unknown_open(req)¶

Этот метод не определён в BaseHandler, но подклассы должны определить его, если хотят перехватывать все URL, для которых нет зарегистрированного обработчика для открытия.

Если этот метод реализован, он будет вызван parent OpenerDirector. Возвращаемые значения должны быть такими же, как для default_open().

BaseHandler.http_error_default(req, fp, code, msg, hdrs)¶

Этот метод не определён в BaseHandler, но подклассы должны переопределить его, если они намерены обеспечить всеобъемлющую обработку для иначе необработанных HTTP-ошибок. Он будет автоматически вызван OpenerDirector при получении ошибки и обычно не должен вызываться в других обстоятельствах.

OpenerDirector вызовет этот метод с пятью позиционными аргументами:

1. объект Request,

2. файлоподобный объект с телом HTTP-ошибки,

3. трёхзначный код ошибки в виде строки,

4. понятное пользователю объяснение кода в виде строки и

5. заголовки ошибки в виде объекта отображения.

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

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn должен быть трёхзначным HTTP-кодом ошибки. Этот метод также не определён в BaseHandler, но будет вызван, если он существует, на экземпляре подкласса, когда возникает HTTP-ошибка с кодом nnn.

Подклассы должны переопределить этот метод для обработки конкретных HTTP-ошибок.

Аргументы, возвращаемые значения и вызываемые исключения должны быть такими же, как для http_error_default().

BaseHandler.<protocol>_request(req)

Этот метод не определён в BaseHandler, но подклассы должны определить его, если хотят предварительно обрабатывать запросы заданного протокола.

Если этот метод определён, он будет вызван родительским OpenerDirector. req будет объектом Request. Возвращаемое значение должно быть объектом Request.

BaseHandler.<protocol>_response(req, response)

Этот метод не определён в BaseHandler, но подклассы должны определить его, если хотят выполнять постобработку ответов заданного протокола.

Этот метод, если он определён, будет вызван родительским OpenerDirector. req будет объектом Request. response будет объектом, реализующим тот же интерфейс, что и возвращаемое значение urlopen(). Возвращаемое значение должно реализовывать тот же интерфейс, что и возвращаемое значение urlopen().

Объекты HTTPRedirectHandler¶HTTPRedirectHandler Objects

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)¶

Возвращает Request или None в ответ на перенаправление. Этот метод вызывается реализациями по умолчанию методов http_error_30*(), когда от сервера получено перенаправление. Если перенаправление должно произойти, верните новый Request, чтобы http_error_30*() смог выполнить перенаправление на newurl. В противном случае возбудите HTTPError, если никакой другой обработчик не должен пытаться обработать этот URL, или верните None, если вы не можете, но другой обработчик смог бы.

Примечание

Реализация по умолчанию этого метода не следует строго RFC 2616, который говорит, что ответы 301 и 302 на запросы POST не должны автоматически перенаправляться без подтверждения пользователем. В действительности браузеры разрешают автоматическое перенаправление таких ответов, меняя POST на GET, и реализация по умолчанию воспроизводит такое поведение.

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)¶

Перенаправляет на URL Location: или URI:. Этот метод вызывается родительским OpenerDirector при получении HTTP-ответа «Moved Permanently».

HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)¶

То же, что и http_error_301(), но вызывается для ответа «Found».

HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)¶

То же, что и http_error_301(), но вызывается для ответа «See Other».

HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)¶

То же, что и http_error_301(), но вызывается для ответа «Temporary Redirect». Не разрешает изменять метод запроса с POST на GET.

HTTPRedirectHandler.http_error_308(req, fp, code, msg, hdrs)¶

То же, что и http_error_301(), но вызывается для ответа «Permanent Redirect». Не разрешает изменять метод запроса с POST на GET.

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

Объекты HTTPCookieProcessor¶HTTPCookieProcessor Objects

Экземпляры HTTPCookieProcessor имеют один атрибут:

HTTPCookieProcessor.cookiejar¶

http.cookiejar.CookieJar, в котором хранятся куки.

Объекты ProxyHandler¶ProxyHandler Objects

ProxyHandler.<protocol>_open(request)

Объект ProxyHandler будет иметь метод <protocol>_open() для каждого протокол, для которого есть прокси в словаре proxies, переданном в конструктор. Метод будет изменять запросы для прохождения через прокси, вызывая request.set_proxy(), и вызывать следующий обработчик в цепочке для непосредственного выполнения протокола.

Объекты HTTPPasswordMgr¶HTTPPasswordMgr Objects

Эти методы доступны у объектов HTTPPasswordMgr и HTTPPasswordMgrWithDefaultRealm.

HTTPPasswordMgr.add_password(realm, uri, user, passwd)¶

uri может быть как одним URI, так и последовательностью URI. realm, user и passwd должны быть строками. В результате (user, passwd) будет использоваться в качестве токенов аутентификации, когда запрашивается аутентификация для realm и супер-URI любого из заданных URI.

HTTPPasswordMgr.find_user_password(realm, authuri)¶

Получает имя пользователя/пароль для заданных realm и URI, если они есть. Этот метод вернёт (None, None), если нет соответствующей пары пользователь/пароль.

Для объектов HTTPPasswordMgrWithDefaultRealm область None будет проверена, если заданная realm не имеет соответствующей пары пользователь/пароль.

Объекты HTTPPasswordMgrWithPriorAuth¶HTTPPasswordMgrWithPriorAuth Objects

Этот менеджер паролей расширяет HTTPPasswordMgrWithDefaultRealm, чтобы поддерживать отслеживание URI, для которых учётные данные аутентификации должны всегда отправляться.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)¶

realm, uri, user, passwd – как и для HTTPPasswordMgr.add_password(). is_authenticated устанавливает начальное значение флага is_authenticated для указанного URI или списка URI. Если is_authenticated указан как True, realm игнорируется.

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)¶

То же, что и для объектов HTTPPasswordMgrWithDefaultRealm

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)¶

Обновляет флаг is_authenticated для указанного uri или списка URI.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)¶

Возвращает текущее состояние флага is_authenticated для указанного URI.

Объекты AbstractBasicAuthHandler¶AbstractBasicAuthHandler Objects

AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶

Обрабатывает запрос аутентификации, получая пару пользователь/пароль и повторяя запрос. authreq должен быть именем заголовка, в котором содержится информация о realm в запросе, host указывает URL и путь для аутентификации, req должен быть (неудачным) объектом Request, а headers – заголовками ошибки.

host – это либо authority (например, "python.org"), либо URL, содержащий компонент authority (например, "https://python.org/"). В любом случае, authority не должен содержать компонент userinfo (поэтому "python.org" и "python.org:80" подходят, а "joe:password@python.org" – нет).

Объекты HTTPBasicAuthHandler¶HTTPBasicAuthHandler Objects

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

Объекты ProxyBasicAuthHandler¶ProxyBasicAuthHandler Objects

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

Объекты AbstractDigestAuthHandler¶AbstractDigestAuthHandler Objects

AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)¶

authreq должен быть именем заголовка, в котором содержится информация о realm в запросе, host должен быть хостом для аутентификации, req должен быть (неудачным) объектом Request, а headers – заголовками ошибки.

Объекты HTTPDigestAuthHandler¶HTTPDigestAuthHandler Objects

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

Объекты ProxyDigestAuthHandler¶ProxyDigestAuthHandler Objects

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)¶

Повторяет запрос с информацией аутентификации, если она доступна.

Объекты HTTPHandler¶HTTPHandler Objects

HTTPHandler.http_open(req)¶

Отправляет HTTP-запрос, который может быть GET или POST, в зависимости от req.data.

Объекты HTTPSHandler¶HTTPSHandler Objects

HTTPSHandler.https_open(req)¶

Отправляет HTTPS-запрос, который может быть GET или POST, в зависимости от req.data.

Объекты FileHandler¶FileHandler Objects

FileHandler.file_open(req)¶

Открывает файл локально, если имя хоста отсутствует или равно 'localhost'.

Изменено в версии 3.2: Этот метод применим только для локальных имён хостов. При указании удалённого имени хоста вызывается исключение URLError.

Объекты DataHandler¶DataHandler Objects

DataHandler.data_open(req)¶

Читает data URL. Такой URL содержит содержимое, закодированное непосредственно в самом URL. Синтаксис data URL описан в RFC 2397. Эта реализация игнорирует пробелы в data URL с base64-кодированием, поэтому URL может быть перенесён в любом исходном файле, откуда он берётся. Но даже если некоторые браузеры не обращают внимания на отсутствие дополнения (padding) в конце base64-кодированного data URL, данная реализация в таком случае вызовет исключение ValueError.

Объекты FTPHandler¶FTPHandler Objects

FTPHandler.ftp_open(req)¶

Открывает FTP-файл, указанный req. Вход всегда выполняется с пустыми именем пользователя и паролем.

Объекты CacheFTPHandler¶CacheFTPHandler Objects

Объекты CacheFTPHandler являются объектами FTPHandler со следующими дополнительными методами:

CacheFTPHandler.setTimeout(t)¶

Устанавливает тайм-аут соединений равным t секунд.

CacheFTPHandler.setMaxConns(m)¶

Устанавливает максимальное количество кэшированных соединений равным m.

Объекты UnknownHandler¶UnknownHandler Objects

UnknownHandler.unknown_open()¶

Вызывает исключение URLError.

Объекты HTTPErrorProcessor¶HTTPErrorProcessor Objects

HTTPErrorProcessor.http_response(request, response)¶

Обрабатывает ошибочные HTTP-ответы.

Для кода 200 объект ответа возвращается немедленно.

Для кодов ошибок, отличных от 200, этот метод просто передаёт задачу методам обработчика http_error_<type>() через OpenerDirector.error(). В конечном счёте, HTTPDefaultErrorHandler вызовет исключение HTTPError, если ни один другой обработчик не обработает ошибку.

HTTPErrorProcessor.https_response(request, response)¶

Обрабатывает ошибочные HTTPS-ответы.

Поведение аналогично http_response().

Примеры¶Examples

В дополнение к примерам ниже, больше примеров приведено в HOWTO Fetch Internet Resources Using The urllib Package.

Этот пример получает главную страницу python.org и отображает первые 300 байт.

>>> import urllib.request
>>> with urllib.request.urlopen('https://www.python.org/') as f:
...     # Ответ может быть сжат (например, 'gzip').
...     print(f.headers.get('Content-Encoding'))
...     data = f.read()
...     if f.headers.get('Content-Encoding') == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:300].decode('utf-8', errors='replace'))

Обратите внимание, что urlopen возвращает объект bytes. Это связано с тем, что urlopen не может автоматически определить кодировку байтового потока, полученного от HTTP-сервера. Как правило, программа декодирует возвращённый объект bytes в строку, как только определит или угадает подходящую кодировку.

В следующем документе спецификации HTML, https://html.spec.whatwg.org/#charset, перечислены различные способы указания информации о кодировке в HTML- или XML-документе.

Дополнительную информацию см. в документе W3C: https://www.w3.org/International/questions/qa-html-encoding-declarations.

Поскольку на сайте python.org используется кодировка utf-8, как указано в его мета-теге, мы будем использовать её же для декодирования байтового объекта:

>>> with urllib.request.urlopen('https://www.python.org/') as f:
...     # Проверить сжатие и декодировать соответствующим образом.
...     enc = f.headers.get('Content-Encoding')
...     data = f.read()
...     if enc == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:100].decode('utf-8', errors='replace'))
...

Тот же результат можно получить и без использования подхода контекстного менеджера:

>>> import urllib.request
>>> f = urllib.request.urlopen('https://www.python.org/')
>>> try:
...     enc = f.headers.get('Content-Encoding')
...     data = f.read()
...     if enc == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:100].decode('utf-8', errors='replace'))
... finally:
...     f.close()

В следующем примере мы отправляем поток данных на стандартный ввод CGI и читаем данные, которые он возвращает. Обратите внимание: этот пример будет работать только в том случае, если установка Python поддерживает SSL.

>>> import urllib.request
>>> req = urllib.request.Request(url='https://localhost/cgi-bin/test.cgi',
...                       data=b'This data is passed to stdin of the CGI')
>>> with urllib.request.urlopen(req) as f:
...     print(f.read().decode('utf-8'))
...
Got Data: "This data is passed to stdin of the CGI"

Код образца CGI, использованного в приведённом выше примере:

#!/usr/bin/env python
import sys
data = sys.stdin.read()
print('Content-type: text/plain\n\nGot Data: "%s"' % data)

Вот пример выполнения запроса PUT с помощью Request:

import urllib.request
DATA = b'some data'
req = urllib.request.Request(url='http://localhost:8080', data=DATA, method='PUT')
with urllib.request.urlopen(req) as f:
    pass
print(f.status)
print(f.reason)

Использование базовой HTTP-аутентификации:

import urllib.request
# Создать OpenerDirector с поддержкой базовой HTTP-аутентификации...
auth_handler = urllib.request.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
                          uri='https://mahler:8092/site-updates.py',
                          user='klem',
                          passwd='kadidd!ehopper')
opener = urllib.request.build_opener(auth_handler)
# ...и установить его глобально, чтобы его можно было использовать с urlopen.
urllib.request.install_opener(opener)
with urllib.request.urlopen('http://www.example.com/login.html') as f:
    print(f.read().decode('utf-8'))

build_opener() предоставляет множество обработчиков по умолчанию, включая ProxyHandler. По умолчанию ProxyHandler использует переменные окружения с именами <scheme>_proxy, где <scheme> – это используемая схема URL. Например, переменная окружения http_proxy читается для получения URL HTTP-прокси.

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

proxy_handler = urllib.request.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib.request.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')

opener = urllib.request.build_opener(proxy_handler, proxy_auth_handler)
# На этот раз, вместо установки OpenerDirector, используется напрямую:
with opener.open('http://www.example.com/login.html') as f:
   print(f.read().decode('utf-8'))

Добавление HTTP-заголовков:

Используйте аргумент headers конструктора Request или:

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'https://www.python.org/')
# Настроить значение заголовка User-Agent по умолчанию:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
with urllib.request.urlopen(req) as f:
    print(f.read().decode('utf-8'))

OpenerDirector автоматически добавляет заголовок User-Agent к каждому запросу Request. Чтобы изменить это:

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
with opener.open('http://www.example.com/') as f:
   print(f.read().decode('utf-8'))

Также помните, что несколько стандартных заголовков (Content-Length, Content-Type и Host) добавляются, когда Request передаётся в urlopen() (или OpenerDirector.open()).

Вот пример сеанса, в котором используется метод GET для получения URL с параметрами:

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "https://www.python.org/?%s" % params
>>> with urllib.request.urlopen(url) as f:
...     print(f.read().decode('utf-8'))
...

В следующем примере вместо этого используется метод POST. Обратите внимание, что вывод параметров из urlencode кодируется в байты перед отправкой в urlopen в качестве данных:

>>> import urllib.request
>>> import urllib.parse
>>> data = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> data = data.encode('ascii')
>>> with urllib.request.urlopen("https://httpbin.org/post", data) as f:
...     print(f.read().decode('utf-8'))
...

В следующем примере используется явно указанный HTTP-прокси, переопределяющий настройки окружения:

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler(proxies))
>>> with opener.open("https://www.python.org") as f:
...     f.read().decode('utf-8')
...

В следующем примере прокси не используются вовсе, переопределяя настройки окружения:

>>> import urllib.request
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
>>> with opener.open("https://www.python.org/") as f:
...     f.read().decode('utf-8')
...

Устаревший интерфейс¶Legacy interface

Следующие функции и классы перенесены из модуля Python 2 urllib (в отличие от urllib2). В будущем они могут стать устаревшими.

urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)¶

Копирует сетевой объект, заданный URL, в локальный файл. Если URL указывает на локальный файл, объект не будет скопирован, если не указан filename. Возвращает кортеж (filename, headers), где filename – это имя локального файла, под которым можно найти объект, а headers – то, что вернул метод info() объекта, возвращённого urlopen() (для удалённого объекта). Исключения те же, что и для urlopen().

Второй аргумент, если присутствует, задаёт местоположение файла для копирования (если отсутствует, местоположением будет временный файл с автоматически сгенерированным именем). Третий аргумент, если присутствует, является вызываемым объектом, который будет вызван один раз при установлении сетевого соединения и один раз после каждого последующего чтения блока. Вызываемый объект будет получать три аргумента: количество переданных блоков на данный момент, размер блока в байтах и общий размер файла. Третий аргумент может быть -1 на старых FTP-серверах, которые не возвращают размер файла в ответ на запрос получения.

Следующий пример иллюстрирует наиболее распространённый сценарий использования:

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('https://python.org/')
>>> html = open(local_filename)
>>> html.close()

Если url использует идентификатор схемы http:, необязательный аргумент data может быть передан для указания запроса POST (обычно тип запроса – GET). Аргумент data должен быть байтовым объектом в стандартном формате application/x-www-form-urlencoded; см. функцию urllib.parse.urlencode().

urlretrieve() вызовет исключение ContentTooShortError, когда обнаружит, что объём доступных данных меньше ожидаемого (который указан в заголовке Content-Length). Это может произойти, например, при прерывании загрузки.

Заголовок Content-Length рассматривается как нижняя граница: если доступно больше данных для чтения, urlretrieve читает больше данных, но если данных меньше, он вызывает исключение.

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

Если заголовок Content-Length не был передан, urlretrieve не может проверить размер загруженных данных и просто возвращает их. В этом случае остаётся только предполагать, что загрузка прошла успешно.

urllib.request.urlcleanup()¶

Очищает временные файлы, которые могли остаться от предыдущих вызовов urlretrieve().

Ограничения urllib.request¶urllib.request Restrictions

• В настоящее время поддерживаются только следующие протоколы: HTTP (версии 0.9 и 1.0), FTP, локальные файлы и data-URL.

  Изменено в версии 3.4: Добавлена поддержка data-URL.

• Функция кэширования urlretrieve() отключена, пока не будет реализована правильная обработка заголовков Expiration time.

• Должна быть функция для проверки, находится ли определённый URL в кэше.

• Для обратной совместимости, если URL указывает на локальный файл, но файл не удаётся открыть, URL интерпретируется заново с использованием протокола FTP. Это иногда может приводить к запутанным сообщениям об ошибках.

• Функции urlopen() и urlretrieve() могут вызывать сколь угодно длительные задержки при ожидании установки сетевого соединения. Это означает, что создать интерактивный веб-клиент с помощью этих функций без использования потоков сложно.

• Данные, возвращаемые urlopen() или urlretrieve(), представляют собой необработанные данные, возвращённые сервером. Это могут быть бинарные данные (например, изображение), обычный текст или, к примеру, HTML. Протокол HTTP передаёт информацию о типе в заголовке ответа, который можно проверить, взглянув на заголовок Content-Type. Если возвращённые данные являются HTML, можно использовать модуль html.parser для его разбора.

• Код, обрабатывающий протокол FTP, не может различить файл и каталог. Это может приводить к неожиданному поведению при попытке чтения URL, указывающего на недоступный файл. Если URL заканчивается на /, считается, что он ссылается на каталог, и обрабатывается соответствующим образом. Но если попытка чтения файла приводит к ошибке 550 (означающей, что URL не найден или недоступен, часто из-за прав доступа), то путь трактуется как каталог, чтобы обработать случай, когда каталог указан URL, но конечный / был опущен. Это может приводить к вводящим в заблуждение результатам при попытке получить файл, недоступный для чтения из-за прав; код FTP попытается прочитать его, получит ошибку 550, а затем выполнит листинг каталога для этого недоступного файла. Если требуется более точный контроль, стоит рассмотреть использование модуля ftplib.