urllib.request — Расширяемая библиотека для открытия URL-адресов

Объекты Request

Следующие методы описывают публичный интерфейс 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()

Возвращает список кортежей (header_name, header_value) с заголовками Request.

Объекты OpenerDirector

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

OpenerDirector.add_handler(handler)

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

• <protocol>_open() — указывает, что обработчик умеет открывать URL-адреса protocol.

  Дополнительные сведения см. в разделе BaseHandler.<protocol>_open().

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

  Дополнительные сведения см. в разделе BaseHandler.http_error_<nnn>().

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

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

  Дополнительные сведения см. в разделе BaseHandler.<protocol>_request().

• <protocol>_response() — указывает, что обработчик умеет выполнять последующую обработку ответов protocol.

  Дополнительные сведения см. в разделе 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 предоставляют несколько непосредственно полезных методов, а также другие методы, предназначенные для использования производными классами. Эти методы предназначены для непосредственного использования:

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-адреса, для открытия которых не зарегистрирован специальный обработчик.

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

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

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

req будет объектом Request, fp — файловоподобным объектом с телом ошибки HTTP, code — трёхзначным кодом ошибки, msg — видимым пользователю пояснением кода, а hdrs — объектом отображения с заголовками ошибки.

Возвращаемые значения и возбуждаемые исключения должны совпадать с таковыми у 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.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-ответа «перемещено навсегда».

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

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

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

То же, что и http_error_301(), но вызывается для ответа «см. другой ресурс».

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

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

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

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

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

Объекты HTTPCookieProcessor

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

HTTPCookieProcessor.cookiejar

http.cookiejar.CookieJar, в котором хранятся файлы cookie.

Объекты ProxyHandler

ProxyHandler.<protocol>_open(request)

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

Объекты HTTPPasswordMgr

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

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

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

HTTPPasswordMgr.find_user_password(realm, authuri)

Получить имя пользователя и пароль для заданных области и URI, если они есть. Если подходящих имени пользователя и пароля нет, этот метод возвращает (None, None).

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

Объекты HTTPPasswordMgrWithPriorAuth

Этот менеджер паролей расширяет 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.http_error_auth_reqed(authreq, host, req, headers)

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

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

Объекты HTTPBasicAuthHandler

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

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

Объекты ProxyBasicAuthHandler

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

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

Объекты AbstractDigestAuthHandler

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

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

Объекты HTTPDigestAuthHandler

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

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

Объекты ProxyDigestAuthHandler

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

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

Объекты HTTPHandler

HTTPHandler.http_open(req)

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

Объекты HTTPSHandler

HTTPSHandler.https_open(req)

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

Объекты FileHandler

FileHandler.file_open(req)

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

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

Объекты DataHandler

DataHandler.data_open(req)

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

Объекты FTPHandler

FTPHandler.ftp_open(req)

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

Объекты CacheFTPHandler

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

CacheFTPHandler.setTimeout(t)

Задает время ожидания соединений в секундах, равное t.

CacheFTPHandler.setMaxConns(m)

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

Объекты UnknownHandler

UnknownHandler.unknown_open()

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

Объекты HTTPErrorProcessor

HTTPErrorProcessor.http_response(request, response)

Обрабатывает ответы HTTP с ошибками.

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

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

HTTPErrorProcessor.https_response(request, response)

Обрабатывает ответы HTTPS с ошибками.

Поведение такое же, как у http_response().

Примеры

Помимо приведенных ниже примеров, дополнительные примеры доступны в разделе HOWTO: получение интернет-ресурсов с помощью пакета urllib.

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

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
<meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
<title>Python Programming '

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

В следующем документе W3C, https://www.w3.org/International/O-charset, перечислены различные способы указания кодировки в документах (X)HTML и XML.

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

>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

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

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> print(f.read(100).decode('utf-8'))
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtm

В следующем примере мы отправляем поток данных на стандартный ввод 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
# Create an OpenerDirector with support for Basic HTTP Authentication...
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)
# ...and install it globally so it can be used with urlopen.
urllib.request.install_opener(opener)
urllib.request.urlopen('http://www.example.com/login.html')

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

В этом примере стандартный 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)
# This time, rather than install the OpenerDirector, we use it directly:
opener.open('http://www.example.com/login.html')

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

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

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib.request.urlopen(req)

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

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')

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

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

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "http://www.musi-cal.com/cgi-bin/query?%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("http://requestb.in/xrbl82xr", data) as f:
...     print(f.read().decode('utf-8'))
...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

urllib.request.urlcleanup()

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

class urllib.request.URLopener(proxies=None, **x509)

Устарело начиная с версии 3.3.

Базовый класс для открытия и чтения URL. Если вам не требуется поддержка открытия объектов с использованием схем, отличных от http:, ftp: или file:, вероятно, вам следует использовать FancyURLopener.

По умолчанию класс URLopener отправляет заголовок User-Agent со значением urllib/VVV, где VVV — номер версии urllib. Приложения могут задавать собственный заголовок User-Agent, создавая подкласс URLopener или FancyURLopener и задавая атрибут класса version подходящим строковым значением в определении подкласса.

Необязательный параметр proxies должен быть словарем, сопоставляющим имена схем URL-адресам прокси. Пустой словарь полностью отключает прокси. Значение по умолчанию — None; в этом случае, если заданы переменные среды для прокси, они будут использоваться, как описано выше в определении urlopen().

Дополнительные именованные параметры, собранные в x509, можно использовать для аутентификации клиента при использовании схемы https:. Поддерживаются ключевые слова key_file и cert_file, задающие ключ SSL и сертификат; для поддержки аутентификации клиента необходимы оба параметра.

Объекты URLopener вызывают исключение OSError, если сервер возвращает код ошибки.

open(fullurl, data=None)

Открывает fullurl с помощью соответствующего протокола. Этот метод настраивает кэш и сведения о прокси, а затем вызывает соответствующий метод открытия с переданными ему аргументами. Если схема не распознана, вызывается open_unknown(). Аргумент data имеет то же значение, что и аргумент data функции urlopen().

Этот метод всегда экранирует fullurl с помощью quote().

open_unknown(fullurl, data=None)

Переопределяемый интерфейс для открытия URL неизвестных типов.

retrieve(url, filename=None, reporthook=None, data=None)

Получает содержимое url и сохраняет его в filename. Возвращаемое значение — кортеж, состоящий из имени локального файла и либо объекта email.message.Message с заголовками ответа (для удаленных URL), либо None (для локальных URL). Затем вызывающая сторона должна открыть файл filename и прочитать его содержимое. Если filename не задан, а URL указывает на локальный файл, возвращается имя исходного файла. Если URL удаленный и filename не задан, именем файла становится результат вызова tempfile.mktemp() с суффиксом, совпадающим с суффиксом последнего компонента пути входного URL. Если задан reporthook, он должен быть функцией, принимающей три числовых параметра: номер блока, максимальный размер считываемых блоков и общий размер загрузки (-1, если он неизвестен). Функция вызывается один раз в начале, а затем после чтения каждого блока данных из сети. Для локальных URL параметр reporthook игнорируется.

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

version

Переменная, задающая пользовательский агент объекта-открывателя. Чтобы urllib сообщал серверам определенный пользовательский агент, задайте эту переменную как переменную класса в подклассе или в конструкторе до вызова конструктора базового класса.

class urllib.request.FancyURLopener(...)

Устарело начиная с версии 3.3.

FancyURLopener — подкласс URLopener, обеспечивающий обработку по умолчанию для следующих кодов ответа HTTP: 301, 302, 303, 307 и 401. Для перечисленных выше кодов ответа 30x фактический URL запрашивается с использованием заголовка Location. Для кода ответа 401 (требуется аутентификация) выполняется базовая HTTP-аутентификация. Для кодов ответа 30x число перенаправлений ограничено значением атрибута maxtries, равным по умолчанию 10.

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

Примечание

Согласно буквальному толкованию RFC 2616, ответы 301 и 302 на запросы POST нельзя перенаправлять автоматически без подтверждения пользователя. На практике браузеры автоматически перенаправляют такие ответы, заменяя POST на GET, и urllib воспроизводит такое поведение.

Параметры конструктора совпадают с параметрами конструктора URLopener.

Примечание

При выполнении базовой аутентификации экземпляр FancyURLopener вызывает свой метод prompt_user_passwd(). Реализация по умолчанию запрашивает необходимые сведения у пользователя в управляющем терминале. При необходимости подкласс может переопределить этот метод, обеспечив более подходящее поведение.

Класс FancyURLopener предоставляет один дополнительный метод, который следует переопределить для реализации подходящего поведения:

prompt_user_passwd(host, realm)

Возвращает сведения, необходимые для аутентификации пользователя на заданном узле в указанной области безопасности. Возвращаемое значение должно быть кортежем (user, password), который можно использовать для базовой аутентификации.

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

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

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

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

• Функция кэширования urlretrieve() отключена до тех пор, пока кто-нибудь не найдёт время реализовать корректную обработку заголовков времени истечения срока действия.
• Должна быть функция для проверки, находится ли конкретный URL-адрес в кэше.
• Для обратной совместимости, если URL-адрес, по-видимому, указывает на локальный файл, но файл не удаётся открыть, URL-адрес интерпретируется повторно с использованием протокола FTP. Иногда это может приводить к запутанным сообщениям об ошибках.
• Функции urlopen() и urlretrieve() могут вызывать сколь угодно долгие задержки при ожидании установки сетевого соединения. Это означает, что с помощью этих функций сложно создать интерактивный веб-клиент без использования потоков.
• Данные, возвращаемые функцией urlopen() или urlretrieve(), представляют собой необработанные данные, возвращённые сервером. Это могут быть двоичные данные (например, изображение), обычный текст или, например, HTML. Протокол HTTP предоставляет информацию о типе данных в заголовке ответа; её можно посмотреть в заголовке Content-Type. Если возвращённые данные — HTML, для их разбора можно использовать модуль html.parser.
• Код, обрабатывающий протокол FTP, не может различить файл и каталог. Это может привести к неожиданному поведению при попытке прочитать URL-адрес, указывающий на недоступный файл. Если URL-адрес заканчивается на /, предполагается, что он указывает на каталог, и он обрабатывается соответствующим образом. Но если попытка прочитать файл приводит к ошибке 550 (означающей, что URL-адрес не найден или недоступен, часто по причине отсутствия разрешений), путь рассматривается как каталог, чтобы обработать ситуацию, когда URL-адрес указывает на каталог, но завершающий / опущен. Это может привести к вводящим в заблуждение результатам при попытке получить файл, который недоступен для чтения из-за разрешений: код FTP попытается прочитать его, получит ошибку 550, а затем выведет список содержимого каталога для нечитаемого файла. Если требуется детальный контроль, рассмотрите возможность использовать модуль ftplib, создать подкласс FancyURLopener или изменить _urlopener в соответствии с вашими потребностями.