Рис. 5.1. Прозрачные пути и прозрачные имена функций в графе вызовов проекта howdoi
Ключевое слово для перечисления сценариев консоли — console_scripts.
Объявляет, что исполняемый файл с именем howdoi в качестве цели будет иметь функцию howdoi.howdoi.command_line_runner(). Поэтому мы будем знать, что функция command_line_runner() является стартовой точкой для всего приложения.
Примеры из структуры 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(), обрабатывающая все возможные исключения.
Остальные внутренние функции (_format_output(), _is_question(), _enable_cache() и _clear_cache()) не предназначены для использования за пределами пакета. Тестирующий сценарий howdoi/test_howdoi.py вызывает только функции без префиксов, проверяя, что средство форматирования работает, и передавая аргумент командной строки для раскрашивания в функцию верхнего уровня howdoi.howdoi() вместо того, чтобы передавать код в функцию howdoi._format_output().
Разница между версиями возможных зависимостей обрабатывается перед выполнением основного кода, поэтому пользователь знает, что проблем с зависимостями не возникнет, а проверка версий не засоряет код в других местах. Это хорошо, поскольку HowDoI поставляется как инструмент командной строки и дополнительные усилия, затрачиваемые пользователями, будут означать, что им не потребуется менять свою среду Python, чтобы установить инструмент. Рассмотрим фрагмент кода, в котором решается эта проблема: