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

Функции, определенные в файле api.py (за исключением request()), названы в честь методов запросов HTTP65. Все методы запроса практически одинаковы, за исключением имени метода и возможных параметров с ключевыми словами, поэтому мы удалим из этого фрагмента весь код, расположенный в файле 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 (мы все — ответственные пользователи)

Файл __init__.py предоставляет классы Request, PreparedRequest и Response из файла models.py как часть основного API. Зачем вообще нужен файл models.Re­quest? В стандартной библиотеке уже существует urllib.requests.Request, и в файле cookies.py находится объект MockRequest, который оборачивает models.Re­quest, чтобы он работал как urllib.requests.Request для http.cookiejar66. Это означает, что любые методы, необходимые для взаимодействия объекта типа Request с библио­текой cookies, намеренно исключены из requests.Request. Для чего эти лишние усилия?

Дополнительные методы в MockRequest (нужен для эмуляции urllib.request.Re­quest для библиотеки cookies) используются библиотекой cookies для управления cookies. За исключением функции get_type() (которая обычно возвращает http или https при использовании) и непроверяемого свойства (в нашем случае True), они связаны с URL или заголовками запросов.

Связанные с заголовками:

• add_unredirected_header() — добавить в заголовок новую пару ключ-значение;

• get_header() — получить определенное имя из словаря заголовков;

• get_new_headers() — получить словарь, содержащий новые заголовки (которые добавлены с помощью cookielib); • has_header() — проверяем, существует ли имя в словаре заголовков.

Связанные с URL:

• get_full_url() — соответствует своему имени;

• host и origin_req_host — свойства, чьи значения устанавливаются путем вызова методов get_host() и get_origin_req_host() соответственно; • get_host() — извлекает хост из URL (например, www.python.org из https://www.py­thon.orgdevpeps/pep-0008/); • get_origin_req_host() — вызывает get_host()67.

Все они являются функциями доступа, за исключением MockRequest.add_unre­directed_header().

В строке документации к объекту MockRequest указывается, что «оригинальный объект запроса доступен только для чтения».

В requests.Request вместо этого непосредственно доступны атрибуты данных. Это делает все функции доступа ненужными: для получения или установки заголовков требуется лишь получить доступ к словарю request-instance.headers. Аналогично пользователь может получить или изменить строку URL: request-instance.url.