Категория

Практика

Время на паре

Около 60 минут

Проверка

mypy, тесты, запуск

Результат

Проект с аннотациями, mypy app без ошибок

§1Задача

В главах 4.1–4.4 аннотации читались и проверялись в готовом коде второго архива: в 4.2 — как записать тип, в 4.3 — как запустить проверку, в 4.4 — как прочитать её сообщения. В этой главе их пишут самостоятельно. Первый архив темы — рабочий проект без аннотаций. Отчёт печатается, двенадцать тестов проходят, а mypy app находит семнадцать функций без типов. Задача: расставить аннотации у всех семнадцати, не меняя поведения программы, и получить от mypy ответ Success.

§2Подготовка

Работа идёт в папке первого архива, подготовленной в главе 4.1: окружение .venv создано, зависимости установлены. Перед началом выполните три шага.

1. Включите проверку в редакторе так же, как в главе 4.3: настройки, вкладка Workspace, параметр python.analysis.typeCheckingMode — значение basic. Проверьте, что выбран интерпретатор .venv.
2. Запустите проект и тесты: .venv/bin/python main.py.venv\Scripts\python main.py и .venv/bin/python -m pytest -q.venv\Scripts\python -m pytest -q. Запомните итог отчёта — 4 937,50 ₽ — и число тестов — 12 passed: после работы они должны остаться теми же.
3. Запустите .venv/bin/mypy app.venv\Scripts\mypy app. Семнадцать строк вывода — список работы; такой же вывод показан в главе 4.3, §8.

§3Порядок: от листьев к корню

Семнадцать функций лежат в десяти файлах, и первым решается вопрос, с какого файла начать. Модули проекта зависят друг от друга. Это видно по импортам: domain вызывает normalize_name из utils, services создаёт объекты Order из domain, а main.py вызывает services, ui и utils. Аннотации расставляют в обратном порядке — начиная с модулей, которые ничего из проекта не вызывают.

Файл main.py в архиве оставлен с аннотациями: его функция build_report(path: Path) -> list[str] служит образцом записи.

§4Как выбрать тип

Порядок файлов задан. Внутри каждого файла для каждой функции нужно решить, какие типы написать. Ответ ищется в трёх местах по очереди.

Когда сомнения остаются, ставят предполагаемый тип и запускают mypy: неверное предположение он покажет ошибкой в месте вызова. Для выражений внутри функции помогают наведение указателя на имя и временная строка reveal_type(...) — оба способа разобраны в главе 4.3, §9. Как записать найденный тип, показано в главе 4.2. Сообщения, которыми проверка отвечает на неверную запись, собраны в главе 4.4, §15.

§5Подсказки типа результата

Третье место из §4 — return — Pylance умеет читать сам: тип результата он выводит из тела функции. Выведенный тип можно показать прямо в коде — серой надписью после закрывающей скобки. Такую надпись называют подсказкой вставки (inlay hint): она не входит в текст файла, пока её не вставят.

Включите подсказки типа результата

Откройте настройки (Ctrl + ,, на macOS — Cmd + ,), вкладку Workspace, и введите в поиске inlay hints function return types. Поставьте флажок у параметра Python › Analysis › Inlay Hints: Function Return Types. В .vscode/settings.json появится строка "python.analysis.inlayHints.functionReturnTypes": true.

Откройте модуль и прочитайте подсказки

Откройте app/utils/formatter.py. После подписи каждой функции появится серый тип результата.

Вставьте подходящую подсказку двойным щелчком

Дважды щёлкните по серому -> str у format_kopeks: подсказка станет частью кода. Тип параметра Pylance не подсказывает, его пишут сами: def format_kopeks(kopeks: int) -> str:.

Подсказку -> Any не вставляют: Any выключает проверку, и в работах курса он запрещён. Сначала аннотируют параметры — text: str, width: int = 40, — и подсказка сменится на -> str: теперь известно, что text.center(...) вызывается у строки.

Перед вставкой подсказку сверяют с тем, что функция должна возвращать по смыслу: Pylance выводит тип из текущего тела, и если в теле ошибка, в подсказку попадёт неверный тип. После каждого пакета запускают mypy. Когда работа закончена, флажок можно снять.

§6Один модуль до и после

Как приёмы §4 и §5 работают вместе, видно на одном модуле целиком — app/services/orders.py из пакета services. В первом архиве mypy сообщает о нём три строки — по одной на функцию:

app/services/orders.py:7: error: Function is missing a type annotation  [no-untyped-def]
app/services/orders.py:14: error: Function is missing a type annotation  [no-untyped-def]
app/services/orders.py:26: error: Function is missing a type annotation  [no-untyped-def]

def load_orders(path):
    return [
        Order(waiter=row["waiter"], kopeks=int(row["kopeks"]))
        for row in read_rows(path)
    ]


def revenue_by_waiter(orders, top=0):
    ...
    totals = {}
    ...


def sort_orders_in_place(orders):
    orders.sort(key=lambda order: -order.kopeks)

def load_orders(path: Path) -> list[Order]:
    return [
        Order(waiter=row["waiter"], kopeks=int(row["kopeks"]))
        for row in read_rows(path)
    ]


def revenue_by_waiter(orders: list[Order], top: int = 0) -> dict[str, int]:
    ...
    totals: dict[str, int] = {}
    ...


def sort_orders_in_place(orders: list[Order]) -> None:
    orders.sort(key=lambda order: -order.kopeks)

Как выбраны типы. path — объект Path, так его передаёт main.py. Список orders содержит заказы: из элементов берут .waiter и .kopeks. sort_orders_in_place ничего не возвращает, поэтому -> None. Переменной totals нужна аннотация, потому что по пустому словарю {} тип ключей и значений не определить.

§7Трудные места проекта

Большинство функций проекта устроены как в orders.py: тип параметра виден из того, как его используют, тип результата — из return. В таблице собраны места, где решение не такое очевидное, и причина каждого решения.

§8Как уменьшается число ошибок

Работа идёт по пакетам в порядке §3, и после каждого пакета видно, сколько осталось. Запускайте .venv/bin/mypy app.venv\Scripts\mypy app. Число ошибок в последней строке вывода — ход работы. Ниже настоящие итоги прогонов при работе в порядке из §3:

Когда mypy ответил Success, проверьте, что поведение не изменилось: тесты и запуск должны дать то же, что в §2.

Получившийся проект совпадает со вторым архивом темы во всех файлах, кроме README, — это проверено сравнением. С этого проекта начинается следующая часть темы: в главе 4.6 в него добавляются описания.

§9Что сдаётся с пары

Работа закончена, когда выполнены все условия ниже; по ним её и проверяют.

§10Проверьте себя

Итог главы

Аннотации расставляют по пакетам, начиная с тех, что ничего из проекта не вызывают: utils, domain, services, ui. Тип параметра берут из того, как его используют и что передаёт вызывающий код, тип результата — из return или подсказки Pylance. После каждого пакета mypy показывает, сколько осталось: 17, 12, 8, 1, Success. Работа принята, когда проверка чистая, тесты проходят и отчёт не изменился; результат совпадает со вторым архивом, и с него начинается часть про документацию.

Категория

Практика

Время на паре

Около 60 минут

Проверка

go build, go vet, тесты, запуск

Результат

Проект собирается, go vet без замечаний

§1Задача

В главах 4.1–4.4 ошибки типов читались в маленьких файлах proba/main.go. В этой главе их исправляют в целом проекте. Первый архив темы — «Отчёт кафе», написанный так, как его написал бы человек, привыкший к Python: функция вызвана без аргумента, у которого «было значение по умолчанию», строка склеивается с числом, из двух результатов принят один. Компилятор Go такой код не собирает: в нём двенадцать ошибок в шести файлах.

Задача: исправить все двенадцать, не меняя подписей функций, и получить чистые go build ./... и go vet ./..., двенадцать проходящих тестов и тот же отчёт, что печатает второй архив.

§2Подготовка

1. Распакуйте первый архив и откройте папку otchet-kafe-go-oshibki в VS Code — ту, в которой лежит go.mod.
2. Откройте панель Problems (CtrlCmd + Shift + M). В ней двенадцать ошибок — список работы. Такой же кадр показан в главе 4.3, §8.
3. Выполните в терминале go build ./.... В ответе три ошибки пакета internal/utils: остальные пакеты компилятор пока не проверяет. Почему так — в §3.
4. Запустить проект и тесты сейчас нельзя: go run . и go test ./... начинают со сборки и останавливаются на тех же ошибках. Ожидаемый результат известен по второму архиву: итог отчёта 4 937,50 ₽, все тесты проходят.

§3Порядок: от листьев к корню

Двенадцать ошибок лежат в шести файлах четырёх пакетов, и первым решается вопрос, с какого пакета начать. Пакеты проекта зависят друг от друга. Это видно по импортам: domain вызывает NormalizeName из utils, services создаёт заказы из domain, а main.go вызывает services, ui и utils. Исправляют в том же порядке, в каком компилятор собирает пакеты, — начиная с тех, что ничего из проекта не импортируют.

Почему не начать с main.go, где ошибка одна? Начать можно — gopls показывает её в Problems. Но go build до неё не дойдёт, пока не собраны пакеты ниже, и проверить исправление сборкой будет нельзя. При работе снизу вверх каждый исправленный пакет сразу подтверждается командой.

§4Как найти исправление

Порядок пакетов задан. Для каждой ошибки нужно решить, что менять: место вызова или объявление. Правило практики — подписи функций не меняются: на них опираются тесты и другие пакеты, и подпись в этом проекте верная. Меняется код, который с подписью не согласован. Ответ ищется в трёх местах по очереди.

Когда исправление найдено, его сверяют с тем, что функция должна делать по смыслу: компилятор проверит типы, но не поведение. Поведение проверяют тесты в конце работы. Как записать нужный тип, показано в главе 4.2, а разборы похожих сообщений собраны в главе 4.4, §14.

§5Быстрые исправления gopls

Для части ошибок gopls предлагает готовое исправление. Значок лампочки слева от строки означает, что исправление есть. Вызывают его сочетанием CtrlCmd + . или командой палитры Quick Fix…, когда курсор стоит на подчёркнутой строке.

Быстрых исправлений для ошибок типов немного: Fill in return values, удаление лишнего импорта, объявление неизвестной переменной. Для большинства ошибок этого проекта исправления нет: какое значение нужно передать, решает разработчик. Перед тем как принять предложенное исправление, его читают: nil на месте ошибки верен, только если ошибки в этой ветке действительно нет.

§6Один пакет до и после

Как приёмы §4 и §5 работают вместе, видно на первом пакете — internal/utils. В нём три ошибки в двух файлах:

# example.com/otchet-kafe/internal/utils
internal/utils/formatter.go:18:9: invalid operation: strings.Join(groups, " ") + "," + cents (mismatched types string and int)
internal/utils/text.go:9:22: not enough arguments in call to strings.Join
	have ([]string)
	want ([]string, string)
internal/utils/text.go:16:30: cannot use word[0] (value of type byte) as rune value in argument to unicode.ToUpper

// formatter.go, строка 18
	return strings.Join(groups, " ") + "," + cents + " ₽"

// text.go, строка 9
	return strings.Join(strings.Fields(value))

// text.go, строка 16
		runes[0] = unicode.ToUpper(word[0])

// formatter.go, строка 18
	return strings.Join(groups, " ") + "," + strconv.Itoa(cents/10) + strconv.Itoa(cents%10) + " ₽"

// text.go, строка 9
	return strings.Join(strings.Fields(value), " ")

// text.go, строка 16
		runes[0] = unicode.ToUpper(runes[0])

Как выбраны исправления. В первой строке сообщение назвало типы — string and int: число нужно перевести в строку, и функция для этого в файле уже импортирована — strconv.Itoa. Во второй строки have и want показали недостающий аргумент типа string — это разделитель. В третьей сообщение сказало byte вместо rune: индекс строки в Go даёт байт, а кириллическая буква занимает в UTF-8 два байта, поэтому первый знак берут из среза []rune. Если исправить третью ошибку переводом rune(word[0]), программа соберётся, но «и» превратится в бессмысленный знак: компилятор такое исправление пропустит, а тест NormalizeName — нет.

§7Двенадцать ошибок проекта

В таблице все ошибки архива в порядке работы. Колонка «Привычка из Python» объясняет, откуда ошибка берётся: так эту строку написал бы человек, переносящий код с Python.

Две строки таблицы требуют пояснения. В orders.go:24 мало принять два результата: ошибку нужно проверить и вернуть наверх — if err != nil { return nil, err }, как это сделано тремя строками ниже для NewOrder. Иначе неверная сумма в файле превратится в ноль без сообщения. В orders.go:61 функция сравнения для slices.SortStableFunc возвращает не «да или нет», а число: отрицательное, если a должен стоять раньше b. Для сортировки по убыванию суммы это b.Kopeks - a.Kopeks.

§8Как меняется число ошибок

Работа идёт по пакетам в порядке §3, и после каждого пакета запускают go build ./.... Число ошибок в ответе меняется не так, как у mypy в ветке Python: оно сначала растёт. Ниже настоящие итоги прогонов при работе в порядке §3:

Число в панели Problems, напротив, уменьшается ровно на количество исправленных ошибок: 12, 9, 7, 1, 0. Если после правки оно не уменьшилось или выросло, значит, исправление внесло новую ошибку — она появится в панели рядом с местом правки.

Когда go build ничего не печатает, проверьте остальное четырьмя командами подряд:

$ go build ./... && go vet ./... && go test ./... && go run .

Получившийся проект совпадает со вторым архивом темы во всех файлах, кроме README: архив с ошибками собран из второго заменой двенадцати строк. С этого проекта начинается следующая часть темы: в главе 4.6 в него добавляются комментарии документации.

§9Что сдаётся с пары

Работа закончена, когда выполнены все условия ниже; по ним её и проверяют.

§10Проверьте себя

Итог главы

Ошибки типов исправляют по пакетам, начиная с тех, что ничего из проекта не импортируют: utils, domain, services, main.go. Исправление ищут в сообщении, в подписи вызываемой функции и в подписи своей; подписи не меняют, меняют несогласованный с ними код. Для части ошибок gopls предлагает быстрое исправление, но его читают перед тем, как принять. Число ошибок в терминале меняется как 3, 2, 6, 1, 0, потому что компилятор открывает пакеты по одному, а в панели Problems — уменьшается с 12 до 0. Работа принята, когда сборка, go vet и тесты чистые, отчёт не изменился, а все ошибки из результатов проверяются; результат совпадает со вторым архивом, и с него начинается часть про документацию.