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, игнорируют заголовки; обработчики 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, который можно использовать для открытия URL с другим протоколом или обработки ошибок.

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.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() для каждого protocol, для которого в словаре proxies, переданном конструктору, задан прокси. Метод изменит запросы так, чтобы они проходили через прокси, вызвав request.set_proxy(), а затем вызовет следующий обработчик в цепочке для фактического выполнения протокола.

Объекты HTTPPasswordMgr

Эти методы доступны для объектов 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)

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

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

Объекты 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 — это либо полномочия (например, "python.org"), либо URL, содержащий компонент полномочий (например, "http://python.org/"). В обоих случаях полномочия не должны содержать компонент 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.data.

Объекты HTTPSHandler

HTTPSHandler.https_open(req)

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

Объекты FileHandler

FileHandler.file_open(req)

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

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

Объекты DataHandler

DataHandler.data_open(req)

Прочитать URL данных. URL такого типа содержит данные, закодированные непосредственно в URL. Синтаксис URL данных определён в RFC 2397. Эта реализация игнорирует пробельные символы в URL данных, закодированных в base64, поэтому URL можно переносить в исходном файле, из которого он получен. Однако, хотя некоторые браузеры не возражают против отсутствия завершающего заполнения в URL данных, закодированном в 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().

Примеры

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

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

>>> import urllib.request
>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(300))
...
b'<!doctype html>\n<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->\n<!--[if IE 7]>      <html class="no-js ie7 lt-ie8 lt-ie9">          <![endif]-->\n<!--[if IE 8]>      <html class="no-js ie8 lt-ie9">

Обратите внимание, что 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, указанная в его метатеге, для декодирования объекта bytes мы воспользуемся той же кодировкой:

>>> with urllib.request.urlopen('http://www.python.org/') as f:
...     print(f.read(100).decode('utf-8'))
...
<!doctype html>
<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
<!-

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

>>> import urllib.request
>>> f = urllib.request.urlopen('http://www.python.org/')
>>> try:
...     print(f.read(100).decode('utf-8'))
... finally:
...     f.close()
...
<!doctype html>
<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
<!--

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

>>> 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)
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. Например, для получения 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:
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', 'http://www.python.org/')
# Customize the default User-Agent header value:
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'))

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

Ниже приведён пример сеанса, в котором для получения 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, 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

Переменная, задающая агент пользователя объекта opener. Чтобы 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-адреса данных.

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

• Функция кэширования 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 в соответствии с вашими потребностями.