Кеннет Рейтц – Автостопом по Python (страница 24)
HowDoI
Проект HowDoI, написанный Бенджамином Гляйтсманом (Benjamin Gleitzman), станет отличной стартовой точкой нашей одиссеи, несмотря на то что он состоит менее чем из 300 строк.
Читаем сценарий, состоящий из одного файла
Сценарий обычно имеет четко определенные точку входа, параметры и точку выхода. Благодаря этому читать его проще, чем библиотеки, которые предоставляют API или фреймворк.
Загрузите модуль HowDoI с GitHub[55]:
$ git clone https://github.com/gleitz/howdoi.git
$ virtualenv — p python3 venv # Или используйте mkvirtualenv, на ваш выбор…
$ source venv/bin/activate
(venv)$ cd howdoi/
(venv)$ pip install — editable.
(venv)$ python test_howdoi.py # Запустите юнит-тесты
Теперь у вас должен быть установлен исполняемый файл howdoi в каталоге venv/bin. (Вы можете увидеть его, введя cat 'which howdoi' в командной строке.) Он был сгенерирован автоматически, когда вы ввели команду pip install.
Документация к HowDoI находится в файле README.rst, который располагается в репозитории на GitHub (https://github.com/gleitz/howdoi). Это небольшое приложение для командной строки, позволяющее пользователям искать в Интернете ответы на вопросы, связанные с программированием.
В командной строке терминальной оболочки можно ввести команду howdoi — help, чтобы узнать, как пользоваться HowDoI:
(venv)$ howdoi — help
usage: howdoi [-h] [-p POS] [-a] [-l] [-c] [-n NUM_ANSWERS] [-C] [-v]
··············[QUERY [QUERY…]]
instant coding answers via the command line
positional arguments:
··QUERY ················the question to answer
optional arguments:
··-h, — help ···········show this help message and exit
··-p POS, — pos POS ····select answer in specified position (default: 1)
··-a, — all ············display the full text of the answer
··-l, — link ···········display only the answer link
··-c, — color ··········enable colorized output
··-n NUM_ANSWERS, — num-answers NUM_ANSWERS
························number of answers to return
··-C, — clear-cache ····clear the cache
··-v, — version ········displays the current version of howdoi
Из документации мы знаем, что HowDoI получает ответы на вопросы, связанные с программированием, из Интернета. В руководстве указано, что можно выбрать ответ в определенной позиции, раскрасить выводимую информацию, получить несколько ответов, а также то, что модуль имеет кэш, который можно очистить.
Мы можем подтвердить, что понимаем, как работает HowDoI. Рассмотрим пример:
(venv)$ howdoi — num-answers 2 python lambda function list comprehension
- Answer 1 —
[(lambda x: x*x)(x) for x in range(10)]
- Answer 2 —
[x() for x in [lambda m=m: m for m in [1,2,3]]]
# [1, 2, 3]
Мы установили HowDoI, прочли его документацию и теперь можем его использовать. Перейдем к чтению кода!
Если вы заглянете в каталог howdoi/, то увидите два файла: __init__.py, который состоит всего из одной строки, указывающей номер версии, и howdoi.py, который мы откроем и прочитаем.
Просматривая файл howdoi.py, мы увидим, что каждое новое определение функции использовано в следующей функции; это упрощает чтение кода. Каждая функция выполняет всего одну задачу (она вынесена в ее имя). Главная функция command_line_runner() располагается в нижней части файла howdoi.py.
Вместо того чтобы приводить здесь исходный код HowDoI, мы можем проиллюстрировать структуру его вызовов с помощью графа, показанного на рис. 5.1. Этот граф создан с помощью Python Call Graph (https://pycallgraph.readthedocs.io/), который предоставляет визуализацию функций, вызываемых при запуске сценария Python. Он хорошо работает с приложениями командной строки благодаря тому, что они имеют одну точку входа и относительно небольшое количество путей выполнения, по которым может пойти код. (Обратите внимание, что мы вручную удалили из отрисованного изображения функции, которые отсутствуют в проекте HowDoI, дабы вместить граф на страницу, а также немного переформатировали его.)
Код мог бы выглядеть как одна большая спагетти-функция, сложная для восприятия. Вместо этого код был намеренно разбит на отдельные функции, имеющие понятные имена. Кратко рассмотрим граф, изображенный на рис. 5.1: функция command_line_runner() анализирует входные данные и передает флаги и запрос, полученные от пользователя, в функцию howdoi(). Далее функция howdoi() оборачивает функцию _get_instructions() в блок try/except, чтобы можно было отловить ошибки соединения и вывести адекватное сообщение об ошибке (поскольку код приложения не должен завершать работу при наличии исключения).
Основную работу делает функция _get_instructions(): она вызывает функцию _get_links(), чтобы выполнить поиск ссылок, соответствующих запросу, в Google или на сайте Stack Overflow, а затем — функцию _get_answer() для каждого полученного результата (вплоть до предельного количества ссылок, указанного пользователем в командной строке, — по умолчанию одной).
Функция _get_answer() следует ссылке на ресурс Stack Overflow, извлекает код из ответа, раскрашивает его и возвращает функции _get_instructions(), которая объединяет все ответы в одну строку и возвращает их. Функции _get_links() и _get_answer() вызывают _get_result(), чтобы выполнить HTTP-запрос: _get_links() для запроса Google и _get_answer() для получения ссылок из запроса Google.
Функция _get_result() лишь оборачивает функцию requests.get() блоком try/except, чтобы можно было отловить ошибки SSL, вывести сообщение об ошибке и повторно сгенерировать исключение, дабы блок try/except верхнего уровня мог отловить его и выйти (это правило хорошего тона для любых программ).
Файл setup.py проекта HowDoI, который находится выше каталога howdoi/, — отличный пример модуля установки, поскольку в дополнение к обычной установке пакета он также устанавливает исполняемый файл (к которому вы можете обратиться при упаковке собственной утилиты командной строки). Функция установки tools.setup() использует аргументы с ключевым словом для определения всех параметров конфигурации. Та часть, которая отвечает за исполняемый файл, использует аргумент с ключевым словом entry_points.
Рис. 5.1. Прозрачные пути и прозрачные имена функций в графе вызовов проекта howdoi
Примеры из структуры HowDoI
HowDoI — это небольшая библиотека (в других разделах мы рассмотрим ее архитектуру более подробно, а здесь лишь скажем пару слов).
Мы не устанем повторять, насколько полезно разделять внутренние функции HowDoI таким образом, чтобы они делали лишь что-то одно. Существуют функции, чье единственное предназначение — оборачивание других функций в оператор try/except. (Единственная функция, имеющая оператор try/except, которая не следует этой практике, — _format_output(). Она задействует операторы try/except не для обработки исключений, а для определения языка программирования с целью подсветки синтаксиса.)
HowDoI проверяет и использует текущие системные значения, например с помощью функции urllib.request.getproxies() обрабатывается применение прокси-серверов (это подойдет для организаций вроде школ, которые имеют промежуточный сервер, фильтрующий соединение с Интернетом). Обратите внимание на этот сниппет:
XDG_CACHE_DIR = os.environ.get(
····'XDG_CACHE_HOME',
····os.path.join(os.path.expanduser('~'), '.cache')
)
Как вам узнать, что эти переменные существуют? Необходимость urllib.request.getproxies() обусловлена необязательными аргументами в requests.get(), поэтому часть этой информации доступна из сведений API о вызываемых вами библиотеках. Переменные среды зачастую нужны для определенной функциональности, поэтому, если библиотека предназначена для использования с конкретной базой данных или другим родственным приложением, в документации к этим приложениям будут перечислены актуальные переменные среды. Для систем POSIX хорошей стартовой точкой будет список стандартных переменных среды Ubuntu (https://help.ubuntu.com/community/EnvironmentVariables) или список переменных среды в спецификации POSIX (http://bit.ly/posix-env-variables), который указывает на другие важные списки.
Примеры из стиля HowDoI
HowDoI в основном следует PEP 8, но не в тех случаях, когда это вредит читаемости. Например, операторы импорта находятся в верхней части файла, но стандартная библиотека и внешние модули перемешаны. И несмотря на то что строковые константы в USER_AGENTS гораздо длиннее 80 символов, в строках нет места, где их можно было бы разбить естественным образом, поэтому они остаются целыми.
В нескольких следующих фрагментах кода показываются другие решения, связанные со стилем, о которых мы говорили в главе 4.
Имя почти каждой функции в HowDoI начинается с нижнего подчеркивания. Это показывает, что функции предназначены лишь для внутреннего использования. Для большинства из них это нужно, потому что при их прямом вызове появляется вероятность генерации необработанного исключения (этим грешат все функции, которые вызывают функцию _get_result()), до тех пор пока не будет вызвана функция howdoi(), обрабатывающая все возможные исключения.