Читаем более крупную библиотеку.

Библиотека Requests намного крупнее библиотеки Tablib и имеет множество модулей. Однако мы подходим к вопросу ее прочтения точно так же — просмотрим документацию и будем следовать API в коде.

Загрузите Requests из GitHub:

$ git clone https://github.com/kennethreitz/requests.git.

$ virtualenv — p python3 venv.

$ source venv/bin/activate.

(venv)$ cd requests.

(venv)$ pip install — editable.

(venv)$ pip install — r requirements.txt # Required for unit tests.

(venv)$ py.test tests # Run the unit tests.

Некоторые тесты могут дать сбой. Например, если ваш интернет-провайдер перехватывает ошибку 404 для того, чтобы показать вам какую-нибудь рекламу, вы не сможете сгенерировать исключение ConnectionError.

Читаем документацию библиотеки Requests.

Библиотека Requests находится в гораздо более крупном пакете, поэтому сначала просмотрите лишь заголовки разделов в документации к Requests (http://docs.python-requests.org/). Requests расширяет библиотеки urrlib и httplib, которые вы можете найти в стандартной библиотеке Python, предоставляя методы, выполняющие запросы HTTP. Библиотека предусматривает поддержку международных доменов и URL, автоматическую декомпрессию, автоматическое декодирование содержимого, проверку сертификатов SSL, поддержку прокси для HTTP(S) и другую функциональность, определенную стандартами Internet Engineering Task Force (IETF) для HTTP с помощью запросов комментария (requests for comment, RFC) 7230–7235[64].

Библиотека Requests стремится покрыть все спецификации HTTP от IETF, задействуя всего несколько функций, набор аргументов с ключевым словом и несколько классов.

Используем Requests.

Как и в случае Tablib, в строках документации содержится достаточно информации для того, чтобы использовать Requests, не обращаясь к документации, размещенной онлайн. Рассмотрим следующий пример:

>>> import requests.

>>> help(requests) # Показывает руководство по использованию.

···················# и указывает искать 'requests.api'.

>>> help(requests.api) # Показывает подробное описание API.

>>>

>>> result = requests.get('https://pypi.python.org/pypi/requests/json').

>>> result.status_code.

200.

>>> result.ok.

True.

>>> result.text[:42].

'{\n····"info": {\n········"maintainer": null'.

>>>

>>> result.json(). keys().

Dict_keys(['info', 'releases', 'urls']).

>>>

>>> result.json()['info']['summary'].

'Python HTTP for Humans.'.

Читаем код Requests.

Рассмотрим содержимое пакета Requests.

Cacert.pem — стандартный набор сертификатов, который используется при проверке сертификатов SSL.

Requests имеет простую структуру, за исключением каталога packages, хранящего сторонние зависимости chardet и urllib3. Они импортируются как requests.packages.chardet и requests.packages.urllib3, поэтому программисты все еще могут получить доступ к chardet и urllib3 из стандартной библиотеки.

Мы можем разобраться в происходящем благодаря удачно выбранным именам модулей, но если нужно больше информации, просмотрите строки документации модуля, введя head *.py в каталоге верхнего уровня. В следующем списке эти строки документации приводятся в сокращенном виде (не показывается compat.py). Исходя из его имени (он назван так же, как и аналогичный файл библиотеки Reitz’s Tablib, мы можем сделать вывод, что он отвечает за совместимость между Python 2 и Python 3).

• api.py — реализует Requests API.

• hooks.py — предоставляет возможность использовать систему функций перехвата Requests.

• models.py — содержит основные объекты, которыми пользуется Requests.

• sessions.py — предоставляет объект Session для управления настройками и их сохранения между запросами (cookies, авторизация, прокси).

• auth.py — содержит дескрипторы для аутентификации в Requests.

• status_codes.py — таблица, в которой соотносятся заголовки состояний и их коды.

• cookies.py — код для совместимости, который позволяет использовать cookielib.CookieJar с запросами.

• adapters.py — содержит транспортные адаптеры, которые Requests применяет для определения и поддержания соединений.

• exceptions.py — все исключения Requests.

• structures.py — структуры данных, которыми пользуется Requests.

• certs.py — возвращает предпочтительный набор сертификатов CA по умолчанию, в котором перечислены доверенные сертификаты SSL.

• utils.py — предоставляет вспомогательные функции, которые используются внутри Requests и могут применяться внешними пользователями.

Что мы узнали из заголовков:

• существует система функций перехвата (hooks.py) — это подразумевает, что пользователь может модифицировать способ работы библиотеки Requests. Мы не будем обсуждать этот вопрос подробно, чтобы не отвлекаться от темы;

• основным модулем является models.py, поскольку в нем содержатся «основные объекты, которыми пользуется Requests»;

• основная причина существования sessions.Session — сохранение cookies между несколькими запросами (например, это может понадобиться во время аутентификации);

• соединение HTTP создается с помощью объектов из модуля adapters.py;

• остальная часть проекта довольно очевидна: auth.py нужен для аутентификации, status_codes.py содержит коды состояний, cookies.py нужен для добавления и удаления cookies, exceptions.py — для исключений, structures.py содержит структуры данных (например, не зависящий от регистра словарь), utils.py — вспомогательные функции.

Идея поместить модуль коммуникации в отдельный файл adapters.py инновационна (во всяком случае для этого разработчика). Это означает, что models.Request, models.PreparedRequest и models.Response на самом деле ничего не делают — просто сохраняют данные, возможно несколько изменяя их в угоду представлению, сериализации или кодировке. Действия обрабатываются отдельными классами, которые существуют только для того, чтобы выполнить, например, аутентификацию или коммуникацию. Каждый класс делает что-то одно, и каждый модуль содержит классы, выполняющие похожие задачи, — в этом и проявляется питонский подход, который многие из нас используют для определений функций.

Строки документации Requests, совместимые со Sphinx. Если вы начинаете новый проект и используете Sphinx и его расширения autodoc, вам нужно отформатировать строки документации таким образом, чтобы Sphinx смог проанализировать их. В документации Sphinx не всегда получится легко найти нужные ключевые слова. Многие рекомендуют копировать строки документации в Requests, если вы хотите, чтобы формат был правильным, а не искать инструкции в документации Sphinx. Например, рассмотрим определение функции delete() в файле requests/api.py: Def delete(url, **kwargs): ····"""Отправляет запрос DELETE. ····:param url: URL для нового объекта: class:'Request'. ····:param \*\*kwargs: Необязательные аргументы, которые принимает. ·······················''request''. ····:return: объект класса: class:'Response <Response>'. ····:rtype: requests.Response. ····""". ····return request('delete', url, **kwargs). Представление этого определения в Sphinx autodoc находится в онлайн-документации к API (http://docs.python-requests.org/en/master/api/#requests.delete).