urllib — Открытие произвольных ресурсов по URL

Этот модуль предоставляет высокоуровневый интерфейс для получения данных через Всемирную паутину. В частности, функция urlopen() похожа на встроенную функцию open(), но принимает универсальные идентификаторы ресурсов (URL) вместо имён файлов. Применяются некоторые ограничения — она может открывать URL только для чтения, и операции поиска недоступны.

1. Высокоуровневый интерфейс

urllib.urlopen(url[, data[, proxies[, context]]])

Открывает сетевой объект, обозначенный URL, для чтения. Если у URL нет идентификатора схемы или он имеет идентификатор схемы file:, это открывает локальный файл (без универсальных новых строк); в противном случае открывает сокет к серверу где-то в сети. Если подключение не может быть установлено, возбуждается исключение IOError. Если всё прошло успешно, возвращается файлоподобный объект. Он поддерживает следующие методы: read(), readline(), readlines(), fileno(), close(), info(), getcode() и geturl(). Он также поддерживает протокол итератора. Одно замечание: метод read(), если аргумент size опущен или отрицателен, может не читать до конца потока данных; нет хорошего способа определить, что весь поток из сокета был прочитан в общем случае.

За исключением методов info(), getcode() и geturl(), эти методы имеют тот же интерфейс, что и для объектов файлов — см. раздел Объекты файлов в этом руководстве. (Однако, это не встроенный объект файла, поэтому его нельзя использовать в тех немногих местах, где требуется настоящий встроенный объект файла.)

Метод info() возвращает экземпляр класса mimetools.Message, содержащий метаинформацию, связанную с URL. Когда метод HTTP, эти заголовки — те, которые возвращены сервером в начале полученной HTML-страницы (включая Content-Length и Content-Type). Когда метод FTP, заголовок Content-Length будет присутствовать, если (как обычно) сервер вернул длину файла в ответ на запрос на получение файла по FTP. Заголовок Content-Type будет присутствовать, если тип MIME можно угадать. При локальном файле возвращаемые заголовки будут включать Date, представляющий время последнего изменения файла, Content-Length, задающий размер файла, и Content-Type, содержащий догадку о типе файла. См. также описание модуля mimetools.

Метод geturl() возвращает фактический URL страницы. В некоторых случаях HTTP-сервер перенаправляет клиента на другой URL. Функция urlopen() обрабатывает это прозрачно, но в некоторых случаях вызывающему коду нужно знать, на какой URL был перенаправлен клиент. Метод geturl() может использоваться для получения этого перенаправленного URL.

Метод getcode() возвращает HTTP-код состояния, который был отправлен вместе с ответом, или None, если URL не является HTTP-URL.

Если url использует идентификатор схемы http:, необязательный аргумент data может быть передан для указания запроса POST (обычно тип запроса GET). Аргумент data должен быть в стандартном формате application/x-www-form-urlencoded; см. функцию urlencode() ниже.

Функция urlopen() прозрачно работает с прокси, не требующими аутентификации. В среде Unix или Windows установите переменные окружения http_proxy, или ftp_proxy на URL, который идентифицирует прокси-сервер, перед запуском интерпретатора Python. Например ('%' - командная строка):

% http_proxy="http://www.someproxy.com:3128"
% export http_proxy
% python
...

Переменная окружения no_proxy может использоваться для указания хостов, которые не должны достигаться через прокси; если она установлена, она должна содержать список хостов, разделенных запятыми, необязательно с добавленным :port, например cern.ch,ncsa.uiuc.edu,some.host:8080.

В среде Windows, если переменные окружения прокси не установлены, настройки прокси получаются из раздела Internet Settings в реестре.

В среде Mac OS X, urlopen() будет извлекать информацию о прокси из фреймворка конфигурации системы OS X, который может управляться с помощью панели «Настройки системы сети».

В качестве альтернативы, необязательный аргумент proxies может быть использован для явного указания прокси. Он должен быть словарем, сопоставляющим имена схем с URL-адресами прокси, где пустой словарь не использует прокси, а None (значение по умолчанию) использует настройки прокси из среды, как обсуждалось выше. Например:

# Use http://www.someproxy.com:3128 for HTTP proxying
proxies = {'http': 'http://www.someproxy.com:3128'}
filehandle = urllib.urlopen(some_url, proxies=proxies)
# Don't use any proxies
filehandle = urllib.urlopen(some_url, proxies={})
# Use proxies from environment - both versions are equivalent
filehandle = urllib.urlopen(some_url, proxies=None)
filehandle = urllib.urlopen(some_url)

Прокси, требующие аутентификации для использования, в настоящее время не поддерживаются; это считается ограничением реализации.

Параметр context может быть установлен на экземпляр ssl.SSLContext для настройки параметров SSL, которые используются, если urlopen() устанавливает HTTPS-соединение.

Изменено в версии 2.3: Добавлена поддержка proxies.

Изменено в версии 2.6: Добавлен getcode() к возвращаемому объекту и поддержка переменной окружения no_proxy.

Изменено в версии 2.7.9: Добавлен параметр context. Все необходимые проверки сертификатов и имени хоста выполняются по умолчанию.

Устарело начиная с версии 2.6: Функция urlopen() была удалена в Python 3 в пользу urllib2.urlopen().

urllib.urlretrieve(url[, filename[, reporthook[, data[, context]]]])

Копирует сетевой объект, обозначенный URL, в локальный файл, если необходимо. Если URL указывает на локальный файл или существует действительная кэшированная копия объекта, объект не копируется. Возвращает кортеж (filename, headers) , где filename — имя локального файла, в котором можно найти объект, а headers — то, что вернул метод info() объекта, возвращаемого urlopen() (для удалённого объекта, возможно, кэшированного). Исключение аналогичны тем, что у urlopen().

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

Если url использует идентификатор схемы http:, необязательный аргумент data может быть задан для указания запроса POST (обычно тип запроса GET). Аргумент data должен быть в стандартном формате application/x-www-form-urlencoded; см. функцию urlencode() ниже.

Параметр context может быть установлен на экземпляр ssl.SSLContext для настройки настроек SSL, которые используются, если urlretrieve() устанавливает соединение HTTPS.

Изменено в версии 2.5: urlretrieve() будет поднимать ContentTooShortError, когда обнаружит, что количество доступных данных меньше ожидаемого количества (которое является размером, указанным в заголовке Content-Length). Это может произойти, например, при прерывании загрузки.

Content-Length рассматривается как нижняя граница: если есть больше данных для чтения, urlretrieve() прочитает больше данных, но если данных меньше, то поднимет исключение.

В этом случае вы все ещё можете получить загруженные данные, они хранятся в атрибуте content экземпляра исключения.

Если заголовок Content-Length не был предоставлен, urlretrieve() не может проверить размер загруженных данных и просто возвращает их. В этом случае вы должны предположить, что загрузка прошла успешно.

Изменено в версии 2.7.9: Добавлен параметр context. Все необходимые проверки сертификатов и имён хостов выполняются по умолчанию.

urllib._urlopener

Общедоступные функции urlopen() и urlretrieve() создают экземпляр класса FancyURLopener и используют его для выполнения запрошенных действий. Чтобы переопределить это функциональность, программисты могут создать подкласс URLopener или FancyURLopener, а затем присвоить экземпляр этого класса переменной urllib._urlopener перед вызовом нужной функции. Например, приложения могут захотеть указать другой заголовок User-Agent, чем определён в URLopener. Это можно сделать с помощью следующего кода:

import urllib

class AppURLopener(urllib.FancyURLopener):
    version = "App/1.7"

urllib._urlopener = AppURLopener()

urllib.urlcleanup()

Очистить кэш, который мог быть создан предыдущими вызовами urlretrieve().

2. Функции-утилиты

urllib.quote(string[, safe])

Заменить специальные символы в строке с помощью кодирования %xx. Буквы, цифры и символы '_.-' никогда не кодируются. По умолчанию эта функция предназначена для кодирования части пути URL. Необязательный параметр safe определяет дополнительные символы, которые не должны кодироваться — его значение по умолчанию '/'.

Пример: quote('/~connolly/') возвращает '/%7econnolly/'.

urllib.quote_plus(string[, safe])

Подобно quote(), но также заменяет пробелы знаком «плюс», как требуется для кодирования значений HTML-формы при построении строки запроса для включения в URL. Знаки «плюс» в исходной строке кодируются, если они не включены в safe. Также у него нет значения safe по умолчанию '/'.

urllib.unquote(string)

Заменить %xx кодирования их односимвольными эквивалентами.

Пример: unquote('/%7Econnolly/') возвращает '/~connolly/'.

urllib.unquote_plus(string)

Подобно unquote(), но также заменяет знаки «плюс» пробелами, как требуется для декодирования значений HTML-форм.

urllib.urlencode(query[, doseq])

Преобразовать объект отображения или последовательность пар «ключ-значение» в строку «процентно-кодированную» строку, подходящую для передачи в urlopen() в качестве необязательного аргумента data. Это полезно для передачи словаря полей формы в запрос POST. Полученная строка представляет собой ряд пар «ключ-значение» разделенных символами key=value, где и ключ и значение закодированы с помощью quote_plus() выше. Когда в качестве аргумента query используется последовательность пар «ключ-значение», первый элемент каждой пары — это ключ, а второй — значение. Элемент значения может быть последовательностью, и в этом случае, если необязательный параметр doseq равен True, для каждого элемента последовательности значений ключа генерируются отдельные пары «ключ-значение», разделённые символами '&'. Порядок параметров в закодированной строке будет соответствовать порядку пар параметров в последовательности. Модуль urlparse предоставляет функции parse_qs() и parse_qsl(), которые используются для разбора строк запроса в структуры данных Python.

urllib.pathname2url(path)

Преобразуйте путь path из локального синтаксиса для пути в форму, используемую в компоненте пути URL. Это не генерирует полный URL. Возвращаемое значение уже будет закодировано с использованием функции quote().

urllib.url2pathname(path)

Преобразовать компонент пути path из процентно-кодированного URL в локальный синтаксис пути. Эта функция не принимает полный URL. Эта функция использует unquote() для декодирования path.

urllib.getproxies()

Эта вспомогательная функция возвращает словарь сопоставлений схемы к URL-адресам прокси-серверов. Она сканирует среду на наличие переменных с именами <scheme>_proxy, в регистронезависимом режиме, для всех операционных систем в первую очередь, и когда она не находит, ищет информацию о прокси из Mac OSX System Configuration для Mac OS X и реестра систем Windows для Windows. Если существуют переменные среды и в нижнем регистре, и в верхнем регистре (и они не совпадают), используется переменная в нижнем регистре.

Примечание

Если переменная среды REQUEST_METHOD установлена, что обычно указывает, что ваш скрипт работает в среде CGI, переменная среды HTTP_PROXY (в верхнем регистре _PROXY) будет проигнорирована. Это потому, что эта переменная может быть внедрена клиентом с использованием HTTP-заголовка «Proxy:». Если вам нужно использовать HTTP-прокси в среде CGI, либо явно укажите ProxyHandler, либо убедитесь, что имя переменной находится в нижнем регистре (или, по крайней мере, суффикс _proxy).

3. Объекты открывателей URL

class urllib.URLopener([proxies[, context[, **x509]]])

Базовый класс для открытия и чтения URL-адресов. Если вам не нужно поддерживать открытие объектов с использованием схем, отличных от http:, ftp:, или file:, вы, вероятно, захотите использовать FancyURLopener.

По умолчанию класс URLopener отправляет заголовок User-Agent со значением urllib/VVV, где VVV — номер версии urllib. Приложения могут определять свой собственный заголовок User-Agent, наследуя от класса URLopener или FancyURLopener и устанавливая атрибут класса version в соответствующее строковое значение в определении подкласса.

Необязательный параметр proxies должен быть словарем, сопоставляющим имена схем с URL-адресами прокси-серверов, где пустой словарь полностью отключает прокси. Его значение по умолчанию — None, в этом случае будут использоваться системные настройки прокси, если они заданы, как описано в определении urlopen() выше.

Параметр context может быть экземпляром ssl.SSLContext. Если он задан, он определяет настройки SSL, которые используется открывателем для установления HTTPS-соединений.

Дополнительные ключевые параметры, собранные в x509, могут использоваться для аутентификации клиента при использовании схемы https:. Поддерживаются ключевые слова key_file и cert_file для предоставления SSL-ключа и сертификата; оба необходимы для поддержки аутентификации клиента.

Объекты URLopener будут генерировать исключение IOError, если сервер вернёт код ошибки.

Изменено в версии 2.7.9: Добавлен параметр context. Все необходимые проверки сертификата и имени хоста выполняются по умолчанию.

open(fullurl[, data])

Открывает fullurl с использованием соответствующего протокола. Этот метод устанавливает информацию о кэше и прокси, а затем вызывает соответствующий метод open со своими входными аргументами. Если схема не распознаётся, вызывается open_unknown(). Аргумент data имеет то же значение, что и аргумент data в urlopen().

open_unknown(fullurl[, data])

Переопределяемый интерфейс для открытия неизвестных типов URL.

retrieve(url[, filename[, reporthook[, data]]])

Извлекает содержимое url и помещает его в filename. Возвращаемое значение — кортеж, состоящий из локального имени файла и либо объекта mimetools.Message, содержащего заголовки ответа (для удалённых URL), либо None (для локальных URL). Затем вызывающая сторона должна открыть и прочитать содержимое filename. Если filename не задан и URL ссылается на локальный файл, возвращается имя входного файла. Если URL не локальный и filename не задан, имя файла — результат работы tempfile.mktemp() с суффиксом, соответствующим суффиксу последнего компонента пути входного URL. Если задан reporthook, он должен быть функцией, принимающей три числовых параметра. Она будет вызываться после чтения каждого блока данных из сети. reporthook игнорируется для локальных URL.

Если url использует идентификатор схемы http:, необязательный аргумент data может быть задан для указания запроса POST (обычно тип запроса — GET). Аргумент data должен быть в стандартном формате application/x-www-form-urlencoded; см. функцию urlencode() ниже.

version

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

class urllib.FancyURLopener(...)

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

Реализация запрашивает эту информацию в терминале; приложение должно переопределить этот метод, чтобы использовать соответствующую модель взаимодействия в локальной среде.

exception urllib.ContentTooShortError(msg[, content])

Это исключение возникает, когда функция urlretrieve() обнаруживает, что объём загруженных данных меньше ожидаемого объёма (заданного заголовком Content-Length). Атрибут content хранит загруженные (и предположительно усечённые) данные.

Добавлено в версии 2.5.

4. Ограничения urllib

• В настоящее время поддерживаются только следующие протоколы: HTTP (версии 0.9 и 1.0), FTP и локальные файлы.
• Функция кеширования urlretrieve() отключена до тех пор, пока не будет реализована надлежащая обработка заголовков времени истечения срока действия.
• Должна быть функция для запроса о том, находится ли определенный URL-адрес в кэше.
• Для обратной совместимости, если URL-адрес, по-видимому, указывает на локальный файл, но файл не может быть открыт, URL-адрес повторно интерпретируется с использованием протокола FTP. Это иногда может приводить к запутанным сообщениям об ошибках.
• Функции urlopen() и urlretrieve() могут вызывать произвольно большие задержки при ожидании подключения к сети. Это означает, что сложно создать интерактивный веб-клиент, используя эти функции без использования потоков.
• Данные, возвращаемые urlopen() или urlretrieve(), представляют собой исходные данные, возвращенные сервером. Это могут быть двоичные данные (например, изображение), обычный текст или (например) HTML. Протокол HTTP предоставляет информацию о типе в заголовке ответа, которую можно проверить, просмотрев заголовок Content-Type. Если возвращаемые данные являются HTML, вы можете использовать модуль htmllib для их разбора.
• Код, обрабатывающий протокол FTP, не может различать файл и директорию. Это может привести к неожиданному поведению при попытке чтения URL-адреса, указывающего на файл, который недоступен. Если URL-адрес заканчивается на /, предполагается, что он относится к каталогу, и он будет обработан соответствующим образом. Но если попытка чтения файла приводит к ошибке 550 (что означает, что URL-адрес не найден или недоступен, часто по причинам разрешения доступа), то путь рассматривается как каталог для обработки случая, когда каталог указан URL-адресом, но заключительный / опущен. Это может привести к вводящим в заблуждение результатам, когда вы пытаетесь получить файл, чтение которого запрещено; код FTP попытается прочитать его, потерпит неудачу с ошибкой 550, а затем выполнит список каталогов для недоступного файла. Если требуется точный контроль, рассмотрите возможность использования модуля ftplib, наследования класса FancyURLopener или изменения _urlopener для соответствия вашим потребностям.
• Этот модуль не поддерживает использование прокси, требующих аутентификации. Это может быть реализовано в будущем.
• Хотя модуль urllib содержит (недокументированные) процедуры для разбора и разбора строк URL-адресов, рекомендуемый интерфейс для работы с URL-адресами находится в модуле urlparse.

5. Примеры

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

>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
>>> print f.read()

В следующем примере используется метод POST:

>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
>>> print f.read()

В следующем примере используется явно указанный HTTP-прокси, перезаписывающий настройки среды:

>>> import urllib
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.FancyURLopener(proxies)
>>> f = opener.open("http://www.python.org")
>>> f.read()

В следующем примере вообще не используются прокси, перезаписывающие настройки среды:

>>> import urllib
>>> opener = urllib.FancyURLopener({})
>>> f = opener.open("http://www.python.org/")
>>> f.read()