Автостопом по Python - [49]
Читаем более крупную библиотеку
Библиотека Requests намного крупнее библиотеки Tablib и имеет множество модулей. Однако мы подходим к вопросу ее прочтения точно так же — просмотрим документацию и будем следовать API в коде.
Загрузите Requests из GitHub:
>$ git clone https://github.com/kennethreitz/requests.git
>$ virtualenv — p python3 venv
>$ source venv/bin/activate
>(venv)$ cd requests
>(venv)$ pip install — editable.
>(venv)$ pip install — r requirements.txt # Required for unit tests
>(venv)$ py.test tests # Run the unit tests.
Некоторые тесты могут дать сбой. Например, если ваш интернет-провайдер перехватывает ошибку 404 для того, чтобы показать вам какую-нибудь рекламу, вы не сможете сгенерировать исключение ConnectionError.
Библиотека Requests находится в гораздо более крупном пакете, поэтому сначала просмотрите лишь заголовки разделов в документации к Requests (http://docs.python-requests.org/). Requests расширяет библиотеки urrlib и httplib, которые вы можете найти в стандартной библиотеке Python, предоставляя методы, выполняющие запросы HTTP. Библиотека предусматривает поддержку международных доменов и URL, автоматическую декомпрессию, автоматическое декодирование содержимого, проверку сертификатов SSL, поддержку прокси для HTTP(S) и другую функциональность, определенную стандартами Internet Engineering Task Force (IETF) для HTTP с помощью запросов комментария (requests for comment, RFC) 7230–7235[64].
Библиотека 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.
Мы можем разобраться в происходящем благодаря удачно выбранным именам модулей, но если нужно больше информации, просмотрите строки документации модуля, введя 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 — вспомогательные функции.
