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 использует прокси, то селектор будет полным 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().

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

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

Обработчики 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.

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 — имя заголовка, где в запросе содержится информация о realm, 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 — имя заголовка, где в запросе содержится информация о realm, 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().

Примеры

В дополнение к примерам ниже, больше примеров приведено в 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 возвращает объект байтов. Это связано с тем, что urlopen не может автоматически определить кодировку потока байтов, полученного от HTTP-сервера. В общем случае программа декодирует возвращенный объект байтов в строку, как только определит или предположит соответствующую кодировку.

В следующем документе W3C, https://www.w3.org/International/O-charset, перечислены различные способы, которыми (X)HTML или XML документ может указать информацию о своей кодировке.

Поскольку веб-сайт python.org использует кодировку utf-8, как указано в теге мета, мы воспользуемся той же кодировкой для декодирования объекта байтов.

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

Использование аутентификации 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 вместо него. Обратите внимание, что параметры, выведенные из 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:, file:, или ftp:, вам, вероятно, следует использовать 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().

Этот метод всегда использует quote() для кодирования строки fullurl.

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