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 задает таймаут в секундах для блокирующих операций, таких как попытка подключения (если не указано, будет использоваться глобальное значение по умолчанию для таймаута). Функция таймаута фактически работает только для подключений HTTP, HTTPS и FTP.

OpenerDirector.error(proto, *args)

Обработать ошибку данного протокола. Это вызовет зарегистрированные обработчики ошибок для данного протокола с заданными аргументами (которые специфичны для протокола). Протокол HTTP — это особый случай, который использует код ответа HTTP для определения конкретного обработчика ошибок; см. методы http_error_<type>() классов обработчиков.

Возвращаемые значения и возникающие исключения аналогичны тем, что у urlopen().

Объекты OpenerDirector открывают URL-адреса в три этапа:

Порядок вызова этих методов в каждом этапе определяется сортировкой экземпляров обработчиков.

1. Каждый обработчик с методом, подобным <protocol>_request(), вызывает этот метод для предварительной обработки запроса.

2. Обработчики с методом, подобным <protocol>_open(), вызываются для обработки запроса. Этот этап завершается, когда обработчик либо возвращает значение, отличное от None (т. е. ответ), либо вызывает исключение (обычно URLError). Исключения разрешается распространять.

   Фактически, вышеуказанный алгоритм сначала используется для методов, подобных default_open(). Если все такие методы возвращают None, алгоритм повторяется для методов, подобных <protocol>_open(). Если все такие методы возвращают None, алгоритм повторяется для методов, подобных unknown_open().

   Обратите внимание, что реализация этих методов может включать вызовы метода родительского экземпляра OpenerDirector open() и error().

3. Каждый обработчик с методом, подобным <protocol>_response(), вызывает этот метод для последующей обработки ответа.

Объекты BaseHandler

BaseHandler предоставляют несколько методов, которые непосредственно полезны, и другие, предназначенные для использования производными классами. Эти предназначены для прямого использования:

BaseHandler.add_parent(director)

Добавить директора в качестве родителя.

BaseHandler.close()

Удалить всех родителей.

Следующие атрибуты и методы должны использоваться только классами, производными от BaseHandler.

BaseHandler.parent

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

BaseHandler.default_open(req)

Этот метод не определен в BaseHandler, но подклассы должны его определить, если они хотят обрабатывать все URL-адреса.

Этот метод, если он реализован, будет вызван родительским OpenerDirector. Он должен вернуть объект, подобный файлу, как описано в значении возврата метода open() объекта OpenerDirector, или None. Он должен вызывать исключение URLError, если не произойдёт действительно исключительное событие (например, MemoryError не должно отображаться как URLError).

Этот метод будет вызван до любого метода открытия, специфичного для протокола.

BaseHandler.<protocol>_open(req)

Этот метод не определен в BaseHandler, но подклассы должны его определить, если они хотят обрабатывать URL-адреса с заданным протоколом.

Этот метод, если он определён, будет вызван родительским OpenerDirector. Значения возврата должны быть такими же, как для default_open().

BaseHandler.unknown_open(req)

Этот метод не определен в BaseHandler, но подклассы должны его определить, если они хотят обрабатывать все URL-адреса без зарегистрированного обработчика открытия.

Этот метод, если реализован, будет вызван родительским parent OpenerDirector. Значения возврата должны быть такими же, как для default_open().

BaseHandler.http_error_default(req, fp, code, msg, hdrs)

Этот метод не определен в BaseHandler, но подклассы должны его переопределить, если они намерены обеспечить обработку всех необработанных ошибок HTTP. Он будет автоматически вызван OpenerDirector при возникновении ошибки и обычно не должен вызываться в других ситуациях.

req будет объектом Request, fp будет объектом, подобным файлу, с телом ошибки HTTP, code будет трёхзначным кодом ошибки, msg будет отображаемым пользователю описанием кода, а hdrs будет объектом отображения с заголовками ошибки.

Значения возврата и генерируемые исключения должны быть такими же, как у urlopen().

BaseHandler.http_error_<nnn>(req, fp, code, msg, hdrs)

nnn должен быть трёхзначным кодом ошибки HTTP. Этот метод также не определён в BaseHandler, но будет вызван, если он существует, на экземпляре подкласса, когда возникает ошибка HTTP с кодом nnn.

Подклассы должны переопределять этот метод для обработки конкретных ошибок HTTP.

Аргументы, возвращаемые значения и генерируемые исключения должны быть такими же, как для http_error_default().

BaseHandler.<protocol>_request(req)

Этот метод не определен в BaseHandler, но подклассы должны его определить, если они хотят предварительно обработать запросы заданного протокола.

Этот метод, если он определен, будет вызван родительским OpenerDirector. req будет объектом Request. Значение возврата должно быть объектом Request.

BaseHandler.<protocol>_response(req, response)

Этот метод не определен в BaseHandler, но подклассы должны его определить, если они хотят послеобработать ответы заданного протокола.

Этот метод, если он определен, будет вызван родительским OpenerDirector. req будет объектом Request. response будет объектом, реализующим тот же интерфейс, что и значение возврата urlopen(). Значение возврата должно реализовывать тот же интерфейс, что и значение возврата urlopen().

Объекты HTTPRedirectHandler

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

Возвращает Request или None в ответ на перенаправление. Данный метод вызывается в реализации по умолчанию методов http_error_30*() при получении перенаправления от сервера. Если перенаправление необходимо, вернуть новый объект Request для выполнения перенаправления на 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(), но вызывается для ответа «временное перенаправление». Оно не позволяет изменять метод запроса с POST на GET.

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

То же, что и http_error_301(), но вызывается для ответа «постоянное перенаправление». Оно не позволяет изменять метод запроса с POST на GET.

Новое в версии 3.11.

Объекты HTTPCookieProcessor

HTTPCookieProcessor имеют один атрибут:

HTTPCookieProcessor.cookiejar

Объект http.cookiejar.CookieJar, в котором хранятся куки.

Объекты ProxyHandler

ProxyHandler.<protocol>_open(request)

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

Объекты HTTPPasswordMgr

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

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

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

HTTPPasswordMgr.find_user_password(realm, authuri)

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

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

Объекты HTTPPasswordMgrWithPriorAuth

Этот менеджер паролей расширяет HTTPPasswordMgrWithDefaultRealm, чтобы поддерживать отслеживание URI, для которых аутентификационные данные должны всегда передаваться.

HTTPPasswordMgrWithPriorAuth.add_password(realm, uri, user, passwd, is_authenticated=False)

realm, uri, user, passwd — как и в HTTPPasswordMgr.add_password(). is_authenticated устанавливает начальное значение флага is_authenticated для данного URI или списка URI. Если is_authenticated задано как True, то realm игнорируется.

HTTPPasswordMgrWithPriorAuth.find_user_password(realm, authuri)

Аналогично объектам HTTPPasswordMgrWithDefaultRealm.

HTTPPasswordMgrWithPriorAuth.update_authenticated(self, uri, is_authenticated=False)

Обновить флаг is_authenticated для данного uri или списка URI.

HTTPPasswordMgrWithPriorAuth.is_authenticated(self, authuri)

Возвращает текущее состояние флага is_authenticated для данного URI.

Объекты AbstractBasicAuthHandler

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

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

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

Объекты HTTPBasicAuthHandler

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

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

Объекты ProxyBasicAuthHandler

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

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

Объекты AbstractDigestAuthHandler

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

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

Объекты HTTPDigestAuthHandler

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

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

Объекты ProxyDigestAuthHandler

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

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

Объекты HTTPHandler

HTTPHandler.http_open(req)

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

Объекты HTTPSHandler

HTTPSHandler.https_open(req)

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

Объекты FileHandler

FileHandler.file_open(req)

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

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

Объекты DataHandler

DataHandler.data_open(req)

Чтение URL-адреса данных. Такой URL содержит кодированное содержимое в самом URL. Синтаксис 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().

Примеры

В дополнение к примерам ниже, больше примеров предоставлено в HOWTO Получение ресурсов Интернета с помощью пакета 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

В следующем примере мы отправляем поток данных в stdin CGI и считываем возвращаемые данные. Обратите внимание, что этот пример будет работать только в случае, если ваша установка Python поддерживает SSL.

>>> 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)

Использование базовой аутентификации 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

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

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