КАК получить интернет-ресурсы с помощью пакета urllib¶
- Автор:
Введение¶
urllib.request - это модуль Python для получения URL-адресов (Uniform Resource Locators). Он предлагает очень простой интерфейс в виде функции urlopen. Она способна получать URL, используя множество различных протоколов. Она также предлагает несколько более сложный интерфейс для обработки общих ситуаций, таких как базовая аутентификация, cookies, прокси и так далее. Для этого используются объекты, называемые обработчиками и открывателями.
urllib.request поддерживает получение URL для многих «схем URL» (идентифицируемых строкой перед ":" в URL - например, "ftp" является схемой URL для "ftp://python.org/"), используя связанные с ними сетевые протоколы (например, FTP, HTTP). В этом учебнике рассматривается наиболее распространенный случай - HTTP.
Для простых ситуаций urlopen очень прост в использовании. Но как только вы столкнетесь с ошибками или нетривиальными случаями при открытии HTTP URL, вам понадобится некоторое понимание протокола передачи гипертекста. Наиболее полным и авторитетным справочником по HTTP является RFC 2616. Это технический документ, и он не предназначен для легкого чтения. Цель этого HOWTO - проиллюстрировать использование urllib, а также рассказать о HTTP достаточно подробно, чтобы помочь вам. Он не заменяет документацию urllib.request, а является дополнением к ней.
Получение URL-адресов¶
Самый простой способ использования urllib.request заключается в следующем:
import urllib.request
with urllib.request.urlopen('http://python.org/') as response:
html = response.read()
Если вы хотите получить ресурс по URL и сохранить его во временном месте, вы можете сделать это с помощью функций shutil.copyfileobj() и tempfile.NamedTemporaryFile():
import shutil
import tempfile
import urllib.request
with urllib.request.urlopen('http://python.org/') as response:
with tempfile.NamedTemporaryFile(delete=False) as tmp_file:
shutil.copyfileobj(response, tmp_file)
with open(tmp_file.name) as html:
pass
Многие случаи использования urllib будут такими же простыми (обратите внимание, что вместо URL „http:“ мы могли бы использовать URL, начинающийся с „ftp:“, „file:“ и т. д.). Однако цель этого руководства - объяснить более сложные случаи, сосредоточившись на HTTP.
HTTP основан на запросах и ответах - клиент делает запросы, а серверы отправляют ответы. urllib.request отражает это с помощью объекта Request, который представляет HTTP-запрос, который вы делаете. В простейшей форме вы создаете объект Request, который указывает URL, который вы хотите получить. Вызов urlopen с этим объектом Request возвращает объект ответа для запрошенного URL. Этот ответ представляет собой файлоподобный объект, что означает, что вы можете, например, вызвать .read() на ответе:
import urllib.request
req = urllib.request.Request('http://python.org/')
with urllib.request.urlopen(req) as response:
the_page = response.read()
Обратите внимание, что urllib.request использует один и тот же интерфейс Request для работы со всеми схемами URL. Например, вы можете сделать FTP-запрос следующим образом:
req = urllib.request.Request('ftp://example.com/')
В случае с HTTP объекты Request позволяют делать две дополнительные вещи: Во-первых, вы можете передавать данные для отправки на сервер. Во-вторых, вы можете передать серверу дополнительную информацию («метаданные») о данных или о самом запросе - эта информация передается в виде «заголовков» HTTP. Давайте рассмотрим каждый из них по очереди.
Данные¶
Иногда вам нужно отправить данные на URL (часто URL ссылается на CGI (Common Gateway Interface) скрипт или другое веб-приложение). В HTTP это часто делается с помощью так называемого POST-запроса. Именно так часто поступает ваш браузер, когда вы отправляете HTML-форму, заполненную в Интернете. Не все POST-запросы должны исходить от форм: вы можете использовать POST для передачи произвольных данных в ваше собственное приложение. В обычном случае HTML-формы данные должны быть закодированы стандартным способом, а затем переданы в объект Request в качестве аргумента data. Для кодирования используется функция из библиотеки urllib.parse.
import urllib.parse
import urllib.request
url = 'http://www.someserver.com/cgi-bin/register.cgi'
values = {'name' : 'Michael Foord',
'location' : 'Northampton',
'language' : 'Python' }
data = urllib.parse.urlencode(values)
data = data.encode('ascii') # data should be bytes
req = urllib.request.Request(url, data)
with urllib.request.urlopen(req) as response:
the_page = response.read()
Обратите внимание, что иногда требуются другие кодировки (например, для загрузки файлов из HTML-форм - подробнее см. в HTML Specification, Form Submission).
Если вы не передаете аргумент data, urllib использует запрос GET. Разница между GET и POST-запросами заключается в том, что POST-запросы часто имеют «побочные эффекты»: они изменяют состояние системы каким-либо образом (например, размещая на сайте заказ на доставку сотни килограммов консервированного спама к вашей двери). Хотя в стандарте HTTP ясно сказано, что POST-запросы должны всегда вызывать побочные эффекты, а GET-запросы никогда не вызывать побочных эффектов, ничто не мешает GET-запросу иметь побочные эффекты, а POST-запросу - не иметь побочных эффектов. Данные также могут быть переданы в HTTP GET-запросе, закодировав их в самом URL.
Это делается следующим образом:
>>> import urllib.request
>>> import urllib.parse
>>> data = {}
>>> data['name'] = 'Somebody Here'
>>> data['location'] = 'Northampton'
>>> data['language'] = 'Python'
>>> url_values = urllib.parse.urlencode(data)
>>> print(url_values) # The order may differ from below.
name=Somebody+Here&language=Python&location=Northampton
>>> url = 'http://www.example.com/example.cgi'
>>> full_url = url + '?' + url_values
>>> data = urllib.request.urlopen(full_url)
Обратите внимание, что полный URL-адрес создается путем добавления ? к URL-адресу, за которым следуют закодированные значения.
Заголовки¶
Мы рассмотрим один конкретный HTTP-заголовок, чтобы проиллюстрировать, как добавлять заголовки в HTTP-запрос.
Некоторые сайты [1] не любят, когда их просматривают программы, или отправляют разные версии в разные браузеры [2]. По умолчанию urllib идентифицирует себя как Python-urllib/x.y (где x и y - мажорный и минорный номера версии релиза Python, например Python-urllib/2.5), что может запутать сайт или просто не работать. Браузер идентифицирует себя через заголовок User-Agent [3]. Когда вы создаете объект Request, вы можете передать в него словарь заголовков. Следующий пример делает тот же запрос, что и выше, но идентифицирует себя как версию Internet Explorer [4].
import urllib.parse
import urllib.request
url = 'http://www.someserver.com/cgi-bin/register.cgi'
user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'
values = {'name': 'Michael Foord',
'location': 'Northampton',
'language': 'Python' }
headers = {'User-Agent': user_agent}
data = urllib.parse.urlencode(values)
data = data.encode('ascii')
req = urllib.request.Request(url, data, headers)
with urllib.request.urlopen(req) as response:
the_page = response.read()
У ответа также есть два полезных метода. См. раздел о info and geturl, который следует после того, как мы рассмотрим, что происходит, когда что-то идет не так.
Обработка исключений¶
urlopen поднимает URLError, когда не может обработать ответ (хотя, как обычно в Python API, могут быть подняты и встроенные исключения, такие как ValueError, TypeError и т. д.).
HTTPError является подклассом URLError, созданным для конкретного случая HTTP URL.
Классы исключений экспортируются из модуля urllib.error.
URLError¶
Часто ошибка URLError возникает из-за отсутствия сетевого соединения (нет маршрута к указанному серверу) или из-за того, что указанный сервер не существует. В этом случае возникающее исключение будет иметь атрибут „reason“, который представляет собой кортеж, содержащий код ошибки и текстовое сообщение об ошибке.
например
>>> req = urllib.request.Request('http://www.pretend_server.org')
>>> try: urllib.request.urlopen(req)
... except urllib.error.URLError as e:
... print(e.reason)
...
(4, 'getaddrinfo failed')
HTTPError¶
Каждый HTTP-ответ от сервера содержит числовой «код состояния». Иногда код состояния указывает на то, что сервер не может выполнить запрос. Обработчики по умолчанию обработают некоторые из этих ответов за вас (например, если ответ является «перенаправлением», которое просит клиента получить документ с другого URL, urllib обработает это за вас). Для тех, с которыми он не может справиться, urlopen вызовет ошибку HTTPError. Типичные ошибки включают „404“ (страница не найдена), „403“ (запрос запрещен) и „401“ (требуется аутентификация).
Все коды ошибок HTTP описаны в разделе 10 книги RFC 2616.
Поднятый экземпляр HTTPError будет иметь целочисленный атрибут „code“, который соответствует ошибке, отправленной сервером.
Коды ошибок¶
Поскольку обработчики по умолчанию обрабатывают перенаправления (коды в диапазоне 300), а коды в диапазоне 100-299 означают успех, вы обычно будете видеть только коды ошибок в диапазоне 400-599.
http.server.BaseHTTPRequestHandler.responses - это полезный словарь кодов ответов, в котором указаны все коды ответов, используемые RFC 2616. Словарь воспроизводится здесь для удобства
# Table mapping response codes to messages; entries have the
# form {code: (shortmessage, longmessage)}.
responses = {
100: ('Continue', 'Request received, please continue'),
101: ('Switching Protocols',
'Switching to new protocol; obey Upgrade header'),
200: ('OK', 'Request fulfilled, document follows'),
201: ('Created', 'Document created, URL follows'),
202: ('Accepted',
'Request accepted, processing continues off-line'),
203: ('Non-Authoritative Information', 'Request fulfilled from cache'),
204: ('No Content', 'Request fulfilled, nothing follows'),
205: ('Reset Content', 'Clear input form for further input.'),
206: ('Partial Content', 'Partial content follows.'),
300: ('Multiple Choices',
'Object has several resources -- see URI list'),
301: ('Moved Permanently', 'Object moved permanently -- see URI list'),
302: ('Found', 'Object moved temporarily -- see URI list'),
303: ('See Other', 'Object moved -- see Method and URL list'),
304: ('Not Modified',
'Document has not changed since given time'),
305: ('Use Proxy',
'You must use proxy specified in Location to access this '
'resource.'),
307: ('Temporary Redirect',
'Object moved temporarily -- see URI list'),
400: ('Bad Request',
'Bad request syntax or unsupported method'),
401: ('Unauthorized',
'No permission -- see authorization schemes'),
402: ('Payment Required',
'No payment -- see charging schemes'),
403: ('Forbidden',
'Request forbidden -- authorization will not help'),
404: ('Not Found', 'Nothing matches the given URI'),
405: ('Method Not Allowed',
'Specified method is invalid for this server.'),
406: ('Not Acceptable', 'URI not available in preferred format.'),
407: ('Proxy Authentication Required', 'You must authenticate with '
'this proxy before proceeding.'),
408: ('Request Timeout', 'Request timed out; try again later.'),
409: ('Conflict', 'Request conflict.'),
410: ('Gone',
'URI no longer exists and has been permanently removed.'),
411: ('Length Required', 'Client must specify Content-Length.'),
412: ('Precondition Failed', 'Precondition in headers is false.'),
413: ('Request Entity Too Large', 'Entity is too large.'),
414: ('Request-URI Too Long', 'URI is too long.'),
415: ('Unsupported Media Type', 'Entity body in unsupported format.'),
416: ('Requested Range Not Satisfiable',
'Cannot satisfy request range.'),
417: ('Expectation Failed',
'Expect condition could not be satisfied.'),
500: ('Internal Server Error', 'Server got itself in trouble'),
501: ('Not Implemented',
'Server does not support this operation'),
502: ('Bad Gateway', 'Invalid responses from another server/proxy.'),
503: ('Service Unavailable',
'The server cannot process the request due to a high load'),
504: ('Gateway Timeout',
'The gateway server did not receive a timely response'),
505: ('HTTP Version Not Supported', 'Cannot fulfill request.'),
}
При возникновении ошибки сервер возвращает код ошибки HTTP и страницу ошибки. Вы можете использовать экземпляр HTTPError в качестве ответа на возвращаемой странице. Это означает, что, помимо атрибута code, он также имеет методы read, geturl и info, которые возвращаются модулем urllib.response:
>>> req = urllib.request.Request('http://www.python.org/fish.html')
>>> try:
... urllib.request.urlopen(req)
... except urllib.error.HTTPError as e:
... print(e.code)
... print(e.read())
...
404
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
...
<title>Page Not Found</title>\n
...
Завершение¶
Поэтому, если вы хотите быть готовыми к HTTPError или URLError, есть два основных подхода. Я предпочитаю второй подход.
Номер 1¶
from urllib.request import Request, urlopen
from urllib.error import URLError, HTTPError
req = Request(someurl)
try:
response = urlopen(req)
except HTTPError as e:
print('The server couldn\'t fulfill the request.')
print('Error code: ', e.code)
except URLError as e:
print('We failed to reach a server.')
print('Reason: ', e.reason)
else:
# everything is fine
Примечание
except HTTPError должен быть первым, иначе except URLError будет также ловить HTTPError.
Номер 2¶
from urllib.request import Request, urlopen
from urllib.error import URLError
req = Request(someurl)
try:
response = urlopen(req)
except URLError as e:
if hasattr(e, 'reason'):
print('We failed to reach a server.')
print('Reason: ', e.reason)
elif hasattr(e, 'code'):
print('The server couldn\'t fulfill the request.')
print('Error code: ', e.code)
else:
# everything is fine
информация и geturl¶
Ответ, возвращаемый urlopen (или экземпляр HTTPError), имеет два полезных метода info() и geturl() и определяется в модуле urllib.response.
geturl - возвращает реальный URL-адрес найденной страницы. Это полезно, поскольку
urlopen(или используемый объект opener) может следовать за редиректом. URL найденной страницы может не совпадать с запрошенным URL.info - возвращает объект, похожий на словарь, который описывает найденную страницу, в частности заголовки, отправленные сервером. В настоящее время это экземпляр
http.client.HTTPMessage.
Типичные заголовки включают „Content-length“, „Content-type“ и так далее. Полезный список заголовков HTTP с краткими объяснениями их значения и использования см. в Quick Reference to HTTP Headers.
Открыватели и манипуляторы¶
Когда вы получаете URL, вы используете открыватель (экземпляр, возможно, путано названный urllib.request.OpenerDirector). Обычно мы используем открыватель по умолчанию - через urlopen. - но вы можете создавать собственные открыватели. Открыватели используют обработчики. Всю «тяжелую работу» выполняют обработчики. Каждый обработчик знает, как открывать URL для определенной схемы URL (http, ftp и т. д.), или как обрабатывать тот или иной аспект открытия URL, например HTTP-перенаправления или HTTP-куки.
Вы захотите создать открыватели, если вам нужно получить URL с установленными определенными обработчиками, например, чтобы получить открыватель, который обрабатывает cookies, или чтобы получить открыватель, который не обрабатывает перенаправления.
Чтобы создать открывалку, инстанцируйте OpenerDirector, а затем несколько раз вызовите .add_handler(some_handler_instance).
В качестве альтернативы можно использовать build_opener, которая представляет собой удобную функцию для создания объектов-открывателей с помощью одного вызова функции. build_opener добавляет несколько обработчиков по умолчанию, но предоставляет быстрый способ добавить больше и/или переопределить обработчики по умолчанию.
Другие виды обработчиков, которые вам могут понадобиться, могут обрабатывать прокси, аутентификацию и другие распространенные, но немного специализированные ситуации.
С помощью install_opener можно сделать объект opener открывателем (глобальным) по умолчанию. Это означает, что при вызове urlopen будет использоваться установленный вами открыватель.
У объектов Opener есть метод open, который можно вызывать напрямую для получения урлов так же, как и функцию urlopen: нет необходимости вызывать install_opener, кроме как для удобства.
Базовая аутентификация¶
Для иллюстрации создания и установки обработчика мы будем использовать HTTPBasicAuthHandler. Для более подробного обсуждения этой темы - включая объяснение того, как работает базовая аутентификация - смотрите Basic Authentication Tutorial.
Когда требуется аутентификация, сервер отправляет заголовок (а также код ошибки 401) с запросом на аутентификацию. В нем указывается схема аутентификации и «область». Заголовок выглядит следующим образом: WWW-Authenticate: SCHEME realm="REALM".
например.
WWW-Authenticate: Basic realm="cPanel Users"
Затем клиент должен повторить запрос с соответствующими именем и паролем для царства, включенными в заголовок запроса. Это и есть «базовая аутентификация». Чтобы упростить этот процесс, мы можем создать экземпляр HTTPBasicAuthHandler и открыватель для использования этого обработчика.
В HTTPBasicAuthHandler используется объект, называемый менеджером паролей, для сопоставления URL и областей с паролями и именами пользователей. Если вы знаете, что такое царство (из заголовка аутентификации, отправленного сервером), то можно использовать HTTPPasswordMgr. Часто бывает так, что реальность не важна. В этом случае удобно использовать HTTPPasswordMgrWithDefaultRealm. Это позволяет указать имя пользователя и пароль по умолчанию для URL. Они будут заданы в том случае, если вы не укажете альтернативную комбинацию для конкретного царства. Мы указываем это, предоставляя None в качестве аргумента realm для метода add_password.
URL верхнего уровня - это первый URL, требующий аутентификации. URL «глубже», чем URL, который вы передаете в .add_password(), также будет соответствовать.
# create a password manager
password_mgr = urllib.request.HTTPPasswordMgrWithDefaultRealm()
# Add the username and password.
# If we knew the realm, we could use it instead of None.
top_level_url = "http://example.com/foo/"
password_mgr.add_password(None, top_level_url, username, password)
handler = urllib.request.HTTPBasicAuthHandler(password_mgr)
# create "opener" (OpenerDirector instance)
opener = urllib.request.build_opener(handler)
# use the opener to fetch a URL
opener.open(a_url)
# Install the opener.
# Now all calls to urllib.request.urlopen use our opener.
urllib.request.install_opener(opener)
Примечание
В приведенном выше примере мы передали HTTPBasicAuthHandler только в build_opener. По умолчанию открыватели имеют обработчики для обычных ситуаций - ProxyHandler (если задана настройка прокси, например переменная окружения http_proxy), UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler, HTTPRedirectHandler, FTPHandler, FileHandler, DataHandler, HTTPErrorProcessor.
top_level_url на самом деле является либо полным URL (включая компонент схемы „http:“, имя хоста и, опционально, номер порта), например, "http://example.com/" или «авторитет» (т.е. имя хоста, опционально включающее номер порта), например "example.com" или "example.com:8080" (последний пример включает номер порта). Авторитет, если он присутствует, НЕ должен содержать компонент «userinfo» - например, "joe:password@example.com" не является корректным.
Прокси-серверы¶
urllib будет автоматически определять настройки прокси и использовать их. Это происходит через ProxyHandler, который является частью обычной цепочки обработчиков при обнаружении настроек прокси. Обычно это хорошо, но бывают случаи, когда это может быть бесполезно [5]. Один из способов сделать это - настроить собственный ProxyHandler, в котором не определены прокси. Это делается с помощью шагов, аналогичных настройке обработчика Basic Authentication:
>>> proxy_support = urllib.request.ProxyHandler({})
>>> opener = urllib.request.build_opener(proxy_support)
>>> urllib.request.install_opener(opener)
Примечание
В настоящее время urllib.request не поддерживает получение местоположений https через прокси. Однако это можно сделать, расширив urllib.request, как показано в рецепте [6].
Примечание
HTTP_PROXY будет игнорироваться, если задана переменная REQUEST_METHOD; см. документацию по getproxies().
Сокеты и слои¶
Поддержка Python для получения ресурсов из Интернета является многоуровневой. urllib использует библиотеку http.client, которая, в свою очередь, использует библиотеку сокетов.
Начиная с Python 2.3 вы можете указать, как долго сокет должен ждать ответа, прежде чем прервется работа. Это может быть полезно в приложениях, которые должны получать веб-страницы. По умолчанию модуль сокета не имеет таймаута и может зависнуть. В настоящее время таймаут сокета не отображается на уровнях http.client или urllib.request. Однако вы можете установить таймаут по умолчанию глобально для всех сокетов с помощью
import socket
import urllib.request
# timeout in seconds
timeout = 10
socket.setdefaulttimeout(timeout)
# this call to urllib.request.urlopen now uses the default timeout
# we have set in the socket module
req = urllib.request.Request('http://www.voidspace.org.uk')
response = urllib.request.urlopen(req)
Сноски¶
Этот документ был проверен и пересмотрен Джоном Ли.