Автостопом по Python - [50]

Идея поместить модуль коммуникации в отдельный файл 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 '
····: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 (очевидный способ решить задачу, желательно единственный)

Функции, определенные в файле api.py (за исключением request()), названы в честь методов запросов HTTP[65]. Все методы запроса практически одинаковы, за исключением имени метода и возможных параметров с ключевыми словами, поэтому мы удалим из этого фрагмента весь код, расположенный в файле requests/api.py после функции get().

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

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

С помощью оператора with Python поддерживает контекст времени выполнения. Оно может быть использовано для любого объекта, для которого определены методы __enter__() и __exit__(). Метод __enter()__ будет вызван при входе в оператор with, а __exit__() — при выходе, независимо от того, завершился оператор нормально или сгенерировал исключение.

Функция get() получает ключевое слово params=None, применяя значение по умолчанию None. Аргумент с ключевым словом params важен для get, поскольку будет использоваться в строке запроса HTTP. Предоставление отдельных аргументов с ключевым словом дает гибкость действий опытным пользователям (благодаря оставшимся **kwargs), упрощая работу для 99 % людей, которым это не нужно.

По умолчанию функция request() не разрешает перенаправление, поэтому на этом шаге устанавливается значение True, если пользователь не сделал этого заранее.

Функция get() вызывает функцию request(), передавая в качестве первого параметра get. Создание функции get имеет два преимущества перед использованием строкового аргумента вроде request("get"…). Во-первых, даже без документации становится очевидно, какие методы HTTP доступны в этом API. Во-вторых, если пользователь сделает опечатку в имени метода, исключение NameError будет сгенерировано быстрее, и, возможно, его будет проще отследить, чем если бы оно было сгенерировано более глубоко в коде.

В файле requests/api.py нет новой функциональности; она существует для того, чтобы предоставить пользователю простой API. Плюс размещение строковых методов HTTP непосредственно в API в качестве имен функций означает, что любая опечатка в имени метода будет найдена на ранних этапах, например:

>>> requests.foo('http://www.python.org')
Traceback (most recent call last):
····File "", line 1, in
AttributeError: 'module' object has no attribute 'foo'
>>>
>>> requests.request('foo', 'http://www.python.org')

Объекты класса Request и PreparedRequest (мы все — ответственные пользователи)