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

Объекты запросов

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

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)

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

Request.get_header(header_name, default=None)

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

Request.header_items()

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

Объекты 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() — означает, что обработчик знает, как обрабатывать ошибки из (не-http) protocol.

• <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().

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

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

Этот метод, если реализован, будет вызван parent OpenerDirector. Значения возврата должны быть такими же, как у 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)

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

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.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)

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

Для объектов HTTPPasswordMgrWithDefaultRealm будет просматриваться realm 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 — это имя заголовка, где информация о realm включается в запрос, 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.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 данных. Этот тип 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().

Примеры

Помимо примеров ниже, дополнительные примеры приведены в HOWTO Fetch Internet Resources Using The urllib Package.

В этом примере запрашивается главная страница 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, как указано в теге meta, мы будем использовать её для декодирования объекта 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

В следующем примере мы отправляем поток данных в 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)

Использование аутентификации Basic 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. Например, переменная окружения 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)
# 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()).

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

>>> 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 кодируются в bytes перед отправкой в 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().

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

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

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://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().

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 с его входными аргументами. Если схема не распознана, вызывается 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, если неизвестно). Она будет вызвана один раз в начале и после каждого блока данных, прочитанных из сети. reporthook игнорируется для локальных URL.

Если 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, перечисленных выше, используется заголовок Location для получения фактического URL. Для кодов ответов 401 (требуется аутентификация) выполняется базовая HTTP-аутентификация. Для кодов ответов 30x рекурсия ограничена значением атрибута маxtries, которое по умолчанию равно 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 для удовлетворения ваших потребностей.