Таня Шлюссер - Автостопом по Python

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

Если вы начинаете новый проект и используете 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).

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

Функции, определенные в файле api.py (за исключением request()), названы в честь методов запросов HTTP [65] Они определены в разделе 4.3 текущего рабочего предложения для HTTP ( http://bit.ly/http-method-def ). . Все методы запроса практически одинаковы, за исключением имени метода и возможных параметров с ключевыми словами, поэтому мы удалим из этого фрагмента весь код, расположенный в файле requests/api.py после функции get().

Функция request() содержит в своей сигнатуре **kwargs. Это означает, что дополнительные аргументы с ключевым словом не сгенерируют исключение, также это скрывает параметры от пользователя.

В документации, опущенной в этом фрагменте для краткости, описывается каждый аргумент с ключевым словом, с которым связано действие. Использование **kwargs из сигнатуры вашей функции — единственный способ для пользователя сказать, каким должно быть содержимое **kwargs, не заглядывая в код.