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

Объекты Request

Следующие методы описывают общедоступный интерфейс 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, которые добавляют их в список заголовков, отправляемых серверу. Обратите внимание, что заголовки с одинаковым именем повторяться не могут: последующие вызовы перезаписывают предыдущие, если совпадает key. В настоящее время это не ограничивает возможности 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 заменяют соответствующие значения экземпляра, а selector экземпляра становится исходным URL-адресом, переданным конструктору.

Request.get_header(header_name, default=None)

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

Request.header_items()

Возвращает список кортежей (header_name, header_value) для заголовков Request.

Объекты 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() — указывает, что обработчик умеет обрабатывать ошибки протокола protocol (кроме http).

• <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().

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

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

Объекты BaseHandler

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

BaseHandler.add_parent(director)

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

BaseHandler.close()

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

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

BaseHandler.parent

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

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-адреса, для открытия которых не зарегистрирован конкретный обработчик.

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

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

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

OpenerDirector вызовет этот метод с пятью позиционными аргументами:

1. объект Request,
2. файлоподобный объект с телом ошибки HTTP,
3. трёхзначный код ошибки в виде строки,
4. понятное пользователю описание кода в виде строки и
5. заголовки ошибки в виде объекта отображения.

Возвращаемые значения и возникающие исключения должны быть такими же, как у 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, чтобы http_error_30*() мог выполнить перенаправление на newurl. В противном случае вызывает исключение HTTPError, если этот URL не должен обрабатываться никаким другим обработчиком, или возвращает None, если этот обработчик не может его обработать, но это может сделать другой обработчик.

Примечание

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

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

Перенаправляет на URL Location: или URI:. Этот метод вызывается родительским объектом 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, в котором хранятся файлы cookie.

Объекты 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 включает схему, его учетные данные соответствуют только URI аутентификации с той же схемой или без схемы. URI без схемы соответствует URI аутентификации с любой схемой.

Изменено в версии 3.14.7 (ещё не выпущена): Теперь учетные данные аутентификации для URI со схемой ограничиваются этой схемой.

HTTPPasswordMgr.find_user_password(realm, authuri)

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

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

Объекты 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 должно быть именем заголовка, в котором в запросе указана информация об области, host задаёт URL и путь, для которых требуется аутентификация, req должен быть неудавшимся объектом Request, а headers должны содержать заголовки ошибки.

host — это либо полномочия (например, "python.org"), либо URL, содержащий компонент полномочий (например, "https://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.data.

Объекты HTTPSHandler

HTTPSHandler.https_open(req)

Отправляет HTTPS-запрос GET или POST в зависимости от req.data.

Объекты FileHandler

FileHandler.file_open(req)

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

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

Объекты DataHandler

DataHandler.data_open(req)

Читает URL данных. URL такого типа содержит закодированные в самом URL данные. Синтаксис URL данных определён в RFC 2397. Эта реализация игнорирует пробельные символы в URL данных с кодированием base64, поэтому URL можно переносить в исходном файле, в котором он содержится. Однако, хотя некоторые браузеры допускают отсутствие заполнения в конце URL данных с кодированием base64, в этом случае данная реализация вызывает исключение 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('https://www.python.org/') as f:
...     # The response may be compressed (for example, 'gzip').
...     print(f.headers.get('Content-Encoding'))
...     data = f.read()
...     if f.headers.get('Content-Encoding') == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:300].decode('utf-8', errors='replace'))

Обратите внимание, что urlopen возвращает объект bytes. Это связано с тем, что urlopen не может автоматически определить кодировку полученного от HTTP-сервера потока байтов. Обычно программа преобразует возвращённый объект bytes в строку, определив или предположив подходящую кодировку.

В следующем документе со спецификацией HTML перечислены различные способы указания сведений о кодировке в документах HTML или XML: https://html.spec.whatwg.org/#charset.

Дополнительные сведения см. в документе W3C: https://www.w3.org/International/questions/qa-html-encoding-declarations.

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

>>> with urllib.request.urlopen('https://www.python.org/') as f:
...     # Check for compression and decode appropriately.
...     enc = f.headers.get('Content-Encoding')
...     data = f.read()
...     if enc == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:100].decode('utf-8', errors='replace'))
...

Того же результата можно добиться и без использования менеджера контекста:

>>> import urllib.request
>>> f = urllib.request.urlopen('https://www.python.org/')
>>> try:
...     enc = f.headers.get('Content-Encoding')
...     data = f.read()
...     if enc == 'gzip':
...         import gzip
...         data = gzip.decompress(data)
...     print(data[:100].decode('utf-8', errors='replace'))
... finally:
...     f.close()

В следующем примере мы отправляем поток данных в 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)
with urllib.request.urlopen('http://www.example.com/login.html') as f:
    print(f.read().decode('utf-8'))

build_opener() по умолчанию предоставляет множество обработчиков, в том числе ProxyHandler. По умолчанию ProxyHandler использует переменные среды с именами <scheme>_proxy, где <scheme> — используемая схема URL. Например, для получения URL HTTP-прокси считывается переменная среды http_proxy.

В этом примере стандартный 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:
with opener.open('http://www.example.com/login.html') as f:
   print(f.read().decode('utf-8'))

Добавление заголовков HTTP:

Используйте аргумент headers конструктора Request или:

import urllib.request
req = urllib.request.Request('http://www.example.com/')
req.add_header('Referer', 'https://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
with urllib.request.urlopen(req) as f:
    print(f.read().decode('utf-8'))

OpenerDirector автоматически добавляет заголовок User-Agent в каждый объект Request. Чтобы изменить это поведение:

import urllib.request
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
with opener.open('http://www.example.com/') as f:
   print(f.read().decode('utf-8'))

Также помните, что при передаче объекта Request в urlopen() (или OpenerDirector.open()) добавляются несколько стандартных заголовков (Content-Length, Content-Type и Host).

Пример сеанса, в котором для получения URL с параметрами используется метод GET:

>>> import urllib.request
>>> import urllib.parse
>>> params = urllib.parse.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> url = "https://www.python.org/?%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("https://httpbin.org/post", data) as f:
...     print(f.read().decode('utf-8'))
...

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

>>> import urllib.request
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler(proxies))
>>> with opener.open("https://www.python.org") as f:
...     f.read().decode('utf-8')
...

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

>>> import urllib.request
>>> opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
>>> with opener.open("https://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, headers), где filename — имя локального файла, в котором находится объект, а headers — результат вызова метода info() объекта, возвращённого urlopen() (для удалённого объекта). Возникают те же исключения, что и при вызове urlopen().

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

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

>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('https://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(). Также сбрасывает глобальный обработчик по умолчанию, установленный с помощью install_opener().

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.