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

Таблица 5.1. Типичные функции рассматриваемых проектов

Пакет

Ли­цензия

Количество строк

Строки документации (% от общего количества строк)

Комментарии документации (% от общего количества строк)

Пустые строки документации (% от общего количества строк)

Средняя длина функций

HowDoI

MIT

262

0

6

20

13 строк

Diamond

MIT

6021

21

9

16

11 строк

Tablib

MIT

1802

19

4

27

8 строк

Requests

Apache 2.0

4072

23

8

19

10 строк

Flask

BSD 3-clause

10 163

7

12

11

13 строк

Werkzeug

BSD 3-clause

25 822

25

3

13

9 строк

В каждом разделе мы будем использовать разные приемы чтения кода для того, чтобы понять, чему посвящен проект. Далее мы приведем фрагменты кода, которые демонстрируют темы, описанные в этом руководстве. (Если мы не выделили какую-то функцию в одном проекте, это не означает, что ее там нет; мы лишь хотим охватить большое количество концепций с помощью этих примеров.) После завершения чтения этой главы вы будете более уверенно работать с кодом. Приведенные примеры продемонстрируют, что такое хороший код (некоторые идеи вы, возможно, захотите применить в своем коде в будущем).

HowDoI

Проект HowDoI, написанный Бенджамином Гляйтсманом (Benjamin Gleitzman), станет отличной стартовой точкой нашей одиссеи, несмотря на то что он состоит менее чем из 300 строк.

Читаем сценарий, состоящий из одного файла

Сценарий обычно имеет четко определенные точку входа, параметры и точку выхода. Благодаря этому читать его проще, чем библиотеки, которые предоставляют API или фреймворк.

Загрузите модуль HowDoI с GitHub55:

$ 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

Документация к 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

Мы можем подтвердить, что понимаем, как работает 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

Если вы заглянете в каталог howdoi/, то увидите два файла: __init__.py, который состоит всего из одной строки, указывающей номер версии, и howdoi.py, который мы откроем и прочитаем.

Просматривая файл howdoi.py, мы увидим, что каждое новое определение функции использовано в следующей функции; это упрощает чтение кода. Каждая функция выполняет всего одну задачу (она вынесена в ее имя). Главная функция command_line_runner() располагается в нижней части файла howdoi.py.