Автостопом по Python

Мы можем разобраться в происходящем благодаря удачно выбранным именам модулей, но если нужно больше информации, просмотрите строки документации модуля, введя head *.py в каталоге верхнего уровня. В следующем списке эти строки документации приводятся в сокращенном виде (не показывается com­pat.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.Re­­quest, 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 '

:rtype: requests.Response

"""

return request('delete', url, **kwargs)

Представление этого определения в Sphinx autodoc находится в онлайн-документации к API (http://docs.python-requests.org/en/master/api/#requests.delete).

Примеры из структуры Requests

Все любят API Requests — его просто запомнить, он помогает пользователям писать простой и красивый код. В этом разделе сначала рассматривается предпоч­тительный дизайн для более полных сообщений об ошибках и запоминающийся API, который, как мы думаем, привел к созданию модуля requests.api. Затем мы рассмотрим разницу между объектами requests.Request и urllib.request.Request и расскажем, для чего существует объект requests.Request.

Высокоуровневый API (очевидный способ решить задачу, желательно единственный)