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

Перенаправление на URL Location: или URI: URL. Этот метод вызывается родительским объектом 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(), но вызывается для ответа 'временное перенаправление'.

Объекты 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 из указанных 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.

Абстрактные объекты BasicAuthHandler

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)

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

Абстрактные объекты DigestAuthHandler

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

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

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

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

class urllib.request.FancyURLopener(...)

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

FancyURLopener наследуется от URLopener и предоставляет обработку по умолчанию для следующих кодов ответов HTTP: 301, 302, 303, 307 и 401. Для кодов ответов 30x, перечисленных выше, используется заголовок Location для получения фактического URL. Для кодов ответов 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 для удовлетворения ваших потребностей.