Библиотека Requests стремится покрыть все спецификации HTTP от IETF, задействуя всего несколько функций, набор аргументов с ключевым словом и несколько классов.
Как и в случае 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.
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 на самом деле ничего не делают — просто сохраняют данные, возможно несколько изменяя их в угоду представлению, сериализации или кодировке. Действия обрабатываются отдельными классами, которые существуют только для того, чтобы выполнить, например, аутентификацию или коммуникацию. Каждый класс делает что-то одно, и каждый модуль содержит классы, выполняющие похожие задачи, — в этом и проявляется питонский подход, который многие из нас используют для определений функций.