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

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

Следующие методы описывают публичный интерфейс Request, и поэтому все они могут быть переопределены в подклассах. Он также определяет несколько публичных атрибутов, которые могут быть использованы клиентами для проверки разобранного запроса.

Request.full_url

Исходный URL-адрес, переданный конструктору.

Изменено в версии 3.4.

Request.full_url — это свойство с установщиком, получателем и удалителем. Получение full_url возвращает исходный URL-адрес запроса с фрагментом, если он был указан.

Request.type

Схема URI.

Request.host

Авторитет URI, обычно хост, но также может содержать порт, разделенный двоеточием.

Request.origin_req_host

Исходный хост для запроса без порта.

Request.selector

Путь URI. Если Request использует прокси, то selector будет полным URL-адресом, который передается прокси-серверу.

Request.data

Тело сущности для запроса или None если не указано.

Изменено в версии 3.4: Изменение значения Request.data теперь удаляет заголовок «Content-Length», если он был ранее задан или рассчитан.

Request.unverifiable

булево значение, указывающее, является ли запрос недостоверным, как определено в RFC 2965.

Request.method

Метод HTTP-запроса для использования. По умолчанию его значение равно None, что означает, что get_method() выполнит обычное вычисление метода, который будет использоваться. Его значение можно установить (тем самым переопределив стандартное вычисление в get_method()), либо предоставив значение по умолчанию, установив его на уровне класса в подклассе Request, либо передав значение в конструктор Request через аргумент method.

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

Изменено в версии 3.4: Теперь значение по умолчанию можно установить в подклассах; ранее это можно было сделать только через аргумент конструктора.

Request.get_method()

Возвращает строку, обозначающую метод HTTP-запроса. Если Request.method не равно None, возвращает его значение, иначе возвращает 'GET' если Request.data равно None, или 'POST' если нет. Это имеет смысл только для HTTP-запросов.

Изменено в версии 3.3: get_method теперь смотрит на значение Request.method.

Request.add_header(key, val)

Добавляет другой заголовок к запросу. Заголовки в настоящее время игнорируются всеми обработчиками, кроме обработчиков HTTP, где они добавляются в список заголовков, отправляемых на сервер. Обратите внимание, что не может быть более одного заголовка с одинаковым именем, и последующие вызовы перезапишут предыдущие вызовы в случае совпадения ключ. В настоящее время это не приводит к потере функциональности HTTP, поскольку все заголовки, имеющие смысл при использовании более одного раза, имеют (специфичный для заголовка) способ получения той же функциональности, используя только один заголовок. Обратите внимание, что заголовки, добавленные с помощью этого метода, также добавляются к перенаправленным запросам.

Request.add_unredirected_header(key, header)

Добавляет заголовок, который не будет добавлен к перенаправленному запросу.

Request.has_header(header)

Возвращает, имеет ли экземпляр указанный заголовок (проверяет как обычные, так и неперенаправленные).

Request.remove_header(header)

Удаляет указанный заголовок из экземпляра запроса (как из обычных, так и из неперенаправленных заголовков).

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

Request.get_full_url()

Возвращает URL, заданный в конструкторе.

Изменено в версии 3.4.

Возвращает Request.full_url

Request.set_proxy(host, type)

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

Request.get_header(header_name, default=None)

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

Request.header_items()

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

Объекты OpenerDirector

OpenerDirector имеют следующие методы:

OpenerDirector.add_handler(handler)

handler должен быть экземпляром BaseHandler. Ищутся и добавляются в возможные цепочки следующие методы (обратите внимание, что ошибки HTTP — это особый случай). Обратите внимание, что в следующем protocol следует заменить фактическим протоколом, например, http_response() будет обработчиком ответа протокола HTTP. Также type следует заменить фактическим кодом HTTP, например, http_error_404() будет обрабатывать ошибки HTTP 404.

• <protocol>_open() — указывает, что обработчик знает, как открыть URL-адреса протокола protocol.

  Для получения дополнительной информации см. BaseHandler.<protocol>_open().

• http_error_<type>() — указывает, что обработчик знает, как обрабатывать ошибки HTTP с кодом ошибки HTTP type.

  Для получения дополнительной информации см. BaseHandler.http_error_<nnn>().

• <protocol>_error() — указывает, что обработчик знает, как обрабатывать ошибки из (не-http) protocol.

• <protocol>_request() — указывает, что обработчик знает, как предварительно обрабатывать запросы protocol.

  Для получения дополнительной информации см. BaseHandler.<protocol>_request().

• <protocol>_response() — указывает, что обработчик знает, как после обработки отвечать на запросы protocol.

  Для получения дополнительной информации см. BaseHandler.<protocol>_response().

OpenerDirector.open(url, data=None[, timeout])

Открыть указанный url (который может быть объектом запроса или строкой), необязательно передавая заданные data. Аргументы, возвращаемые значения и возникающие исключения такие же, как у urlopen() (который просто вызывает метод open() на текущем установленной глобальной OpenerDirector). Необязательный параметр timeout задает время ожидания в секундах для блокирующих операций, таких как попытка подключения (если не указано, используется глобальное значение по умолчанию для времени ожидания). Функция time out фактически работает только для подключений 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().

Обработчики перенаправлений HTTP

HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)

Возвращает Request или None в ответ на перенаправление. Этот метод вызывается в реализации по умолчанию для методов http_error_30*() при получении от сервера ответа о перенаправлении. Если перенаправление необходимо выполнить, вернуть новый объект Request, чтобы http_error_30*() смог выполнить перенаправление на newurl. В противном случае, поднять исключение HTTPError, если ни один другой обработчик не должен обрабатывать этот URL, или вернуть None, если вы не можете, но другой обработчик может.

Примечание

Реализация данного метода по умолчанию не строго следует RFC 2616, который указывает, что ответы 301 и 302 на запросы POST не должны автоматически перенаправляться без подтверждения от пользователя. На практике браузеры позволяют автоматическое перенаправление таких ответов, изменяя POST на GET, и реализация по умолчанию воспроизводит это поведение.

HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)

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

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(), но вызывается для ответа 'временное перенаправление'.

Обработчики файлов cookie HTTP

HTTPCookieProcessor объекты имеют одно свойство:

HTTPCookieProcessor.cookiejar

Объект http.cookiejar.CookieJar, в котором хранятся файлы cookie.

Обработчики прокси

ProxyHandler.<protocol>_open(request)

Обработчик ProxyHandler будет иметь метод <protocol>_open() для каждого протокола, у которого есть прокси в словаре proxies, переданном в конструктор. Метод будет модифицировать запросы, чтобы они проходили через прокси, вызывая request.set_proxy(), и вызовет следующий обработчик в цепочке для фактического выполнения протокола.

Управление паролями HTTP

Эти методы доступны для объектов HTTPPasswordMgr и HTTPPasswordMgrWithDefaultRealm.

HTTPPasswordMgr.add_password(realm, uri, user, passwd)

uri может быть как одним URI, так и последовательностью URI. realm, user и passwd должны быть строками. Это приводит к использованию (user, passwd) в качестве токенов аутентификации при аутентификации для realm и любого URI, являющегося супер-URI для указанных URI.

HTTPPasswordMgr.find_user_password(realm, authuri)

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

Для объектов HTTPPasswordMgrWithDefaultRealm будет произведён поиск realm None, если для заданного realm нет соответствующего имени пользователя/пароля.

Управление паролями HTTP с предварительной аутентификацией

Этот менеджер паролей расширяет 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.

Абстрактный обработчик аутентификации Basic

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

Обработка запроса на аутентификацию путём получения пары имя пользователя/пароль и повторной отправки запроса. authreq — имя заголовка, содержащего информацию о домене в запросе, host — URL и путь для аутентификации, req — объект (неуспешного) запроса Request, а headers — заголовки ошибки.

host представляет собой либо домен (например, "python.org"), либо URL, содержащий компонент домена (например, "http://python.org/"). В обоих случаях, компонент домена не должен содержать компонент userinfo (так что "python.org" и "python.org:80" допустимы, "joe:password@python.org" — нет).

Обработчик аутентификации Basic HTTP

HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)

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

Обработчик аутентификации Basic прокси

ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)

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

Абстрактный обработчик аутентификации Digest

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

authreq — имя заголовка, содержащего информацию о домене в запросе, host — хост для аутентификации, req — объект (неуспешного) запроса Request, а headers — заголовки ошибки.

Обработчик аутентификации Digest HTTP

HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)

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

Обработчик аутентификации Digest прокси

ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)

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

Объекты HTTPHandler

HTTPHandler.http_open(req)

Отправить HTTP-запрос, который может быть GET или POST, в зависимости от req.has_data().

Объекты HTTPSHandler

HTTPSHandler.https_open(req)

Отправить HTTPS-запрос, который может быть GET или POST, в зависимости от req.has_data().

Объекты FileHandler

FileHandler.file_open(req)

Открыть файл локально, если нет имени хоста или имя хоста — 'localhost'.

Изменено в версии 3.2: Этот метод применим только для локальных имён хостов. Когда задано удалённое имя хоста, генерируется исключение URLError.

Объекты DataHandler

DataHandler.data_open(req)

Прочитать URL данных. Этот тип URL содержит закодированное в самом URL содержимое. Синтаксис URL данных указан в RFC 2397. Данная реализация игнорирует пробелы в кодированных в base64 URL данных, поэтому 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. Обратите внимание, что выходные данные params из 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

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

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 для соответствия вашим потребностям.