> **Источник:** https://python-all.ru/2.6/howto/urllib2.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # HOWTO. Получение интернет-ресурсов с помощью urllib2 | Автор: | [Michael Foord](https://python-all.ru/2.6/howto/urllib2.html) | | --- | --- | > **Примечание** > > Существует французский перевод более ранней версии этого руководства, доступный по адресу [urllib2 - Le Manuel manquant](https://python-all.ru/2.6/howto/urllib2.html). ## Введение Связанные статьи Также может быть полезна следующая статья о получении веб-ресурсов с помощью Python: - [Базовая аутентификация](https://python-all.ru/2.6/howto/urllib2.html) > Учебник по *базовой аутентификации* с примерами на Python. **urllib2** – это модуль [Python](https://python-all.ru/2.6/howto/urllib2.html) для получения URL (Uniform Resource Locators). Он предоставляет очень простой интерфейс в виде функции *urlopen*. Эта функция может получать URL с использованием различных протоколов. Также имеется несколько более сложный интерфейс для обработки типовых ситуаций, таких как базовая аутентификация, куки, прокси и т.д. Эти возможности реализуются с помощью объектов, называемых обработчиками (handlers) и открывателями (openers). urllib2 поддерживает получение URL для многих «схем URL» (определяемых строкой до двоеточия в URL – например, «ftp» – это схема URL «[ftp://python.org/](ftp://python.org/)») с использованием соответствующих сетевых протоколов (например, FTP, HTTP). Это руководство сосредоточено на наиболее распространённом случае – HTTP. For straightforward situations *urlopen* is very easy to use. But as soon as you encounter errors or non-trivial cases when opening HTTP URLs, you will need some understanding of the HyperText Transfer Protocol. The most comprehensive and authoritative reference to HTTP is [**RFC 2616**](https://python-all.ru/2.6/howto/urllib2.html). This is a technical document and not intended to be easy to read. This HOWTO aims to illustrate using *urllib2*, with enough detail about HTTP to help you through. It is not intended to replace the [`urllib2`](https://python-all.ru/2.6/library/urllib2.html#module-urllib2) docs, but is supplementary to them. ## Загрузка URL Самый простой способ использования urllib2 выглядит следующим образом: ```python import urllib2 response = urllib2.urlopen('http://python.org/') html = response.read() ``` Многие варианты использования urllib2 будут такими же простыми (обратите внимание, что вместо URL с «http:» мы могли бы использовать URL, начинающийся с «ftp:», «file:» и т.д.). Однако цель этого руководства – объяснить более сложные случаи, сосредоточившись на HTTP. HTTP основан на запросах и ответах – клиент отправляет запросы, а серверы отправляют ответы. urllib2 отражает это с помощью объекта `Request`, который представляет выполняемый вами HTTP-запрос. В простейшей форме вы создаёте объект Request, указывающий URL, который хотите получить. Вызов `urlopen` с этим объектом Request возвращает объект ответа для запрошенного URL. Этот ответ является файлоподобным объектом, что означает, что вы можете, например, вызвать `.read()` для ответа: ```python import urllib2 req = urllib2.Request('http://www.voidspace.org.uk') response = urllib2.urlopen(req) the_page = response.read() ``` Обратите внимание, что urllib2 использует один и тот же интерфейс Request для обработки всех схем URL. Например, можно выполнить FTP-запрос следующим образом: ```python req = urllib2.Request('ftp://example.com/') ``` В случае HTTP объекты Request позволяют сделать ещё две вещи: во-первых, можно передать данные для отправки на сервер. Во-вторых, можно передать серверу дополнительную информацию («метаданные») *о* данных или о самом запросе – эта информация отправляется в виде HTTP-заголовков. Рассмотрим каждую из них по очереди. ### Данные Иногда нужно отправить данные на URL (часто URL ссылается на CGI-скрипт [\[1\]](https://python-all.ru/2.6/howto/urllib2.html#id9) или другое веб-приложение). В HTTP это часто делается с помощью так называемого **POST**-запроса. Именно это ваш браузер делает, когда вы отправляете HTML-форму, которую заполнили в интернете. Не все POST-запросы должны исходить из форм: вы можете использовать POST для передачи произвольных данных в своё собственное приложение. В типичном случае HTML-форм данные необходимо закодировать стандартным способом, а затем передать объекту Request в качестве аргумента `data`. Кодирование выполняется с помощью функции из библиотеки `urllib`, *а не* из `urllib2`. ```python import urllib import urllib2 url = 'http://www.someserver.com/cgi-bin/register.cgi' values = {'name' : 'Michael Foord', 'location' : 'Northampton', 'language' : 'Python' } data = urllib.urlencode(values) req = urllib2.Request(url, data) response = urllib2.urlopen(req) the_page = response.read() ``` Обратите внимание, что иногда требуются другие кодировки (например, для загрузки файлов из HTML-форм – подробнее см. [Спецификацию HTML, раздел «Отправка формы»](https://python-all.ru/2.6/howto/urllib2.html)). Если не передавать аргумент `data`, urllib2 использует **GET**-запрос. Одно из различий между GET и POST-запросами заключается в том, что POST-запросы часто имеют «побочные эффекты»: они некоторым образом изменяют состояние системы (например, размещая заказ на сайте на доставку к вашей двери центнера консервированного спама). Хотя стандарт HTTP чётко указывает, что POST-запросы *всегда* должны вызывать побочные эффекты, а GET-запросы *никогда* не должны их вызывать, ничто не мешает GET-запросу иметь побочные эффекты, а POST-запросу не иметь их. Данные также могут передаваться в HTTP GET-запросе путём их кодирования в самом URL. Это делается следующим образом: ```python >>> import urllib2 >>> import urllib >>> data = {} >>> data['name'] = 'Somebody Here' >>> data['location'] = 'Northampton' >>> data['language'] = 'Python' >>> url_values = urllib.urlencode(data) >>> print url_values name=Somebody+Here&language=Python&location=Northampton >>> url = 'http://www.example.com/example.cgi' >>> full_url = url + '?' + url_values >>> data = urllib2.open(full_url) ``` Обратите внимание, что полный URL создаётся добавлением `?` к URL, после которого следуют закодированные значения. ### Заголовки Здесь будет рассмотрен один конкретный HTTP-заголовок, чтобы проиллюстрировать, как добавлять заголовки в HTTP-запросы. Некоторые сайты [\[2\]](https://python-all.ru/2.6/howto/urllib2.html#id10) не любят, когда их просматривают программы, или отправляют разные версии разным браузерам [\[3\]](https://python-all.ru/2.6/howto/urllib2.html#id11). По умолчанию urllib2 идентифицирует себя как `Python-urllib/x.y` (где `x` и `y` – это номера старшей и младшей версии выпуска Python, например `Python-urllib/2.5`), что может сбить с толку сайт или просто не сработать. Способ, которым браузер идентифицирует себя, – это заголовок `User-Agent` [\[4\]](https://python-all.ru/2.6/howto/urllib2.html#id12). Когда вы создаёте объект Request, вы можете передать словарь заголовков. Следующий пример делает тот же запрос, что и выше, но идентифицирует себя как версию Internet Explorer [\[5\]](https://python-all.ru/2.6/howto/urllib2.html#id13). ```python import urllib import urllib2 url = 'http://www.someserver.com/cgi-bin/register.cgi' user_agent = 'Mozilla/4.0 (compatible; MSIE 5.5; Windows NT)' values = {'name' : 'Michael Foord', 'location' : 'Northampton', 'language' : 'Python' } headers = { 'User-Agent' : user_agent } data = urllib.urlencode(values) req = urllib2.Request(url, data, headers) response = urllib2.urlopen(req) the_page = response.read() ``` Ответ также имеет два полезных метода. См. раздел [info и geturl](https://python-all.ru/2.6/howto/urllib2.html#info-and-geturl), который следует после того, как мы рассмотрим, что происходит, когда что-то идёт не так. ## Обработка исключений *urlopen* raises `URLError` when it cannot handle a response (though as usual with Python APIs, built-in exceptions such as [`ValueError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.ValueError), [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError) etc. may also be raised). `HTTPError` is the subclass of `URLError` raised in the specific case of HTTP URLs. ### URLError Часто URLError возникает из-за отсутствия сетевого соединения (нет маршрута к указанному серверу) или потому что указанный сервер не существует. В этом случае возбуждённое исключение будет иметь атрибут 'reason', который представляет собой кортеж, содержащий код ошибки и текстовое сообщение об ошибке. например ```python >>> req = urllib2.Request('http://www.pretend_server.org') >>> try: urllib2.urlopen(req) >>> except URLError, e: >>> print e.reason >>> (4, 'getaddrinfo failed') ``` ### HTTPError Каждый HTTP-ответ от сервера содержит числовой «код состояния». Иногда код состояния указывает, что сервер не может выполнить запрос. Стандартные обработчики обработают некоторые из этих ответов за вас (например, если ответ является «перенаправлением», которое просит клиента получить документ по другому URL, urllib2 обработает это за вас). Для тех случаев, которые он не может обработать, urlopen вызовет исключение `HTTPError`. Типичные ошибки включают «404» (страница не найдена), «403» (запрос запрещён) и «401» (требуется аутентификация). Все коды ошибок HTTP перечислены в разделе 10 документа RFC 2616. The `HTTPError` instance raised will have an integer ‘code’ attribute, which corresponds to the error sent by the server. #### Коды ошибок Поскольку обработчики по умолчанию обрабатывают перенаправления (коды в диапазоне 300), а коды в диапазоне 100-299 указывают на успех, вы обычно будете видеть коды ошибок только в диапазоне 400-599. `BaseHTTPServer.BaseHTTPRequestHandler.responses` – это полезный словарь кодов ответов, который показывает все коды ответов, используемые в RFC 2616. Этот словарь приведён здесь для удобства. ```python # Таблица, сопоставляющая коды ответов с сообщениями; записи имеют # вид {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. ```python >>> req = urllib2.Request('http://www.python.org/fish.html') >>> try: >>> urllib2.urlopen(req) >>> except HTTPError, e: >>> print e.code >>> print e.read() >>> 404 Error 404: File Not Found ...... etc... ``` ### Резюме So if you want to be prepared for `HTTPError` *or* `URLError` there are two basic approaches. I prefer the second approach. #### Способ 1 ```python from urllib2 import Request, urlopen, URLError, HTTPError req = Request(someurl) try: response = urlopen(req) except HTTPError, e: print 'The server couldn\'t fulfill the request.' print 'Error code: ', e.code except URLError, e: print 'We failed to reach a server.' print 'Reason: ', e.reason else: # everything is fine ``` > **Примечание** > > The `except HTTPError` *must* come first, otherwise `except URLError` will *also* catch an `HTTPError`. #### Способ 2 ```python from urllib2 import Request, urlopen, URLError req = Request(someurl) try: response = urlopen(req) except URLError, 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 ``` ## info и geturl Ответ, возвращаемый urlopen (или экземпляр `HTTPError`), имеет два полезных метода: `info()` и `geturl()`. **geturl** - this returns the real URL of the page fetched. This is useful because `urlopen` (or the opener object used) may have followed a redirect. The URL of the page fetched may not be the same as the URL requested. **info** – возвращает объект, подобный словарю, который описывает полученную страницу, в частности заголовки, отправленные сервером. В настоящее время это экземпляр `httplib.HTTPMessage`. Типичные заголовки включают ‘Content-length’, ‘Content-type’ и т.д. Смотрите [Краткий справочник HTTP-заголовков](https://python-all.ru/2.6/howto/urllib2.html) для полезного списка HTTP-заголовков с краткими пояснениями их значения и использования. ## Открыватели и обработчики Когда вы получаете URL, вы используете opener (экземпляр, возможно, сбивающе названного [`urllib2.OpenerDirector`](https://python-all.ru/2.6/library/urllib2.html#urllib2.OpenerDirector)). Обычно мы использовали opener по умолчанию – через `urlopen` – но вы можете создавать собственные openers. Openers используют обработчики. Всю «тяжёлую работу» выполняют обработчики. Каждый обработчик знает, как открывать URL для определённой схемы URL (http, ftp и т.д.) или как обрабатывать определённый аспект открытия URL, например HTTP-перенаправления или HTTP-куки. Стоит создавать собственные opener'ы, если нужно получать URL с установленными определёнными обработчиками, например чтобы получить opener, обрабатывающий cookies, или opener, не обрабатывающий перенаправления. To create an opener, instantiate an `OpenerDirector`, and then call `.add_handler(some_handler_instance)` repeatedly. Alternatively, you can use `build_opener`, which is a convenience function for creating opener objects with a single function call. `build_opener` adds several handlers by default, but provides a quick way to add more and/or override the default handlers. Другие типы обработчиков могут обрабатывать прокси, аутентификацию и другие распространённые, но слегка специализированные ситуации. `install_opener` can be used to make an `opener` object the (global) default opener. This means that calls to `urlopen` will use the opener you have installed. Opener objects have an `open` method, which can be called directly to fetch urls in the same way as the `urlopen` function: there’s no need to call `install_opener`, except as a convenience. ## Базовая аутентификация To illustrate creating and installing a handler we will use the `HTTPBasicAuthHandler`. For a more detailed discussion of this subject – including an explanation of how Basic Authentication works - see the [Basic Authentication Tutorial](https://python-all.ru/2.6/howto/urllib2.html). Когда требуется аутентификация, сервер отправляет заголовок (а также код ошибки 401), запрашивающий аутентификацию. В нём указывается схема аутентификации и «realm» (область). Заголовок выглядит так: `Www-authenticate: SCHEME realm="REALM"`. например ```python Www-authenticate: Basic realm="cPanel Users" ``` Затем клиент должен повторить запрос, указав соответствующие имя и пароль для области (realm) в качестве заголовка запроса. Это называется «базовая аутентификация». Чтобы упростить этот процесс, можно создать экземпляр `HTTPBasicAuthHandler` и opener для использования этого обработчика. `HTTPBasicAuthHandler` использует объект, называемый менеджером паролей, для управления сопоставлением URL и областей (realm) с паролями и именами пользователей. Если известно, что представляет собой область (из заголовка аутентификации, отправленного сервером), то можно использовать `HTTPPasswordMgr`. Часто область не имеет значения. В таком случае удобно использовать `HTTPPasswordMgrWithDefaultRealm`. Это позволяет указать имя пользователя и пароль по умолчанию для URL. Они будут использоваться при отсутствии альтернативной комбинации для конкретной области. Для этого нужно передать `None` в качестве аргумента realm методу `add_password`. URL верхнего уровня – это первый URL, требующий аутентификации. URL «глубже», чем переданный в .add\_password(), также будут соответствовать. ```python # создать менеджер паролей password_mgr = urllib2.HTTPPasswordMgrWithDefaultRealm() # Добавить имя пользователя и пароль. # Если бы мы знали realm, мы могли бы использовать его вместо None. top_level_url = "http://example.com/foo/" password_mgr.add_password(None, top_level_url, username, password) handler = urllib2.HTTPBasicAuthHandler(password_mgr) # создать "opener" (экземпляр OpenerDirector) opener = urllib2.build_opener(handler) # использовать opener для получения URL opener.open(a_url) # Установить opener. # Теперь все вызовы urllib2.urlopen используют наш opener. urllib2.install_opener(opener) ``` > **Примечание** > > В приведенном выше примере мы передали только `HTTPBasicAuthHandler` в `build_opener`. По умолчанию открыватели содержат обработчики для обычных ситуаций: `ProxyHandler`, `UnknownHandler`, `HTTPHandler`, `HTTPDefaultErrorHandler`, `HTTPRedirectHandler`, `FTPHandler`, `FileHandler`, `HTTPErrorProcessor`. `top_level_url` на самом деле *может быть* полным URL (включая схему 'http:' и имя хоста, а также, опционально, номер порта), например, “[http://example.com/](https://python-all.ru/2.6/howto/urllib2.html)” *или* «authority» (т.е. имя хоста, опционально включая номер порта), например, “example.com” или “example.com:8080” (последний пример включает номер порта). Authority, если присутствует, не должен содержать компонент «userinfo» – например, “joe@password:example.com” неверен. ## Прокси **urllib2** автоматически определяет ваши настройки прокси и использует их. Это осуществляется через `ProxyHandler`, который является частью стандартной цепочки обработчиков. Обычно это хорошо, но бывают случаи, когда это может быть не полезно [\[6\]](https://python-all.ru/2.6/howto/urllib2.html#id14). Один из способов сделать это – настроить собственный `ProxyHandler` без определённых прокси. Это делается с помощью шагов, аналогичных настройке обработчика [Basic Authentication](https://python-all.ru/2.6/howto/urllib2.html): ```python >>> proxy_support = urllib2.ProxyHandler({}) >>> opener = urllib2.build_opener(proxy_support) >>> urllib2.install_opener(opener) ``` > **Примечание** > > В настоящее время `urllib2` *не поддерживает* получение `https`-адресов через прокси. Однако это можно включить, расширив urllib2, как показано в рецепте [\[7\]](https://python-all.ru/2.6/howto/urllib2.html#id15). ## Сокеты и уровни Поддержка Python для получения ресурсов из Интернета является многоуровневой. urllib2 использует библиотеку httplib, которая, в свою очередь, использует библиотеку socket. Начиная с Python 2.3 можно указать, как долго сокет должен ждать ответа до истечения времени ожидания. Это может быть полезно в приложениях, которым необходимо получать веб-страницы. По умолчанию модуль socket *не имеет тайм-аута* и может зависнуть. В настоящее время тайм-аут сокета не раскрыт на уровнях httplib или urllib2. Однако можно глобально задать тайм-аут по умолчанию для всех сокетов с помощью ```python import socket import urllib2 # тайм-аут в секундах timeout = 10 socket.setdefaulttimeout(timeout) # этот вызов urllib2.urlopen теперь использует таймаут по умолчанию # который мы установили в модуле socket req = urllib2.Request('http://www.voidspace.org.uk') response = urllib2.urlopen(req) ``` --- ## Примечания Этот документ был проверен и доработан Джоном Ли. | [\[1\]](https://python-all.ru/2.6/howto/urllib2.html#id1) | Введение в протокол CGI см. в [Writing Web Applications in Python](https://python-all.ru/2.6/howto/urllib2.html). | | --- | --- | | [\[2\]](https://python-all.ru/2.6/howto/urllib2.html#id2) | Например, Google. *Правильный* способ использовать Google из программы – это, конечно, использовать [PyGoogle](https://python-all.ru/2.6/howto/urllib2.html). См. [Voidspace Google](https://python-all.ru/2.6/howto/urllib2.html) для примеров использования Google API. | | --- | --- | | [\[3\]](https://python-all.ru/2.6/howto/urllib2.html#id3) | Определение браузера (browser sniffing) – очень плохая практика при проектировании веб-сайтов; гораздо разумнее создавать сайты с использованием веб-стандартов. К сожалению, многие сайты до сих пор отправляют разные версии разным браузерам. | | --- | --- | | [\[4\]](https://python-all.ru/2.6/howto/urllib2.html#id4) | Пользовательский агент для MSIE 6 – *'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)'* | | --- | --- | | [\[5\]](https://python-all.ru/2.6/howto/urllib2.html#id5) | Подробнее о HTTP-заголовках запросов см. [Quick Reference to HTTP Headers](https://python-all.ru/2.6/howto/urllib2.html). | | --- | --- | | [\[6\]](https://python-all.ru/2.6/howto/urllib2.html#id7) | В моём случае для доступа в интернет на работе приходится использовать прокси. При попытке получить URL-адреса *localhost* через этот прокси они блокируются. Браузер Internet Explorer настроен на использование прокси, и urllib2 использует эту настройку. Чтобы тестировать скрипты с локальным сервером, приходится запрещать urllib2 использовать прокси. | | --- | --- | | [\[7\]](https://python-all.ru/2.6/howto/urllib2.html#id8) | Открыватель urllib2 для SSL-прокси (метод CONNECT): [ASPN Cookbook Recipe](https://python-all.ru/2.6/howto/urllib2.html). | | --- | --- |